1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_aes_128_cbc, 6b077aed3SPierre ProncheryEVP_aes_192_cbc, 7b077aed3SPierre ProncheryEVP_aes_256_cbc, 8b077aed3SPierre ProncheryEVP_aes_128_cfb, 9b077aed3SPierre ProncheryEVP_aes_192_cfb, 10b077aed3SPierre ProncheryEVP_aes_256_cfb, 11b077aed3SPierre ProncheryEVP_aes_128_cfb1, 12b077aed3SPierre ProncheryEVP_aes_192_cfb1, 13b077aed3SPierre ProncheryEVP_aes_256_cfb1, 14b077aed3SPierre ProncheryEVP_aes_128_cfb8, 15b077aed3SPierre ProncheryEVP_aes_192_cfb8, 16b077aed3SPierre ProncheryEVP_aes_256_cfb8, 17b077aed3SPierre ProncheryEVP_aes_128_cfb128, 18b077aed3SPierre ProncheryEVP_aes_192_cfb128, 19b077aed3SPierre ProncheryEVP_aes_256_cfb128, 20b077aed3SPierre ProncheryEVP_aes_128_ctr, 21b077aed3SPierre ProncheryEVP_aes_192_ctr, 22b077aed3SPierre ProncheryEVP_aes_256_ctr, 23b077aed3SPierre ProncheryEVP_aes_128_ecb, 24b077aed3SPierre ProncheryEVP_aes_192_ecb, 25b077aed3SPierre ProncheryEVP_aes_256_ecb, 26b077aed3SPierre ProncheryEVP_aes_128_ofb, 27b077aed3SPierre ProncheryEVP_aes_192_ofb, 28b077aed3SPierre ProncheryEVP_aes_256_ofb, 29b077aed3SPierre ProncheryEVP_aes_128_cbc_hmac_sha1, 30b077aed3SPierre ProncheryEVP_aes_256_cbc_hmac_sha1, 31b077aed3SPierre ProncheryEVP_aes_128_cbc_hmac_sha256, 32b077aed3SPierre ProncheryEVP_aes_256_cbc_hmac_sha256, 33b077aed3SPierre ProncheryEVP_aes_128_ccm, 34b077aed3SPierre ProncheryEVP_aes_192_ccm, 35b077aed3SPierre ProncheryEVP_aes_256_ccm, 36b077aed3SPierre ProncheryEVP_aes_128_gcm, 37b077aed3SPierre ProncheryEVP_aes_192_gcm, 38b077aed3SPierre ProncheryEVP_aes_256_gcm, 39b077aed3SPierre ProncheryEVP_aes_128_ocb, 40b077aed3SPierre ProncheryEVP_aes_192_ocb, 41b077aed3SPierre ProncheryEVP_aes_256_ocb, 42b077aed3SPierre ProncheryEVP_aes_128_wrap, 43b077aed3SPierre ProncheryEVP_aes_192_wrap, 44b077aed3SPierre ProncheryEVP_aes_256_wrap, 45b077aed3SPierre ProncheryEVP_aes_128_wrap_pad, 46b077aed3SPierre ProncheryEVP_aes_192_wrap_pad, 47b077aed3SPierre ProncheryEVP_aes_256_wrap_pad, 48b077aed3SPierre ProncheryEVP_aes_128_xts, 49b077aed3SPierre ProncheryEVP_aes_256_xts 50b077aed3SPierre Pronchery- EVP AES cipher 51b077aed3SPierre Pronchery 52b077aed3SPierre Pronchery=head1 SYNOPSIS 53b077aed3SPierre Pronchery 54b077aed3SPierre Pronchery=for openssl generic 55b077aed3SPierre Pronchery 56b077aed3SPierre Pronchery #include <openssl/evp.h> 57b077aed3SPierre Pronchery 58b077aed3SPierre Pronchery const EVP_CIPHER *EVP_ciphername(void) 59b077aed3SPierre Pronchery 60b077aed3SPierre ProncheryI<EVP_ciphername> is used a placeholder for any of the described cipher 61b077aed3SPierre Proncheryfunctions, such as I<EVP_aes_128_cbc>. 62b077aed3SPierre Pronchery 63b077aed3SPierre Pronchery=head1 DESCRIPTION 64b077aed3SPierre Pronchery 65b077aed3SPierre ProncheryThe AES encryption algorithm for EVP. 66b077aed3SPierre Pronchery 67b077aed3SPierre Pronchery=over 4 68b077aed3SPierre Pronchery 69b077aed3SPierre Pronchery=item EVP_aes_128_cbc(), 70b077aed3SPierre ProncheryEVP_aes_192_cbc(), 71b077aed3SPierre ProncheryEVP_aes_256_cbc(), 72b077aed3SPierre ProncheryEVP_aes_128_cfb(), 73b077aed3SPierre ProncheryEVP_aes_192_cfb(), 74b077aed3SPierre ProncheryEVP_aes_256_cfb(), 75b077aed3SPierre ProncheryEVP_aes_128_cfb1(), 76b077aed3SPierre ProncheryEVP_aes_192_cfb1(), 77b077aed3SPierre ProncheryEVP_aes_256_cfb1(), 78b077aed3SPierre ProncheryEVP_aes_128_cfb8(), 79b077aed3SPierre ProncheryEVP_aes_192_cfb8(), 80b077aed3SPierre ProncheryEVP_aes_256_cfb8(), 81b077aed3SPierre ProncheryEVP_aes_128_cfb128(), 82b077aed3SPierre ProncheryEVP_aes_192_cfb128(), 83b077aed3SPierre ProncheryEVP_aes_256_cfb128(), 84b077aed3SPierre ProncheryEVP_aes_128_ctr(), 85b077aed3SPierre ProncheryEVP_aes_192_ctr(), 86b077aed3SPierre ProncheryEVP_aes_256_ctr(), 87b077aed3SPierre ProncheryEVP_aes_128_ecb(), 88b077aed3SPierre ProncheryEVP_aes_192_ecb(), 89b077aed3SPierre ProncheryEVP_aes_256_ecb(), 90b077aed3SPierre ProncheryEVP_aes_128_ofb(), 91b077aed3SPierre ProncheryEVP_aes_192_ofb(), 92b077aed3SPierre ProncheryEVP_aes_256_ofb() 93b077aed3SPierre Pronchery 94b077aed3SPierre ProncheryAES for 128, 192 and 256 bit keys in the following modes: CBC, CFB with 128-bit 95b077aed3SPierre Proncheryshift, CFB with 1-bit shift, CFB with 8-bit shift, CTR, ECB, and OFB. 96b077aed3SPierre Pronchery 97b077aed3SPierre Pronchery=item EVP_aes_128_cbc_hmac_sha1(), 98b077aed3SPierre ProncheryEVP_aes_256_cbc_hmac_sha1() 99b077aed3SPierre Pronchery 100b077aed3SPierre ProncheryAuthenticated encryption with AES in CBC mode using SHA-1 as HMAC, with keys of 101b077aed3SPierre Pronchery128 and 256 bits length respectively. The authentication tag is 160 bits long. 102b077aed3SPierre Pronchery 103b077aed3SPierre ProncheryWARNING: this is not intended for usage outside of TLS and requires calling of 104b077aed3SPierre Proncherysome undocumented ctrl functions. These ciphers do not conform to the EVP AEAD 105b077aed3SPierre Proncheryinterface. 106b077aed3SPierre Pronchery 107b077aed3SPierre Pronchery=item EVP_aes_128_cbc_hmac_sha256(), 108b077aed3SPierre ProncheryEVP_aes_256_cbc_hmac_sha256() 109b077aed3SPierre Pronchery 110b077aed3SPierre ProncheryAuthenticated encryption with AES in CBC mode using SHA256 (SHA-2, 256-bits) as 111b077aed3SPierre ProncheryHMAC, with keys of 128 and 256 bits length respectively. The authentication tag 112b077aed3SPierre Proncheryis 256 bits long. 113b077aed3SPierre Pronchery 114b077aed3SPierre ProncheryWARNING: this is not intended for usage outside of TLS and requires calling of 115b077aed3SPierre Proncherysome undocumented ctrl functions. These ciphers do not conform to the EVP AEAD 116b077aed3SPierre Proncheryinterface. 117b077aed3SPierre Pronchery 118b077aed3SPierre Pronchery=item EVP_aes_128_ccm(), 119b077aed3SPierre ProncheryEVP_aes_192_ccm(), 120b077aed3SPierre ProncheryEVP_aes_256_ccm(), 121b077aed3SPierre ProncheryEVP_aes_128_gcm(), 122b077aed3SPierre ProncheryEVP_aes_192_gcm(), 123b077aed3SPierre ProncheryEVP_aes_256_gcm(), 124b077aed3SPierre ProncheryEVP_aes_128_ocb(), 125b077aed3SPierre ProncheryEVP_aes_192_ocb(), 126b077aed3SPierre ProncheryEVP_aes_256_ocb() 127b077aed3SPierre Pronchery 128b077aed3SPierre ProncheryAES for 128, 192 and 256 bit keys in CBC-MAC Mode (CCM), Galois Counter Mode 129b077aed3SPierre Pronchery(GCM) and OCB Mode respectively. These ciphers require additional control 130b077aed3SPierre Proncheryoperations to function correctly, see the L<EVP_EncryptInit(3)/AEAD Interface> 131b077aed3SPierre Proncherysection for details. 132b077aed3SPierre Pronchery 133b077aed3SPierre Pronchery=item EVP_aes_128_wrap(), 134b077aed3SPierre ProncheryEVP_aes_192_wrap(), 135b077aed3SPierre ProncheryEVP_aes_256_wrap(), 136b077aed3SPierre ProncheryEVP_aes_128_wrap_pad(), 137b077aed3SPierre ProncheryEVP_aes_192_wrap_pad(), 138b077aed3SPierre ProncheryEVP_aes_256_wrap_pad() 139b077aed3SPierre Pronchery 140b077aed3SPierre ProncheryAES key wrap with 128, 192 and 256 bit keys, as according to RFC 3394 section 141b077aed3SPierre Pronchery2.2.1 ("wrap") and RFC 5649 section 4.1 ("wrap with padding") respectively. 142b077aed3SPierre Pronchery 143b077aed3SPierre Pronchery=item EVP_aes_128_xts(), 144b077aed3SPierre ProncheryEVP_aes_256_xts() 145b077aed3SPierre Pronchery 146b077aed3SPierre ProncheryAES XTS mode (XTS-AES) is standardized in IEEE Std. 1619-2007 and described in NIST 147b077aed3SPierre ProncherySP 800-38E. The XTS (XEX-based tweaked-codebook mode with ciphertext stealing) 148b077aed3SPierre Proncherymode was designed by Prof. Phillip Rogaway of University of California, Davis, 149b077aed3SPierre Proncheryintended for encrypting data on a storage device. 150b077aed3SPierre Pronchery 151b077aed3SPierre ProncheryXTS-AES provides confidentiality but not authentication of data. It also 152b077aed3SPierre Proncheryrequires a key of double-length for protection of a certain key size. 153b077aed3SPierre ProncheryIn particular, XTS-AES-128 (B<EVP_aes_128_xts>) takes input of a 256-bit key to 154b077aed3SPierre Proncheryachieve AES 128-bit security, and XTS-AES-256 (B<EVP_aes_256_xts>) takes input 155b077aed3SPierre Proncheryof a 512-bit key to achieve AES 256-bit security. 156b077aed3SPierre Pronchery 157b077aed3SPierre ProncheryThe XTS implementation in OpenSSL does not support streaming. That is there must 158b077aed3SPierre Proncheryonly be one L<EVP_EncryptUpdate(3)> call per L<EVP_EncryptInit_ex(3)> call (and 159b077aed3SPierre Proncherysimilarly with the "Decrypt" functions). 160b077aed3SPierre Pronchery 161b077aed3SPierre ProncheryThe I<iv> parameter to L<EVP_EncryptInit_ex(3)> or L<EVP_DecryptInit_ex(3)> is 162b077aed3SPierre Proncherythe XTS "tweak" value. 163b077aed3SPierre Pronchery 164b077aed3SPierre Pronchery=back 165b077aed3SPierre Pronchery 166b077aed3SPierre Pronchery=head1 NOTES 167b077aed3SPierre Pronchery 168b077aed3SPierre ProncheryDevelopers should be aware of the negative performance implications of 169b077aed3SPierre Proncherycalling these functions multiple times and should consider using 170*ad991e4cSEd MasteL<EVP_CIPHER_fetch(3)> with L<EVP_CIPHER-AES(7)> instead. 171b077aed3SPierre ProncherySee L<crypto(7)/Performance> for further information. 172b077aed3SPierre Pronchery 173b077aed3SPierre Pronchery=head1 RETURN VALUES 174b077aed3SPierre Pronchery 175b077aed3SPierre ProncheryThese functions return an B<EVP_CIPHER> structure that contains the 176b077aed3SPierre Proncheryimplementation of the symmetric cipher. See L<EVP_CIPHER_meth_new(3)> for 177b077aed3SPierre Proncherydetails of the B<EVP_CIPHER> structure. 178b077aed3SPierre Pronchery 179b077aed3SPierre Pronchery=head1 SEE ALSO 180b077aed3SPierre Pronchery 181b077aed3SPierre ProncheryL<evp(7)>, 182b077aed3SPierre ProncheryL<EVP_EncryptInit(3)>, 183b077aed3SPierre ProncheryL<EVP_CIPHER_meth_new(3)> 184b077aed3SPierre Pronchery 185b077aed3SPierre Pronchery=head1 COPYRIGHT 186b077aed3SPierre Pronchery 187b077aed3SPierre ProncheryCopyright 2017-2023 The OpenSSL Project Authors. All Rights Reserved. 188b077aed3SPierre Pronchery 189b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 190b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 191b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 192b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 193b077aed3SPierre Pronchery 194b077aed3SPierre Pronchery=cut 195b077aed3SPierre Pronchery 196