[CryptoAPI] Documentation

Ricardo Silva

Question

Why did I make this component?

Some of you may be asking why I made this component, since Enterprise Manager already provides a Crypto library.

There are a couple of problems I found with the EnterpriseManager Crypto extension:

1) the encryption scheme used is relatively weak by today's standards. It is not Chosen Plaintext secure, which basically means it's possible to tell when ciphertexts relate to the same plaintext (with the same key), which leaks some information.

2) It uses custom implementations of some of the cryptographic primitives, which is generally a bad practice.

3) It does not use an authenticated encryption schema which means that your data may be tampered without you realizing it.

For reference, the EM Crypto extension uses AES in CBC mode with PKCS7 padding with fixed Initialization Vector. The key derivation for EM Crypto, for interoperability reasons, has custom code in the Java version.

Algorithms used

In this extension I have two encryption schemas. One for randomized encryption and another for deterministic encryption. Both of them provide authenticated encryption, meaning they'll let you know if the ciphertext has been tampered with.

Randomized encryption schema (Encrypt/Decrypt Actions): AES with 256 bit key in CBC mode with PKCS7 padding and randomized Initialization Vector + HMACSHA256 for integrity. I use the same key for confidentiality and integrity. Ciphertext is Base64Encode(iv || E(iv,k,plaintext) || mac(k, iv || E(iv,k,plaintext))

Deterministic encryption schema (Det_Encrypt/Det_Decrypt Actions): AES with 256 bit key in CBC mode with PKCS7 padding and Synthetic Initialization vector taken from the first 16 bytes of the HMACSHA256 mac of the plaintext. I use the same key for confidentiality and integrity. Ciphertext is Base64Encode( MSB(128, mac(k, plaintext)) || E(iv, k, plaintext) ) where MSB(b, v) stands for the b most significant bits (left-most) of v.

Asymmetric encryption schema uses RSA with OAEP padding with the common MFG1 and SHA1 functions as parameters.

Integrity schema (ComputeMac action): HMACSHA256 with 256 bit key.

Key derivation (DeriveKey action): RFC 2898 PBKDF2 with fixed 128 byte salt using HMACSha1 as the underlying mac algorithm with 37649 iterations.

All crypto implementations are taken from either .NET framework crypto library or from bouncy castle (in Java).

Data (strings) are utf-8 encoded prior to encryption and utf-8 decoded upon decryption.

Bulk processing

If you want to process a lot of data with the same key, you can use the K* version of the actions to avoid deriving the key for each encryption/mac. This is also one of the reasons why key derivation uses a fixed salt. If the salt was unique per encryption you couldn't bulk process anything since you couldn't pre-process the key.

What should I use?

If you're looking to just encrypt some data, you should use the Encrypt family of actions.

If you want to add some encrypted field as searchable, you can use the Det_Encrypt family of actions. In order to maintain security you should make sure that you do not use the same key to encrypt the same data twice on the database (the attribute holding the encrypted data should have a unique constraint)

Further discussion.

28 Jul 2013

Robert Chanphakeo

Ricardo, love your work!

29 Jul 2013

Tim Timperman

Great extension.
Just 1 remark/question; the "DeriveKey" action seems to consistently take somewhere between 700ms and 1200ms. Anyone else noticing this?

14 Feb 2014

Ricardo Silva

Hello Tim,

sorry for the late reply, but yes: key derivation is meant to be slow (to prevent brute force attacks). As the action says, it does 37649 hmacsha1 operations.

Best regards,
Ricardo Silva

22 Sep 2014

MVP

erm,

silly me, any examples?

i want encrypt a password with HMAC-SHA256 and compare it with a password i got (which i know is samely encrypted with ofcourse the same shared key)

25 Nov 2014

Ricardo Silva

Crypto API purposefully only covers symmetric encryption schemas, and doesn't have any support for one-way MACs or functions, so your specific use-case will not be possible with Crypto API.

The closest you have here would be the deterministic encryption schema, but that is a two-way cipher. For storing passwords you should try and use one-way hash functions (SHA256, MAC's).

25 Nov 2014

Fábio Silva

Staff

Hi guys. I don't know if it helps the discussion, but I came across with the necessity of performing strong one-way hasing on OutSystems platform to develop a component that resembles an OAuth 2.0 provider.
I used CryptoAPI and used the function that encrypts data with a password, being the password a concatenation of two GeneratePassword(10,true) functions.
As the two GeneratePassword functions will yield a pseudo-random string with 10 characters (numbers and letters), I believe that the 20 characters will be enough (I called twice the function so that I had two different seeds and, in theory, have a bit more "random" string).
As in my code, the GeneratePassword() calls are inside the encrypt funcion of CryptoAPI, there's no way for an user to know the key that the original string was encrypted with.

Naturally I know that this only works for fixed-length inputs as this is not a normal "Hash" (MD5, SHA-1, SHA256) function that will only returns fixed-length outputs for any input length, but if you, like me, are working with security tokens, it is good enough.

One suggestion that I leave for Ricardo here would be to implement simple SHA256 Hashing functions to this extension. It would be a god send for most of us that use it.

Hope it helps.
Fábio

26 Nov 2014

Ricardo Silva

Hello Statler,

I have just added a new version of this component which supports password hashing out of the box.

It has two functions: HashPassword and ComparePassword. You can use the first to securely hash a password for storage in a database ( SHA512 with random 24 byte salt ) and the second to compare an existing hash to see if it matches a given password.

Using HMAC for this kind of use is weird as it requires an extra key to be known on both sides.

This should cover your password needs, let me know if you have further questions regarding this.

@ Fábio, SHA256 is also now implemented in CryptoAPI.

Best regards,
Ricardo Silva

30 Nov 2014

MVP

Hi,

I might need to encrypt some data-columns in my database (customernames)
I am curious how to approach this. where should I store my public/private key?

I am thinking of creating some keys on my dev-environment and store the key in my espace?
different keys for acc, production and test?

14 Apr 2015

Ricardo Silva

Hello Statler & Waldorf. I have answered that question in a separate thread.

14 Apr 2015

Vanderson de Moura Vauruk

Ricardo I need yout help.

I need encryption a string , example:
string for encyption -

login=1009512&senha=minhasenha&data=2015-05-20T09:15:38-03:00

format RSA-SHA256 and using key públic in file XML or PEM.

and convert in Base64

How i do? its api enables this?

thanks!

24 Sep 2015

Tarun Kumar

what does KEncrypt and KDecrypt function parameters ,can u give me an example for both

I mean to say Inwhat Format both are passed

20 Jan 2016

Ricardo Silva

KEncrypt takes two parameters, a key ( Binary Data ) and text to encrypt.

You can generate the key by using the GenerateAESKey function.

KDecrypt takes a result from KEncrypt and a key (the same that was used to encrypt) to turn the encrypted text into the text again.

20 Jan 2016

Shirly Ezer

Hi,

I am using the Det_Encrypt/Det_Decrypt actions and I need to understand what is the password meaning.

What I am trying to do is implement these actions in java using the bouncy castle library.

In my application the server will encrypt some info and I will need to decrypt it and dispaly it.

Can you explain what the password do?

16 Mar 2017

Ricardo Silva

Hello there,

CryptoAPI has a Java implementation, so you can just open it using your Eclipse and take it from there.

This is also available on my Github (with an added implementation for Python).

Best regards,

Ricardo Silva

16 Mar 2017

Adam Esterle

Ricardo,

You say "If you want to add some encrypted field as searchable..." Does that mean on the entity?

Basically I need to be able to do Entity.EncryptedColumn like '%keyword%'

How would I get that to work?

17 Apr 2017

Ricardo Silva

Hello Adam,

Unfortunately, this mode of encryption would only support equality searches, not wildcard.

Since the data is encrypted, we can only check for equality. There will be no further information we can use as to the structure of the encrypted data.

There may be other techniques that are able to achieve that, but the one I used in my component is not one such technique.

19 Apr 2017

Adam Esterle

Thank you Ricardo!

Is it possible to encrypt binary data? It looks like only text is possible.

Is there anything to convert binary to text?

27 Apr 2017

Gadar S

Hi Ricardo,

The cipher text from this lib cannot be decrypted with Java and .Net standard lib. Ardo crypto code that is provided somewhere has to be used to decrypt. Is that correct understanding?

21 Dec 2018

Ricardo Silva

I think I don't understand your question.

This is running on .NET and Java, using only standard functions and available algorithms. You can decrypt this using those standard functions and algorithms if you follow the encryption schema specifications I posted on the first post.

Given these specifications you should be able to build encryptors and decryptors for any language that supports AES in CBC mode, or even implement AES and CBC mode yourself given the specification.

If you are using Java, .NET or python, you can use the libraries I have already provided for those languages which save you the trouble of reimplementing all of this. You can find those in by GitHub.

21 Dec 2018

Chanyut Luesiripanit

Is CryptoAPI support SHA3 hash?

13 Aug 2020

Frederick Lozano

Hi Ricado,

i'm using this API to decryp a password from a QR code and it work perfect but at some point im gettin a decryption failed error, invalid lenght for base-64 char and the input is not valid base-64 string at random moments.

any sugestions?

Thanks a lot.

18 Aug 2020

Bruno Yamada

Can I use Deterministic encryption schema (Det_Encrypt/Det_Decrypt Actions) in version OS10? If Yes how to use it? I don't see any Det_Encrypt/Det_Decrypt Actions there, thank you.

07 Jul 2021

https://codono.com/

give me more tips......

16 Sep 2022

Community GuidelinesBe kind and respectful, give credit to the original source of content, and search for duplicates before posting.

See the full guidelines