9.58 ENCRYPT

A companion Built-in Function, 9.35 DECRYPT, is used to decode the encrypted text string.

Warning: From LANSA V11 SP4 onward, a blank key won't be used to encrypt. A generated key will be used instead if the key argument is passed with all blanks. In versions prior to V11 SP4, encrypt will have a key of all spaces.

LANSA for i

YES

Visual LANSA for Windows

YES

Visual LANSA for Linux

YES

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

u

Req

Text to be encrypted

8

Unlimited

2

N

Req

Length of text to be encrypted

The value for this length argument must be a multiple of 8.

The value provided for this argument must not be greater than the length of Argument 1 (text to be encrypted).

1

11

0

0

3

u

Opt

Key to be used for encryption

If a key is not provided for the encryption, a key will be generated and returned.

The key used for encryption must be saved and provided to the DECRYPT Built-In Function.

The current encryption cipher uses 16 bytes/128 bits key. The last 16 bytes are reserved for future use.

If a Unicode field type is used it is converted to UTF-8 and truncated to 32 bytes. If the key is not provided, and if return value 3 is a Unicode field type, then a Unicode key is generated. This key is converted to UTF-8 and truncated to 32 bytes. Alternatively, a key may be automatically generated using a Unicode field for the key, but setting it to an empty string.

Cipher block encryption algorithms always encrypt and decrypt blocks of 8 characters. Therefore the actual value you encrypt must have a length that is a multiple of 8.

The encrypted data returned by the encryption algorithm is binary data and can contain any value. As such, using it or passing it through environments where it may be subject to code page conversion (eg: database managers, communications links, etc) or where special characters like CR, LF or binary zero may cause issues (eg: HTML or XML documents, string processing, stream file processing, etc) may prove to be problematic. As such it is recommended that encrypted data is physically stored in hexadecimal format.

Unicode fields are converted to UTF-8 before encryption. This allows a Unicode field to be encrypted on one platform and decrypted on another. It also means that the encryption length (argument 2) can be up to 3 times the length of the text to be encrypted (argument 1). And then if the result is stored in hex it's further doubled in size. So if you have a 500 character NVarchar then the encrypted length should be 1500 and the size of the returned encrypted text should be 3000. If you do not have the lengths in this ratio then data may be lost.

Examples

Following are two RDML subroutines that demonstrate a generic encryption technique for any information up to 16 characters in length.

Note that even though the subroutine parameter #PROD_NUM is a char 10 field, the resulting encryption field #PROD_ENC is char 32.

This is because the initial binary encryption requires an input that is a multiple of 8 (ie: char 10 #PROD_NUM is padded with blanks to be 16 bytes long by the subroutine execution) and it produces a hexadecimal representation of the encrypted binary data, which is therefore 32 bytes long.

All 32 bytes of #PROD_ENC need to be stored for successful decryption to occur later.

To decrypt these values you would code EXECUTE DECRYPT (#KEY #PROD_ENC #PROD_NUM).

Here the 32 byte hexadecimal value is first converted to binary, decrypted and then returned as a char 16.

The subroutine finally returns the decrypted value right truncated into #PROD_NUM as a char 10.

ENCRYPT a value with a supplied key and return a 32 byte encrypted value in hex