a47c7eb4bd0a8ec220892aaeaee24810f3f1a2ab
[openssl.git] / doc / man3 / EVP_aes.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_aes_128_cbc,
6 EVP_aes_192_cbc,
7 EVP_aes_256_cbc,
8 EVP_aes_128_cfb,
9 EVP_aes_192_cfb,
10 EVP_aes_256_cfb,
11 EVP_aes_128_cfb1,
12 EVP_aes_192_cfb1,
13 EVP_aes_256_cfb1,
14 EVP_aes_128_cfb8,
15 EVP_aes_192_cfb8,
16 EVP_aes_256_cfb8,
17 EVP_aes_128_cfb128,
18 EVP_aes_192_cfb128,
19 EVP_aes_256_cfb128,
20 EVP_aes_128_ctr,
21 EVP_aes_192_ctr,
22 EVP_aes_256_ctr,
23 EVP_aes_128_ecb,
24 EVP_aes_192_ecb,
25 EVP_aes_256_ecb,
26 EVP_aes_128_ofb,
27 EVP_aes_192_ofb,
28 EVP_aes_256_ofb,
29 EVP_aes_128_cbc_hmac_sha1,
30 EVP_aes_256_cbc_hmac_sha1,
31 EVP_aes_128_cbc_hmac_sha256,
32 EVP_aes_256_cbc_hmac_sha256,
33 EVP_aes_128_ccm,
34 EVP_aes_192_ccm,
35 EVP_aes_256_ccm,
36 EVP_aes_128_gcm,
37 EVP_aes_192_gcm,
38 EVP_aes_256_gcm,
39 EVP_aes_128_ocb,
40 EVP_aes_192_ocb,
41 EVP_aes_256_ocb,
42 EVP_aes_128_wrap,
43 EVP_aes_192_wrap,
44 EVP_aes_256_wrap,
45 EVP_aes_128_wrap_pad,
46 EVP_aes_192_wrap_pad,
47 EVP_aes_256_wrap_pad,
48 EVP_aes_128_xts,
49 EVP_aes_256_xts
50 - EVP AES cipher
51
52 =head1 SYNOPSIS
53
54 =for comment generic
55
56  #include <openssl/evp.h>
57
58  const EVP_CIPHER *EVP_ciphername(void)
59
60 I<EVP_ciphername> is used a placeholder for any of the described cipher
61 functions, such as I<EVP_aes_128_cbc>.
62
63 =head1 DESCRIPTION
64
65 The AES encryption algorithm for EVP.
66
67 =over 4
68
69 =item EVP_aes_128_cbc(),
70 EVP_aes_192_cbc(),
71 EVP_aes_256_cbc(),
72 EVP_aes_128_cfb(),
73 EVP_aes_192_cfb(),
74 EVP_aes_256_cfb(),
75 EVP_aes_128_cfb1(),
76 EVP_aes_192_cfb1(),
77 EVP_aes_256_cfb1(),
78 EVP_aes_128_cfb8(),
79 EVP_aes_192_cfb8(),
80 EVP_aes_256_cfb8(),
81 EVP_aes_128_cfb128(),
82 EVP_aes_192_cfb128(),
83 EVP_aes_256_cfb128(),
84 EVP_aes_128_ctr(),
85 EVP_aes_192_ctr(),
86 EVP_aes_256_ctr(),
87 EVP_aes_128_ecb(),
88 EVP_aes_192_ecb(),
89 EVP_aes_256_ecb(),
90 EVP_aes_128_ofb(),
91 EVP_aes_192_ofb(),
92 EVP_aes_256_ofb()
93
94 AES for 128, 192 and 256 bit keys in the following modes: CBC, CFB with 128-bit
95 shift, CFB with 1-bit shift, CFB with 8-bit shift, CTR, ECB, and OFB.
96
97 =item EVP_aes_128_cbc_hmac_sha1(),
98 EVP_aes_256_cbc_hmac_sha1()
99
100 Authenticated encryption with AES in CBC mode using SHA-1 as HMAC, with keys of
101 128 and 256 bits length respectively. The authentication tag is 160 bits long.
102
103 WARNING: this is not intended for usage outside of TLS and requires calling of
104 some undocumented ctrl functions. These ciphers do not conform to the EVP AEAD
105 interface.
106
107 =item EVP_aes_128_cbc_hmac_sha256(),
108 EVP_aes_256_cbc_hmac_sha256()
109
110 Authenticated encryption with AES in CBC mode using SHA256 (SHA-2, 256-bits) as
111 HMAC, with keys of 128 and 256 bits length respectively. The authentication tag
112 is 256 bits long.
113
114 WARNING: this is not intended for usage outside of TLS and requires calling of
115 some undocumented ctrl functions. These ciphers do not conform to the EVP AEAD
116 interface.
117
118 =item EVP_aes_128_ccm(),
119 EVP_aes_192_ccm(),
120 EVP_aes_256_ccm(),
121 EVP_aes_128_gcm(),
122 EVP_aes_192_gcm(),
123 EVP_aes_256_gcm(),
124 EVP_aes_128_ocb(),
125 EVP_aes_192_ocb(),
126 EVP_aes_256_ocb()
127
128 AES for 128, 192 and 256 bit keys in CBC-MAC Mode (CCM), Galois Counter Mode
129 (GCM) and OCB Mode respectively. These ciphers require additional control
130 operations to function correctly, see the L<EVP_EncryptInit(3)/AEAD Interface>
131 section for details.
132
133 =item EVP_aes_128_wrap(),
134 EVP_aes_192_wrap(),
135 EVP_aes_256_wrap(),
136 EVP_aes_128_wrap_pad(),
137 EVP_aes_128_wrap(),
138 EVP_aes_192_wrap(),
139 EVP_aes_256_wrap(),
140 EVP_aes_192_wrap_pad(),
141 EVP_aes_128_wrap(),
142 EVP_aes_192_wrap(),
143 EVP_aes_256_wrap(),
144 EVP_aes_256_wrap_pad()
145
146 AES key wrap with 128, 192 and 256 bit keys, as according to RFC 3394 section
147 2.2.1 ("wrap") and RFC 5649 section 4.1 ("wrap with padding") respectively.
148
149 =item EVP_aes_128_xts(),
150 EVP_aes_256_xts()
151
152 AES XTS mode (XTS-AES) is standardized in IEEE Std. 1619-2007 and described in NIST
153 SP 800-38E. The XTS (XEX-based tweaked-codebook mode with ciphertext stealing)
154 mode was designed by Prof. Phillip Rogaway of University of California, Davis,
155 intended for encrypting data on a storage device.
156
157 XTS-AES provides confidentiality but not authentication of data. It also
158 requires a key of double-length for protection of a certain key size.
159 In particular, XTS-AES-128 (B<EVP_aes_128_xts>) takes input of a 256-bit key to
160 achieve AES 128-bit security, and XTS-AES-256 (B<EVP_aes_256_xts>) takes input
161 of a 512-bit key to achieve AES 256-bit security.
162
163 =back
164
165 =head1 RETURN VALUES
166
167 These functions return an B<EVP_CIPHER> structure that contains the
168 implementation of the symmetric cipher. See L<EVP_CIPHER_meth_new(3)> for
169 details of the B<EVP_CIPHER> structure.
170
171 =head1 SEE ALSO
172
173 L<evp(7)>,
174 L<EVP_EncryptInit(3)>,
175 L<EVP_CIPHER_meth_new(3)>
176
177 =head1 COPYRIGHT
178
179 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
180
181 Licensed under the OpenSSL license (the "License").  You may not use
182 this file except in compliance with the License.  You can obtain a copy
183 in the file LICENSE in the source distribution or at
184 L<https://www.openssl.org/source/license.html>.
185
186 =cut
187