Generates a password-based encryption key, based on the PKCS#5/RFC 2898 standard, and returns the key as a RAW value.
Note: If PBE-ALGORITHM attribute is set to PBKDF2, then a PBKDF2 key derivation algorithm approved by the National Institute of Standards and Technology (NIST) is used instead.

Syntax

GENERATE-PBE-KEY( password[ , salt] )
password
The password (a binary value) to use in generating the encryption key. This value may be of type CHARACTER, LONGCHAR, RAW, or MEMPTR. If the password contains a CHARACTER or LONGCHAR value, the AVM converts it to UTF-8 (which maintains a consistent value regardless of code page settings) before using it to generate the encryption key. To avoid this automatic conversion, specify a RAW or MEMPTR value. If you specify the Unknown value (?), the result is the Unknown value (?).
salt
An optional RAW expression that evaluates to the salt value (a random series of bytes) to use in generating the encryption key. If you specify the Unknown value (?), the current value of the ENCRYPTION-SALT attribute is used. If no salt value is specified in the ENCRYPTION-SALT attribute, no salt value is used.

The salt length is 8 bytes if PBE-ALGORITHM is Legacy and up to 512 bytes if PBE-ALGORITHM is PBKDF2.

You can also use the GENERATE-PBE-SALT or GENERATE-SALT functions to generate a salt value, which helps promote the uniqueness of the password key value.

If specified, this salt value is combined with the password value and hashed some number of times to generate a password-based encryption key (using the algorithm specified by the PBE-HASH-ALGORITHM attribute and the number of iterations specified by the PBE-KEY-ROUNDS attribute).

Note: If FIPS mode is enabled, GENERATE-PBE-KEY requires a 16 to 512-byte salt value, whether specified using the salt parameter, or set through the ENCRYPTION-SALT attribute. The PBE-ALGORITHM attribute must also be set to PBKDF2.

Notes

  • You are responsible for generating, storing, and transporting these values.
  • The size of the generated encryption key is determined by the cryptographic algorithm specified by the SYMMETRIC-ENCRYPTION-ALGORITHM attribute.
  • Before invoking this function, be sure to set the PBE-HASH-ALGORITHM attribute to the name of the hash algorithm to use.
  • If you call this function multiple times with the same password string, hash algorithm, number of iterations, and salt value, the same binary key is generated each time.
  • If PBE-ALGORITHM is set to PBKDF2, the hashing algorithms specified in PBE-HASH-ALGORITHM and SYMMETRIC-ENCRYPTION-ALGORITHM must be approved by the National Institute of Standards and Technology (NIST).
  • If FIPS mode is enabled and a non NIST-approved algorithm is set, the AVM generates a run-time error.

See also

GENERATE-PBE-SALT function, GENERATE-SALT function, GENERATE-RANDOM-KEY function, MESSAGE-DIGEST function, PBE-ALGORITHM attribute, PBE-HASH-ALGORITHM attribute, SECURITY-POLICY system handle, SYMMETRIC-ENCRYPTION-ALGORITHM attribute