1.\" $OpenBSD: EVP_aes_128_cbc.3,v 1.8 2024/12/20 01:54:03 schwarze Exp $ 2.\" selective merge up to: OpenSSL 7c6d372a Nov 20 13:20:01 2018 +0000 3.\" 4.\" This file was written by Ronald Tse <ronald.tse@ribose.com> 5.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: December 20 2024 $ 52.Dt EVP_AES_128_CBC 3 53.Os 54.Sh NAME 55.Nm EVP_aes_128_cbc , 56.Nm EVP_aes_192_cbc , 57.Nm EVP_aes_256_cbc , 58.Nm EVP_aes_128_cfb1 , 59.Nm EVP_aes_192_cfb1 , 60.Nm EVP_aes_256_cfb1 , 61.Nm EVP_aes_128_cfb8 , 62.Nm EVP_aes_192_cfb8 , 63.Nm EVP_aes_256_cfb8 , 64.Nm EVP_aes_128_cfb128 , 65.Nm EVP_aes_192_cfb128 , 66.Nm EVP_aes_256_cfb128 , 67.Nm EVP_aes_128_cfb , 68.Nm EVP_aes_192_cfb , 69.Nm EVP_aes_256_cfb , 70.Nm EVP_aes_128_ctr , 71.Nm EVP_aes_192_ctr , 72.Nm EVP_aes_256_ctr , 73.Nm EVP_aes_128_ecb , 74.Nm EVP_aes_192_ecb , 75.Nm EVP_aes_256_ecb , 76.Nm EVP_aes_128_ofb , 77.Nm EVP_aes_192_ofb , 78.Nm EVP_aes_256_ofb , 79.Nm EVP_aes_128_cbc_hmac_sha1 , 80.Nm EVP_aes_256_cbc_hmac_sha1 , 81.Nm EVP_aes_128_wrap , 82.Nm EVP_aes_192_wrap , 83.Nm EVP_aes_256_wrap , 84.Nm EVP_aes_128_xts , 85.Nm EVP_aes_256_xts 86.Nd EVP AES cipher 87.Sh SYNOPSIS 88.In openssl/evp.h 89.Ft const EVP_CIPHER * 90.Fn EVP_aes_128_cbc void 91.Ft const EVP_CIPHER * 92.Fn EVP_aes_192_cbc void 93.Ft const EVP_CIPHER * 94.Fn EVP_aes_256_cbc void 95.Ft const EVP_CIPHER * 96.Fn EVP_aes_128_cfb1 void 97.Ft const EVP_CIPHER * 98.Fn EVP_aes_192_cfb1 void 99.Ft const EVP_CIPHER * 100.Fn EVP_aes_256_cfb1 void 101.Ft const EVP_CIPHER * 102.Fn EVP_aes_128_cfb8 void 103.Ft const EVP_CIPHER * 104.Fn EVP_aes_192_cfb8 void 105.Ft const EVP_CIPHER * 106.Fn EVP_aes_256_cfb8 void 107.Ft const EVP_CIPHER * 108.Fn EVP_aes_128_cfb128 void 109.Ft const EVP_CIPHER * 110.Fn EVP_aes_192_cfb128 void 111.Ft const EVP_CIPHER * 112.Fn EVP_aes_256_cfb128 void 113.Ft const EVP_CIPHER * 114.Fn EVP_aes_128_cfb void 115.Ft const EVP_CIPHER * 116.Fn EVP_aes_192_cfb void 117.Ft const EVP_CIPHER * 118.Fn EVP_aes_256_cfb void 119.Ft const EVP_CIPHER * 120.Fn EVP_aes_128_ctr void 121.Ft const EVP_CIPHER * 122.Fn EVP_aes_192_ctr void 123.Ft const EVP_CIPHER * 124.Fn EVP_aes_256_ctr void 125.Ft const EVP_CIPHER * 126.Fn EVP_aes_128_ecb void 127.Ft const EVP_CIPHER * 128.Fn EVP_aes_192_ecb void 129.Ft const EVP_CIPHER * 130.Fn EVP_aes_256_ecb void 131.Ft const EVP_CIPHER * 132.Fn EVP_aes_128_ofb void 133.Ft const EVP_CIPHER * 134.Fn EVP_aes_192_ofb void 135.Ft const EVP_CIPHER * 136.Fn EVP_aes_256_ofb void 137.Ft const EVP_CIPHER * 138.Fn EVP_aes_128_cbc_hmac_sha1 void 139.Ft const EVP_CIPHER * 140.Fn EVP_aes_256_cbc_hmac_sha1 void 141.Ft const EVP_CIPHER * 142.Fn EVP_aes_128_wrap void 143.Ft const EVP_CIPHER * 144.Fn EVP_aes_192_wrap void 145.Ft const EVP_CIPHER * 146.Fn EVP_aes_256_wrap void 147.Ft const EVP_CIPHER * 148.Fn EVP_aes_128_xts void 149.Ft const EVP_CIPHER * 150.Fn EVP_aes_256_xts void 151.Sh DESCRIPTION 152These functions provide the AES encryption algorithm in the 153.Xr evp 3 154framework. 155AES is a family of block ciphers operating on 128 bit blocks 156using key lengths of 128, 192, and 256 bits. 157.Pp 158.Fn EVP_aes_128_cbc , 159.Fn EVP_aes_192_cbc , 160.Fn EVP_aes_256_cbc , 161.Fn EVP_aes_128_cfb1 , 162.Fn EVP_aes_192_cfb1 , 163.Fn EVP_aes_256_cfb1 , 164.Fn EVP_aes_128_cfb8 , 165.Fn EVP_aes_192_cfb8 , 166.Fn EVP_aes_256_cfb8 , 167.Fn EVP_aes_128_cfb128 , 168.Fn EVP_aes_192_cfb128 , 169.Fn EVP_aes_256_cfb128 , 170.Fn EVP_aes_128_ctr , 171.Fn EVP_aes_192_ctr , 172.Fn EVP_aes_256_ctr , 173.Fn EVP_aes_128_ecb , 174.Fn EVP_aes_192_ecb , 175.Fn EVP_aes_256_ecb , 176.Fn EVP_aes_128_ofb , 177.Fn EVP_aes_192_ofb , 178and 179.Fn EVP_aes_256_ofb 180provide AES for 128, 192, and 256-bit keys in the following modes: 181CBC, CFB with 1-bit shift, CFB with 8-bit shift, CFB with 128-bit shift, 182CTR, ECB, and OFB. 183.Pp 184.Fn EVP_aes_128_cfb , 185.Fn EVP_aes_192_cfb , 186and 187.Fn EVP_aes_256_cfb 188are aliases for 189.Fn EVP_aes_128_cfb128 , 190.Fn EVP_aes_192_cfb128 , 191and 192.Fn EVP_aes_256_cfb128 , 193implemented as macros. 194.Pp 195.Fn EVP_aes_128_cbc_hmac_sha1 196and 197.Fn EVP_aes_256_cbc_hmac_sha1 198provide authenticated encryption with AES in CBC mode using SHA-1 as HMAC, 199with keys of 128 and 256-bit length respectively. 200The authentication tag is 160 bits long. 201This is not intended for usage outside of TLS and requires 202calling of some undocumented control functions. 203These ciphers do not conform to the EVP AEAD interface. 204.Pp 205.Fn EVP_aes_128_wrap , 206.Fn EVP_aes_192_wrap , 207and 208.Fn EVP_aes_256_wrap 209provide AES key wrap with 128, 192 and 256-bit keys 210according to RFC 3394 section 2.2.1 ("wrap"). 211When the returned 212.Vt EVP_CIPHER 213object is later passed to 214.Xr EVP_CipherInit_ex 3 , 215.Xr EVP_EncryptInit_ex 3 , 216or 217.Xr EVP_DecryptInit_ex 3 218together with an 219.Vt EVP_CIPHER_CTX 220object, the flag 221.Dv EVP_CIPHER_CTX_FLAG_WRAP_ALLOW 222must have been set in the 223.Vt EVP_CIPHER_CTX 224using 225.Xr EVP_CIPHER_CTX_set_flags 3 . 226Otherwise, or when passing the returned 227.Vt EVP_CIPHER 228object to 229.Xr EVP_CipherInit 3 , 230.Xr EVP_EncryptInit 3 , 231or 232.Xr EVP_DecryptInit 3 , 233initialization fails with a 234.Dq wrap not allowed 235error. 236.Pp 237.Fn EVP_aes_128_xts 238and 239.Fn EVP_aes_256_xts 240provide XEX-based tweaked-codebook mode with ciphertext stealing (XTS-AES) 241as specified in IEEE Std. 1619-2007 and described in NIST SP 800-38E. 242It was designed for encrypting data on a storage device, 243provides confidentiality but not authentication of data, 244and requires a key of double length for protection of a certain key size. 245In particular, XTS-AES-128 takes input of a 256-bit key to achieve 246AES 128-bit security, and XTS-AES-256 takes input of a 512-bit key 247to achieve AES 256-bit security. 248.Sh RETURN VALUES 249These functions return an 250.Vt EVP_CIPHER 251structure that provides the implementation of the symmetric cipher. 252.Sh SEE ALSO 253.Xr AES_encrypt 3 , 254.Xr evp 3 , 255.Xr EVP_aes_128_ccm 3 , 256.Xr EVP_aes_128_gcm 3 , 257.Xr EVP_EncryptInit 3 258.Sh HISTORY 259.Fn EVP_aes_128_cbc , 260.Fn EVP_aes_192_cbc , 261.Fn EVP_aes_256_cbc , 262.Fn EVP_aes_128_cfb , 263.Fn EVP_aes_192_cfb , 264.Fn EVP_aes_256_cfb , 265.Fn EVP_aes_128_ebc , 266.Fn EVP_aes_192_ebc , 267.Fn EVP_aes_256_ebc , 268.Fn EVP_aes_128_ofb , 269.Fn EVP_aes_192_ofb , 270and 271.Fn EVP_aes_256_ofb 272first appeared in OpenSSL 0.9.7 and have been available since 273.Ox 3.2 . 274.Pp 275.Fn EVP_aes_128_cfb1 , 276.Fn EVP_aes_192_cfb1 , 277.Fn EVP_aes_256_cfb1 , 278.Fn EVP_aes_128_cfb8 , 279.Fn EVP_aes_192_cfb8 , 280.Fn EVP_aes_256_cfb8 , 281.Fn EVP_aes_128_cfb128 , 282.Fn EVP_aes_192_cfb128 , 283and 284.Fn EVP_aes_256_cfb128 285first appeared in OpenSSL 0.9.7e and have been available since 286.Ox 3.8 . 287.Pp 288.Fn EVP_aes_128_ctr , 289.Fn EVP_aes_192_ctr , 290.Fn EVP_aes_256_ctr , 291.Fn EVP_aes_128_cbc_hmac_sha1 , 292.Fn EVP_aes_256_cbc_hmac_sha1 , 293.Fn EVP_aes_128_xts , 294and 295.Fn EVP_aes_256_xts 296first appeared in OpenSSL 1.0.1 and have been available since 297.Ox 5.3 . 298.Pp 299.Fn EVP_aes_128_wrap , 300.Fn EVP_aes_192_wrap , 301and 302.Fn EVP_aes_256_wrap 303first appeared in OpenSSL 1.0.2 and have been available since 304.Ox 6.5 . 305