Crypto Functions

Overview

This page documents the built-in functions that are available for encrypting and decrypting data and for managing custom encryption keys. All built-in methods described below are available on the Mez namespace.

`createCryptoKey`

The Mez:createCryptoKey built-in function will create a named crypto key that is app specific and can optionally be used by the encrypt and decrypt built-in functions described below.

It expects two string arguments both of which are required.

The first argument represents the name of the crypto key to be created. This name will be the only future reference to the key. Duplicate key names per app are not allowed.
The second argument represents the AES key that will be used to encrypt and decrypt values.
- This is required to be a 128 bit string.
- The key itself will be stored in the app schema and in Helium's core database as an encrypted (and base64 encoded) value itself. Once a key has been created it can only be referenced by the encrypt and decrypt built-in functions below using the key's name. There is no mechanism exposed that will allow the actual unencrypted key value to be inspected after it has been created.
- "default" is a reserved key name and cannot be used for keys created using this built-in function.

Mez:createCryptoKey("mykey","Thats my kung fu");

While the example shows the Mez:createCryptoKey built-in function being supplied with two string literals as arguments, any statement that evaluates to a string is allowed.

It's worth noting that the request to create a crypto key is written to the app schema in a built-in table named __crypto_create_key_request__. This request will then be processed by Helium and an entry for the key will be created in the Helium core database. Once written to the Helium core database the __crypto_create_key_request__ record will never be used internally by Helium. The values can however be queried by the app using a normal selector:

__crypto_create_key_request__[] cryptoKeyCreateRequests = __crypto_create_key_request__:all();

for(int i = 0; i < cryptoKeyCreateRequests.length(); i++) {
    __crypto_create_key_request__ cryptoKeyCreateRequest = cryptoKeyCreateRequests.get(i);
    string keyName = cryptoKeyCreateRequest.name;
	...
}

This allows applications to check previous requests for creation of crypto keys and as such can provide a reference to the keys that are available for the app.

`encrypt`

The Mez:encrypt built-in function will generate an encrypted value based on the provided arguments. Two arguments can be provided, one of which is optional:

The first argument is the value that needs to be encrypted. This is required.
The second argument represents a key name for a key that was previously created. If no value is specified here a default app specific key will be used.

// Using the default key
string ecryptedVaue1 = Mez:encrypt("A value that I want to encrypt");

// Overloaded version using a previously created key
string ecryptedVaue2 = Mez:encrypt("A value that I want to encrypt", "mykey");

While the example shows the Mez:encrypt built-in function being supplied with two string literals as arguments, any statement that evaluates to a string is allowed.

Additionally the resulting encrypted values are also base64 encoded before being returned by the function.

`decrypt`

The Mez:decrypt built-in function will decrypt a previously encrypted value based on the provided arguments. Two arguments can be provided, one of which is optional:

The first argument is the value that needs to be decrypted. This is required.
The second argument represents a key name for a key that was previously created. If no value is specified here a default app specific key will be used.

// Using the default key
string decryptedValue1 = Mez:decrypt("qMnV303QDPQUZJFnFLNMfbTpUe920z2vatsWeQ9izf0=");

// Overloaded version using a previously created key
string decryptedValue2 = Mez:decrypt("qMnV303QDPQUZJFnFLNMfbTpUe920z2vatsWeQ9izf0=", "mykey");