GENERATE-PBE-KEY function

Generates a password-based encryption key, based on the PKCS#5/RFC 2898 standard, and returns the key as a RAW value.

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 ensures 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 8 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.

You can also use the GENERATE-PBE-SALT function to generate a salt value, which can help to ensure that the password key value is unique.

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).

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.