1.\" $OpenBSD: EVP_aes_128_gcm.3,v 1.2 2024/12/29 12:27:28 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100 4.\" OpenSSL EVP_aes.pod a1ec85c1 Apr 21 10:49:12 2020 +0100 5.\" 6.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.\" This file is a derived work containing a few sentences 21.\" written by Dr. Stephen Henson <steve@openssl.org> 22.\" covered by the following license: 23.\" 24.\" Copyright (c) 2012 The OpenSSL Project. All rights reserved. 25.\" 26.\" Redistribution and use in source and binary forms, with or without 27.\" modification, are permitted provided that the following conditions 28.\" are met: 29.\" 30.\" 1. Redistributions of source code must retain the above copyright 31.\" notice, this list of conditions and the following disclaimer. 32.\" 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in 35.\" the documentation and/or other materials provided with the 36.\" distribution. 37.\" 38.\" 3. All advertising materials mentioning features or use of this 39.\" software must display the following acknowledgment: 40.\" "This product includes software developed by the OpenSSL Project 41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 42.\" 43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 44.\" endorse or promote products derived from this software without 45.\" prior written permission. For written permission, please contact 46.\" openssl-core@openssl.org. 47.\" 48.\" 5. Products derived from this software may not be called "OpenSSL" 49.\" nor may "OpenSSL" appear in their names without prior written 50.\" permission of the OpenSSL Project. 51.\" 52.\" 6. Redistributions of any form whatsoever must retain the following 53.\" acknowledgment: 54.\" "This product includes software developed by the OpenSSL Project 55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 69.\" 70.Dd $Mdocdate: December 29 2024 $ 71.Dt EVP_AES_128_GCM 3 72.Os 73.Sh NAME 74.Nm EVP_aes_128_gcm , 75.Nm EVP_aes_192_gcm , 76.Nm EVP_aes_256_gcm 77.Nd EVP AES cipher in Galois Counter Mode 78.Sh SYNOPSIS 79.In openssl/evp.h 80.Ft const EVP_CIPHER * 81.Fn EVP_aes_128_gcm void 82.Ft const EVP_CIPHER * 83.Fn EVP_aes_192_gcm void 84.Ft const EVP_CIPHER * 85.Fn EVP_aes_256_gcm void 86.Sh DESCRIPTION 87.Fn EVP_aes_128_gcm , 88.Fn EVP_aes_192_gcm , 89and 90.Fn EVP_aes_256_gcm 91provide the Advanced Encryption Standard algorithm for 128, 192 and 256-bit 92keys in and Galois Counter Mode in the 93.Xr evp 3 94framework. 95.Pp 96For GCM mode ciphers, the behaviour of the EVP interface is subtly 97altered and several additional 98.Xr EVP_CIPHER_CTX_ctrl 3 99operations are required to function correctly. 100Some of the 101.Dv EVP_CTRL_GCM_* 102control commands are older aliases for corresponding 103.Dv EVP_CTRL_AEAD_* 104constants as indicated below. 105.Pp 106To avoid using the cumbersome and error-prone API documented 107in the present manual page, consider using the functions documented in 108.Xr EVP_AEAD_CTX_init 3 109instead. 110.Ss Configuration controls 111.\" The following constants are intentionally undocumented 112.\" because they are very rarely used in application programs: 113.\" EVP_GCM_TLS_FIXED_IV_LEN (unused in the library) 114.\" EVP_GCM_TLS_EXPLICIT_IV_LEN and EVP_GCM_TLS_TAG_LEN (used internally 115.\" only in aes_gcm_tls_cipher(), which is unused) 116.Bl -tag -width Ds 117.It Dv EVP_CTRL_AEAD_SET_IVLEN Pq == Dv EVP_CTRL_GCM_SET_IVLEN 118Set the length of the initialization vector to 119.Fa arg 120bytes; the 121.Fa ptr 122argument is ignored and passing 123.Dv NULL 124is recommended. 125This call can only be made before specifying an initialization vector. 126If not called, the default IV length of 12 bytes is used. 127.Pp 128Using this control command is discouraged because section 5.2.1.1 of the 129specification explicitly recommends that implementations of GCM restrict 130support to the default IV length of 12 bytes for interoperability, 131efficiency, and simplicity of design. 132.It Dv EVP_CTRL_AEAD_SET_IV_FIXED Pq == Dv EVP_CTRL_GCM_SET_IV_FIXED 133Usually, \-1 is passed for 134.Fa arg . 135In that case, the complete initialization vector is copied from 136.Fa ptr . 137.Pp 138Otherwise, set the fixed field at the beginning of the initialization 139vector to the 140.Fa arg 141bytes pointed to by 142.Fa ptr . 143When encrypting, also generate the remaining bytes 144of the initialization vector at random. 145It is an error to specify an 146.Fa arg 147that is less than 4 or so large that less than 8 bytes remain. 148.El 149.Ss Encryption controls 150.Bl -tag -width Ds 151.It Dv EVP_CTRL_GCM_IV_GEN 152Generate the precounter block from the initialization vector, 153copy the last 154.Fa arg 155bytes of the initialization vector to the location pointed to by 156.Fa ptr , 157or all of it if 158.Fa arg 159is less than 1 or greater than the length of the initialization vector, 160and increment the initialization vector by 1. 161Incrementing ignores the IV length and the fixed field length 162that may have been configured earlier and always operates on the 163last eight bytes of the initialization vector. 164It is an error to issue this command 165when no key or no initialization vector is set. 166.It Dv EVP_CTRL_AEAD_GET_TAG Pq == Dv EVP_CTRL_GCM_GET_TAG 167Write 168.Fa arg 169bytes of the tag value to the location pointed to by 170.Fa ptr . 171This control command only makes sense after all data has been processed, 172e.g. after calling 173.Xr EVP_EncryptFinal 3 . 174It is an error to issue this command while decrypting, 175before any data has been processed, or to specify an 176.Fa arg 177that is less than 1 or greater than 16. 178.El 179.Pp 180To specify any additional authenticated data (AAD), call 181.Xr EVP_EncryptUpdate 3 182with the 183.Fa out 184argument set to 185.Dv NULL . 186.Ss Decryption controls 187.Bl -tag -width Ds 188.It Dv EVP_CTRL_GCM_SET_IV_INV 189Copy 190.Fa arg 191bytes from 192.Fa ptr 193to the last bytes of the initialization vector 194and generate the precounter block from the initialization vector. 195The library does not check whether the arguments are consistent 196with the configured initialization vector and fixed field lengths. 197When default lengths are in use, pass 8 for 198.Fa arg . 199In that case, this control command sets the invocation field. 200It is an error to issue this command 201when no key or no initialization vector is set, or when encrypting. 202.It Dv EVP_CTRL_AEAD_SET_TAG Pq == Dv EVP_CTRL_GCM_SET_TAG 203Set the expected tag to the 204.Fa arg 205bytes located at 206.Fa ptr . 207This control command is mandatory before any data is processed, 208e.g. before calling 209.Xr EVP_DecryptUpdate 3 . 210It is an error to issue this command while encrypting or to specify an 211.Fa arg 212that is less than 1 or greater than 16. 213.El 214.Pp 215To specify any additional authenticated data (AAD), call 216.Xr EVP_DecryptUpdate 3 217with the 218.Fa out 219argument set to 220.Dv NULL . 221.Pp 222If the return value of 223.Xr EVP_DecryptFinal 3 , 224.Xr EVP_DecryptFinal_ex 3 , 225.Xr EVP_CipherFinal 3 , 226or 227.Xr EVP_CipherFinal_ex 3 228does not indicate success when decrypting, 229the authentication operation failed. 230In that case, regard any output data as corrupted. 231.Sh SEE ALSO 232.Xr AES_encrypt 3 , 233.Xr evp 3 , 234.Xr EVP_AEAD_CTX_init 3 , 235.Xr EVP_aes_128_cbc 3 , 236.Xr EVP_CIPHER_CTX_ctrl 3 , 237.Xr EVP_EncryptInit 3 238.Sh STANDARDS 239.Rs 240.%A Morris Dworkin 241.%I National Institute of Standards and Technology 242.%R Recommendation for Block Cipher Modes of Operation:\ 243 Galois/Counter Mode (GCM) and GMAC 244.%N NIST Special Publication 800-38D 245.%C Gaithersburg, Maryland 246.%D November 2007 247.Re 248.Sh HISTORY 249.Fn EVP_aes_128_gcm , 250.Fn EVP_aes_192_gcm , 251and 252.Fn EVP_aes_256_gcm 253first appeared in OpenSSL 1.0.1 and have been available since 254.Ox 5.3 . 255