secure/lib/libcrypto/man/man3/EVP_aes.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "EVP_AES 3"
 136 .TH EVP_AES 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 EVP_aes_128_cbc, EVP_aes_192_cbc, EVP_aes_256_cbc, EVP_aes_128_cfb, EVP_aes_192_cfb, EVP_aes_256_cfb, EVP_aes_128_cfb1, EVP_aes_192_cfb1, EVP_aes_256_cfb1, EVP_aes_128_cfb8, EVP_aes_192_cfb8, EVP_aes_256_cfb8, EVP_aes_128_cfb128, EVP_aes_192_cfb128, EVP_aes_256_cfb128, EVP_aes_128_ctr, EVP_aes_192_ctr, EVP_aes_256_ctr, EVP_aes_128_ecb, EVP_aes_192_ecb, EVP_aes_256_ecb, EVP_aes_128_ofb, EVP_aes_192_ofb, EVP_aes_256_ofb, EVP_aes_128_cbc_hmac_sha1, EVP_aes_256_cbc_hmac_sha1, EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256, EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm, EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ocb, EVP_aes_192_ocb, EVP_aes_256_ocb, EVP_aes_128_wrap, EVP_aes_192_wrap, EVP_aes_256_wrap, EVP_aes_128_wrap_pad, EVP_aes_192_wrap_pad, EVP_aes_256_wrap_pad, EVP_aes_128_xts, EVP_aes_256_xts \&\- EVP AES cipher
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/evp.h>
 147 \&
 148 \& const EVP_CIPHER *EVP_ciphername(void)
 149 .Ve
 150 .PP
 151 \&\fIEVP_ciphername\fR is used a placeholder for any of the described cipher
 152 functions, such as \fIEVP_aes_128_cbc\fR.
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 The \s-1AES\s0 encryption algorithm for \s-1EVP.\s0
 156 .IP "\fBEVP_aes_128_cbc()\fR, \fBEVP_aes_192_cbc()\fR, \fBEVP_aes_256_cbc()\fR, \fBEVP_aes_128_cfb()\fR, \fBEVP_aes_192_cfb()\fR, \fBEVP_aes_256_cfb()\fR, \fBEVP_aes_128_cfb1()\fR, \fBEVP_aes_192_cfb1()\fR, \fBEVP_aes_256_cfb1()\fR, \fBEVP_aes_128_cfb8()\fR, \fBEVP_aes_192_cfb8()\fR, \fBEVP_aes_256_cfb8()\fR, \fBEVP_aes_128_cfb128()\fR, \fBEVP_aes_192_cfb128()\fR, \fBEVP_aes_256_cfb128()\fR, \fBEVP_aes_128_ctr()\fR, \fBEVP_aes_192_ctr()\fR, \fBEVP_aes_256_ctr()\fR, \fBEVP_aes_128_ecb()\fR, \fBEVP_aes_192_ecb()\fR, \fBEVP_aes_256_ecb()\fR, \fBEVP_aes_128_ofb()\fR, \fBEVP_aes_192_ofb()\fR, \fBEVP_aes_256_ofb()\fR" 4
 157 .IX Item "EVP_aes_128_cbc(), EVP_aes_192_cbc(), EVP_aes_256_cbc(), EVP_aes_128_cfb(), EVP_aes_192_cfb(), EVP_aes_256_cfb(), EVP_aes_128_cfb1(), EVP_aes_192_cfb1(), EVP_aes_256_cfb1(), EVP_aes_128_cfb8(), EVP_aes_192_cfb8(), EVP_aes_256_cfb8(), EVP_aes_128_cfb128(), EVP_aes_192_cfb128(), EVP_aes_256_cfb128(), EVP_aes_128_ctr(), EVP_aes_192_ctr(), EVP_aes_256_ctr(), EVP_aes_128_ecb(), EVP_aes_192_ecb(), EVP_aes_256_ecb(), EVP_aes_128_ofb(), EVP_aes_192_ofb(), EVP_aes_256_ofb()"
 158 \&\s-1AES\s0 for 128, 192 and 256 bit keys in the following modes: \s-1CBC, CFB\s0 with 128\-bit
 159 shift, \s-1CFB\s0 with 1\-bit shift, \s-1CFB\s0 with 8\-bit shift, \s-1CTR, ECB,\s0 and \s-1OFB.\s0
 160 .IP "\fBEVP_aes_128_cbc_hmac_sha1()\fR, \fBEVP_aes_256_cbc_hmac_sha1()\fR" 4
 161 .IX Item "EVP_aes_128_cbc_hmac_sha1(), EVP_aes_256_cbc_hmac_sha1()"
 162 Authenticated encryption with \s-1AES\s0 in \s-1CBC\s0 mode using \s-1SHA\-1\s0 as \s-1HMAC,\s0 with keys of
 163 128 and 256 bits length respectively. The authentication tag is 160 bits long.
 164 .Sp
 165 \&\s-1WARNING:\s0 this is not intended for usage outside of \s-1TLS\s0 and requires calling of
 166 some undocumented ctrl functions. These ciphers do not conform to the \s-1EVP AEAD\s0
 167 interface.
 168 .IP "\fBEVP_aes_128_cbc_hmac_sha256()\fR, \fBEVP_aes_256_cbc_hmac_sha256()\fR" 4
 169 .IX Item "EVP_aes_128_cbc_hmac_sha256(), EVP_aes_256_cbc_hmac_sha256()"
 170 Authenticated encryption with \s-1AES\s0 in \s-1CBC\s0 mode using \s-1SHA256\s0 (\s-1SHA\-2,\s0 256\-bits) as
 171 \&\s-1HMAC,\s0 with keys of 128 and 256 bits length respectively. The authentication tag
 172 is 256 bits long.
 173 .Sp
 174 \&\s-1WARNING:\s0 this is not intended for usage outside of \s-1TLS\s0 and requires calling of
 175 some undocumented ctrl functions. These ciphers do not conform to the \s-1EVP AEAD\s0
 176 interface.
 177 .IP "\fBEVP_aes_128_ccm()\fR, \fBEVP_aes_192_ccm()\fR, \fBEVP_aes_256_ccm()\fR, \fBEVP_aes_128_gcm()\fR, \fBEVP_aes_192_gcm()\fR, \fBEVP_aes_256_gcm()\fR, \fBEVP_aes_128_ocb()\fR, \fBEVP_aes_192_ocb()\fR, \fBEVP_aes_256_ocb()\fR" 4
 178 .IX Item "EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm(), EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm(), EVP_aes_128_ocb(), EVP_aes_192_ocb(), EVP_aes_256_ocb()"
 179 \&\s-1AES\s0 for 128, 192 and 256 bit keys in CBC-MAC Mode (\s-1CCM\s0), Galois Counter Mode
 180 (\s-1GCM\s0) and \s-1OCB\s0 Mode respectively. These ciphers require additional control
 181 operations to function correctly, see the \*(L"\s-1AEAD\s0 Interface\*(R" in \fBEVP_EncryptInit\fR\|(3)
 182 section for details.
 183 .IP "\fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_128_wrap_pad()\fR, \fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_192_wrap_pad()\fR, \fBEVP_aes_128_wrap()\fR, \fBEVP_aes_192_wrap()\fR, \fBEVP_aes_256_wrap()\fR, \fBEVP_aes_256_wrap_pad()\fR" 4
 184 .IX Item "EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_128_wrap_pad(), EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_192_wrap_pad(), EVP_aes_128_wrap(), EVP_aes_192_wrap(), EVP_aes_256_wrap(), EVP_aes_256_wrap_pad()"
 185 \&\s-1AES\s0 key wrap with 128, 192 and 256 bit keys, as according to \s-1RFC 3394\s0 section
 186 2.2.1 (\*(L"wrap\*(R") and \s-1RFC 5649\s0 section 4.1 (\*(L"wrap with padding\*(R") respectively.
 187 .IP "\fBEVP_aes_128_xts()\fR, \fBEVP_aes_256_xts()\fR" 4
 188 .IX Item "EVP_aes_128_xts(), EVP_aes_256_xts()"
 189 \&\s-1AES XTS\s0 mode (XTS-AES) is standardized in \s-1IEEE\s0 Std. 1619\-2007 and described in \s-1NIST
 190 SP 800\-38E.\s0 The \s-1XTS\s0 (XEX-based tweaked-codebook mode with ciphertext stealing)
 191 mode was designed by Prof. Phillip Rogaway of University of California, Davis,
 192 intended for encrypting data on a storage device.
 193 .Sp
 194 XTS-AES provides confidentiality but not authentication of data. It also
 195 requires a key of double-length for protection of a certain key size.
 196 In particular, \s-1XTS\-AES\-128\s0 (\fBEVP_aes_128_xts\fR) takes input of a 256\-bit key to
 197 achieve \s-1AES\s0 128\-bit security, and \s-1XTS\-AES\-256\s0 (\fBEVP_aes_256_xts\fR) takes input
 198 of a 512\-bit key to achieve \s-1AES\s0 256\-bit security.
 199 .Sp
 200 The \s-1XTS\s0 implementation in OpenSSL does not support streaming. That is there must
 201 only be one \fBEVP_EncryptUpdate\fR\|(3) call per \fBEVP_EncryptInit_ex\fR\|(3) call (and
 202 similarly with the \*(L"Decrypt\*(R" functions).
 203 .Sp
 204 The \fIiv\fR parameter to \fBEVP_EncryptInit_ex\fR\|(3) or \fBEVP_DecryptInit_ex\fR\|(3) is
 205 the \s-1XTS\s0 \*(L"tweak\*(R" value.
 206 .SH "RETURN VALUES"
 207 .IX Header "RETURN VALUES"
 208 These functions return an \fB\s-1EVP_CIPHER\s0\fR structure that contains the
 209 implementation of the symmetric cipher. See \fBEVP_CIPHER_meth_new\fR\|(3) for
 210 details of the \fB\s-1EVP_CIPHER\s0\fR structure.
 211 .SH "SEE ALSO"
 212 .IX Header "SEE ALSO"
 213 \&\fBevp\fR\|(7),
 214 \&\fBEVP_EncryptInit\fR\|(3),
 215 \&\fBEVP_CIPHER_meth_new\fR\|(3)
 216 .SH "COPYRIGHT"
 217 .IX Header "COPYRIGHT"
 218 Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
 219 .PP
 220 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 221 this file except in compliance with the License.  You can obtain a copy
 222 in the file \s-1LICENSE\s0 in the source distribution or at
 223 <https://www.openssl.org/source/license.html>.