doc/man3/EVP_aes_128_gcm.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 openssl 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_192_wrap_pad(),
 138 EVP_aes_256_wrap_pad()
 139
 140 AES key wrap with 128, 192 and 256 bit keys, as according to RFC 3394 section
 141 2.2.1 ("wrap") and RFC 5649 section 4.1 ("wrap with padding") respectively.
 142
 143 =item EVP_aes_128_xts(),
 144 EVP_aes_256_xts()
 145
 146 AES XTS mode (XTS-AES) is standardized in IEEE Std. 1619-2007 and described in NIST
 147 SP 800-38E. The XTS (XEX-based tweaked-codebook mode with ciphertext stealing)
 148 mode was designed by Prof. Phillip Rogaway of University of California, Davis,
 149 intended for encrypting data on a storage device.
 150
 151 XTS-AES provides confidentiality but not authentication of data. It also
 152 requires a key of double-length for protection of a certain key size.
 153 In particular, XTS-AES-128 (B<EVP_aes_128_xts>) takes input of a 256-bit key to
 154 achieve AES 128-bit security, and XTS-AES-256 (B<EVP_aes_256_xts>) takes input
 155 of a 512-bit key to achieve AES 256-bit security.
 156
 157 The XTS implementation in OpenSSL does not support streaming. That is there must
 158 only be one L<EVP_EncryptUpdate(3)> call per L<EVP_EncryptInit_ex(3)> call (and
 159 similarly with the "Decrypt" functions).
 160
 161 The I<iv> parameter to L<EVP_EncryptInit_ex(3)> or L<EVP_DecryptInit_ex(3)> is
 162 the XTS "tweak" value.
 163
 164 =back
 165
 166 =head1 NOTES
 167
 168 Developers should be aware of the negative performance implications of
 169 calling these functions multiple times and should consider using
 170 L<EVP_CIPHER_fetch(3)> with L<EVP_CIPHER-AES(7)> instead.
 171 See L<crypto(7)/Performance> for further information.
 172
 173 =head1 RETURN VALUES
 174
 175 These functions return an B<EVP_CIPHER> structure that contains the
 176 implementation of the symmetric cipher. See L<EVP_CIPHER_meth_new(3)> for
 177 details of the B<EVP_CIPHER> structure.
 178
 179 =head1 SEE ALSO
 180
 181 L<evp(7)>,
 182 L<EVP_EncryptInit(3)>,
 183 L<EVP_CIPHER_meth_new(3)>
 184
 185 =head1 COPYRIGHT
 186
 187 Copyright 2017-2023 The OpenSSL Project Authors. All Rights Reserved.
 188
 189 Licensed under the Apache License 2.0 (the "License").  You may not use
 190 this file except in compliance with the License.  You can obtain a copy
 191 in the file LICENSE in the source distribution or at
 192 L<https://www.openssl.org/source/license.html>.
 193
 194 =cut
 195