OpenBSD manual page server

Configuration controls

EVP_CTRL_GCM_SET_IVLEN

Set the length of the initialization vector to arg bytes; the ptr argument is ignored and passing NULL is recommended. This call can only be made before specifying an initialization vector. If not called, the default IV length of 12 bytes is used.

Using this control command is discouraged because section 5.2.1.1 of the specification explicitly recommends that implementations of GCM restrict support to the default IV length of 12 bytes for interoperability, efficiency, and simplicity of design.

EVP_CTRL_GCM_SET_IV_FIXED

Usually, -1 is passed for arg. In that case, the complete initialization vector is copied from ptr.

Otherwise, set the fixed field at the beginning of the initialization vector to the arg bytes pointed to by ptr. When encrypting, also generate the remaining bytes of the initialization vector at random. It is an error to specify an arg that is less than 4 or so large that less than 8 bytes remain.

Encryption controls

EVP_CTRL_GCM_IV_GEN

Generate the precounter block from the initialization vector, copy the last arg bytes of the initialization vector to the location pointed to by ptr, or all of it if arg is less than 1 or greater than the length of the initialization vector, and increment the initialization vector by 1. Incrementing ignores the IV length and the fixed field length that may have been configured earlier and always operates on the last eight bytes of the initialization vector. It is an error to issue this command when no key or no initialization vector is set.

EVP_CTRL_GCM_GET_TAG

Write arg bytes of the tag value to the location pointed to by ptr. This control command only makes sense after all data has been processed, e.g. after calling EVP_EncryptFinal(3). It is an error to issue this command while decrypting, before any data has been processed, or to specify an arg that is less than 1 or greater than 16.

To specify any additional authenticated data (AAD), call EVP_EncryptUpdate(3) with the out argument set to NULL.

Decryption controls

EVP_CTRL_GCM_SET_IV_INV

Copy arg bytes from ptr to the last bytes of the initialization vector and generate the precounter block from the initialization vector. The library does not check whether the arguments are consistent with the configured initialization vector and fixed field lengths. When default lengths are in use, pass 8 for arg. In that case, this control command sets the invocation field. It is an error to issue this command when no key or no initialization vector is set, or when encrypting.

EVP_CTRL_GCM_SET_TAG

Set the expected tag to the arg bytes located at ptr. This control command is mandatory before any data is processed, e.g. before calling EVP_DecryptUpdate(3). It is an error to issue this command while encrypting or to specify an arg that is less than 1 or greater than 16.

To specify any additional authenticated data (AAD), call EVP_DecryptUpdate(3) with the out argument set to NULL.

If the return value of EVP_DecryptFinal(3), EVP_DecryptFinal_ex(3), EVP_CipherFinal(3), or EVP_CipherFinal_ex(3) does not indicate success when decrypting, the authentication operation failed. In that case, regard any output data as corrupted.