This section shows basic uses of the ABL symmetric cryptography functions and related ABL elements.

The following example shows the use of a random binary key to encrypt the text "Bathtub Pancake Ladybug".

Example 1: Encryption using a random binary key

DEFINE VARIABLE binary-key   AS RAW       NO-UNDO.
DEFINE VARIABLE clear-text   AS CHARACTER NO-UNDO
  INITIAL "Bathtub Pancake Ladybug".
DEFINE VARIABLE crypto-value AS RAW       NO-UNDO.

binary-key = GENERATE-RANDOM-KEY.
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY = binary-key.
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV = ?.

crypto-value = Encrypt (clear-text).

For the receiver of the crypto-value to be able to successfully decrypt the value and recover the clear text requires the following information:

  1. The name of the algorithm (the default, AES_CBC_128, used and obtained by reading SECURITY-POLICY:SYMMETRIC-ENCRYPTION-ALGORITHM)
  2. The initialization vector (none used, but available by reading SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV)
  3. The binary key value
    Note: Setting SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY directly from the GENERATE-RANDOM-KEY function leads to an irrecoverable key because this attribute is write-only and GENERATE-RANDOM-KEY returns a different value if called again.

The following example shows the use of a binary key to decrypt the text from the previous example.

Example 2: Decryption using a random binary key

DEFINE VARIABLE binary-key   AS RAW       NO-UNDO.
DEFINE VARIABLE clear-text   AS CHARACTER NO-UNDO.
DEFINE VARIABLE crypto-value AS RAW       NO-UNDO.
/* binary-key is set to the same value as in the previous example */
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY = binary-key.
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV = ?.
/* crypto-value is obtained by some means */
clear-text = GET-STRING(DECRYPT(crypto-value), 1).

The following example shows the use of a password-based key to encrypt the text, "Matter Property Mass Solid". The password is "Migratory Blueberries".

Example 3: Encryption using a password-based key

DEFINE OUTPUT PARAMETER salt-value AS RAW NO-UNDO.
DEFINE VARIABLE password     AS CHARACTER NO-UNDO
  INITIAL "Migratory Blueberries".
DEFINE VARIABLE clear-text   AS CHARACTER NO-UNDO
  INITIAL "Matter Property Mass Solid".
DEFINE VARIABLE crypto-value AS RAW       NO-UNDO.
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-ALGORITHM = "AES_CBC_256".
SECURITY-POLICY:PBE-KEY-ROUNDS                 = 2000.
SECURITY-POLICY:PBE-HASH-ALGORITHM             = "SHA-256".
SECURITY-POLICY:ENCRYPTION-SALT                = GENERATE-PBE-SALT.
/* The salt value is passed as an OUTPUT parameter for use by the
 * following password decryption example */
salt-value = SECURITY-POLICY:ENCRYPTION-SALT.
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY = GENERATE-PBE-KEY (password).
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV  = ?.
crypto-value = ENCRYPT (clear-text).

For the receiver of the crypto-value to be able to successfully decrypt the value and recover the clear text, the following information is necessary:

  1. The name of the algorithm (a non-default value specified and obtained by reading SECURITY-POLICY:SYMMETRIC-ENCRYPTION-ALGORITHM)
  2. The initialization vector (none is used, but can be set using SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV)
  3. The number of hashing algorithm iterations to generate the key (a non-default value specified and obtained by reading SECURITY-POLICY:PBE-KEY-ROUNDS)
  4. The salt value (obtained by reading SECURITY-POLICY:ENCRYPTION-SALT)
    Note: Calling GENERATE-PBE-SALT function again produces a different salt value and is not useful in generating the binary key necessary to decrypt the text.
  5. The hash algorithm used to transform the password into the binary key (a non-default value specified and obtained by reading SECURITY-POLICY:PBE-HASH-ALGORITHM)
  6. The password text

In place of items mentioned in points 3 through 6, the binary key value itself can be supplied. Because SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY is write-only, an intermediate RAW variable can be used to hold the value returned from the GENERATE-PBE-KEY function, or the function may be called again with the same password value (it will return the same result provided the SECURITY-POLICY system handle attributes SYMMETRIC-ENCRYPTION-ALGORITHM, PBE-KEY-ROUNDS, PBE-HASH-ALGORITHM, and ENCRYPTION-SALT all have the same values).

The following example shows the use of a password-based key to decrypt the text from the previous example. The password is "Migratory Blueberries".

Example 4: Decryption using a password-based key

/* The salt value from the previous password encryption example is passed in
   as an INPUT parameter */
DEFINE INPUT PARAMETER salt-value AS RAW NO-UNDO.
DEFINE VARIABLE clear-text   AS CHARACTER NO-UNDO.
DEFINE VARIABLE crypto-value AS RAW       NO-UNDO.
/* The password is most likely obtained from the user and not in the code as
   shown here. */
DEFINE VARIABLE password     AS CHARACTER NO-UNDO
  INITIAL "Migratory Blueberries".
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-ALGORITHM = "AES_CBC_256".
SECURITY-POLICY:PBE-KEY-ROUNDS                 = 2000.
SECURITY-POLICY:PBE-HASH-ALGORITHM             = "SHA-256".
SECURITY-POLICY:ENCRYPTION-SALT                = salt-value.
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-KEY       = GENERATE-PBE-KEY(password).
SECURITY-POLICY:SYMMETRIC-ENCRYPTION-IV        = ?.
/* crypto-value is obtained by some means */
clear-text = DECRYPT (crypto-value).