*** UNIX MANUAL PAGE BROWSER ***

EVP_AES_128_GCM(3) FreeBSD Library Functions Manual EVP_AES_128_GCM(3) NAME EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm - EVP AES cipher in Galois Counter Mode SYNOPSIS #include <openssl/evp.h> const EVP_CIPHER * EVP_aes_128_gcm(void); const EVP_CIPHER * EVP_aes_192_gcm(void); const EVP_CIPHER * EVP_aes_256_gcm(void); DESCRIPTION EVP_aes_128_gcm(), EVP_aes_192_gcm(), and EVP_aes_256_gcm() provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit keys in and Galois Counter Mode in the evp(3) framework. For GCM mode ciphers, the behaviour of the EVP interface is subtly altered and several additional EVP_CIPHER_CTX_ctrl(3) operations are required to function correctly. Some of the EVP_CTRL_GCM_* control commands are older aliases for corresponding EVP_CTRL_AEAD_* constants as indicated below. To avoid using the cumbersome and error-prone API documented in the present manual page, consider using the functions documented in EVP_AEAD_CTX_init(3) instead. Configuration controls EVP_CTRL_AEAD_SET_IVLEN (== 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_AEAD_SET_IV_FIXED (== 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_AEAD_GET_TAG (== 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_AEAD_SET_TAG (== 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. SEE ALSO AES_encrypt(3), evp(3), EVP_AEAD_CTX_init(3), EVP_aes_128_cbc(3), EVP_CIPHER_CTX_ctrl(3), EVP_EncryptInit(3) STANDARDS Morris Dworkin, National Institute of Standards and Technology, Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC, NIST Special Publication 800-38D, Gaithersburg, Maryland, November 2007. HISTORY EVP_aes_128_gcm(), EVP_aes_192_gcm(), and EVP_aes_256_gcm() first appeared in OpenSSL 1.0.1 and have been available since OpenBSD 5.3. FreeBSD 14.1-RELEASE-p8 December 29, 2024 FreeBSD 14.1-RELEASE-p8