GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  EVP_AEAD_AES_128_GCM (3)

NAME

EVP_AEAD_CTX_init, EVP_AEAD_CTX_cleanup, EVP_AEAD_CTX_open, EVP_AEAD_CTX_seal, EVP_AEAD_key_length, EVP_AEAD_max_overhead, EVP_AEAD_max_tag_len, EVP_AEAD_nonce_length, EVP_aead_aes_128_gcm, EVP_aead_aes_256_gcm, EVP_aead_chacha20_poly1305, EVP_aead_chacha20_poly1305_ietf - authenticated encryption with additional data

CONTENTS

Synopsis
Description
Return Values
Examples
See Also
Standards
History

SYNOPSIS


.In openssl/evp.h int
.Fo EVP_AEAD_CTX_init EVP_AEAD_CTX *ctx const EVP_AEAD *aead const unsigned char *key size_t key_len size_t tag_len ENGINE *impl
.Fc void
.Fo EVP_AEAD_CTX_cleanup EVP_AEAD_CTX *ctx
.Fc int
.Fo EVP_AEAD_CTX_open const EVP_AEAD_CTX *ctx unsigned char *out size_t *out_len size_t max_out_len const unsigned char *nonce size_t nonce_len const unsigned char *in size_t in_len const unsigned char *ad size_t ad_len
.Fc int
.Fo EVP_AEAD_CTX_seal const EVP_AEAD_CTX *ctx unsigned char *out size_t *out_len size_t max_out_len const unsigned char *nonce size_t nonce_len const unsigned char *in size_t in_len const unsigned char *ad size_t ad_len
.Fc size_t
.Fo EVP_AEAD_key_length const EVP_AEAD *aead
.Fc size_t
.Fo EVP_AEAD_max_overhead const EVP_AEAD *aead
.Fc size_t
.Fo EVP_AEAD_max_tag_len const EVP_AEAD *aead
.Fc size_t
.Fo EVP_AEAD_nonce_length const EVP_AEAD *aead
.Fc const EVP_AEAD *
.Fo EVP_aead_aes_128_gcm void
.Fc const EVP_AEAD *
.Fo EVP_aead_aes_256_gcm void
.Fc const EVP_AEAD *
.Fo EVP_aead_chacha20_poly1305 void
.Fc const EVP_AEAD *
.Fo EVP_aead_chacha20_poly1305_ietf void
.Fc

DESCRIPTION

AEAD (Authenticated Encryption with Additional Data) couples confidentiality and integrity in a single primitive. AEAD algorithms take a key and can then seal and open individual messages. Each message has a unique, per-message nonce and, optionally, additional data which is authenticated but not included in the output.

EVP_AEAD_CTX_init initializes the context ctx for the given AEAD algorithm aead. The impl argument must be NULL for the default implementation; other values are currently not supported. Authentication tags may be truncated by passing a tag length. A tag length of zero indicates the default tag length should be used.

EVP_AEAD_CTX_cleanup frees any data allocated for the context ctx.

EVP_AEAD_CTX_open authenticates the input in and optional additional data ad, decrypting the input and writing it as output out. This function may be called (with the same
.Vt EVP_AEAD_CTX ) concurrently with itself or with EVP_AEAD_CTX_seal. At most the number of input bytes are written as output. In order to ensure success, max_out_len should be at least the same as the input length in_len. On successful return out_len is set to the actual number of bytes written. The length of the nonce specified with nonce_len must be equal to the result of EVP_AEAD_nonce_length for this AEAD. EVP_AEAD_CTX_open never results in partial output. If max_out_len is insufficient, zero will be returned and out_len will be set to zero. If the input and output are aliased then out must be <= in.

EVP_AEAD_CTX_seal encrypts and authenticates the input and authenticates any additional data provided in ad, the encrypted input and authentication tag being written as output out. This function may be called (with the same
.Vt EVP_AEAD_CTX ) concurrently with itself or with EVP_AEAD_CTX_open. At most max_out_len bytes are written as output and, in order to ensure success, this value should be the in_len plus the result of EVP_AEAD_overhead(3). On successful return, out_len is set to the actual number of bytes written. The length of the nonce specified with nonce_len must be equal to the result of EVP_AEAD_nonce_length for this AEAD. EVP_AEAD_CTX_seal never results in a partial output. If max_out_len is insufficient, zero will be returned and out_len will be set to zero. If the input and output are aliased then out must be <= in.

EVP_AEAD_key_length, EVP_AEAD_max_overhead, EVP_AEAD_max_tag_len, and EVP_AEAD_nonce_length provide information about the AEAD algorithm aead.

All cipher algorithms have a fixed key length unless otherwise stated. The following ciphers are available:
EVP_aead_aes_128_gcm
  AES-128 in Galois Counter Mode.
EVP_aead_aes_256_gcm
  AES-256 in Galois Counter Mode.
EVP_aead_chacha20_poly1305
  ChaCha20 with a Poly1305 authenticator.
EVP_aead_chacha20_poly1305_ietf
  ChaCha20 with a Poly1305 authenticator for IETF Protocols. The IETF standardised variant of the AEAD is incompatible with the original version. It uses a constant salt that is prepended to the nonce.

Where possible the EVP_AEAD interface to AEAD ciphers should be used in preference to the older EVP variants or to the low level interfaces. This is because the code then becomes transparent to the AEAD cipher used and much more flexible, it is also safer to use as it prevents common mistakes with the native APIs.

RETURN VALUES

EVP_AEAD_CTX_init, EVP_AEAD_CTX_open, and EVP_AEAD_CTX_seal return 1 for success or zero for failure.

EVP_AEAD_key_length returns the length of the key used for this AEAD.

EVP_AEAD_max_overhead returns the maximum number of additional bytes added by the act of sealing data with the AEAD.

EVP_AEAD_max_tag_len returns the maximum tag length when using this AEAD. This is the largest value that can be passed as a tag length to EVP_AEAD_CTX_init.

EVP_AEAD_nonce_length returns the length of the per-message nonce.

EXAMPLES

Encrypt a string using ChaCha20-Poly1305:

const EVP_AEAD *aead = EVP_aead_chacha20_poly1305();
static const unsigned char nonce[32] = {0};
size_t buf_len, nonce_len;
EVP_AEAD_CTX ctx;

EVP_AEAD_CTX_init(&ctx, aead, key32, EVP_AEAD_key_length(aead), EVP_AEAD_DEFAULT_TAG_LENGTH, NULL); nonce_len = EVP_AEAD_nonce_length(aead);

EVP_AEAD_CTX_seal(&ctx, out, &out_len, BUFSIZE, nonce, nonce_len, in, in_len, NULL, 0);

EVP_AEAD_CTX_cleanup(&ctx);

SEE ALSO

evp(3)

STANDARDS


.Rs ChaCha20 and Poly1305 based Cipher Suites for TLS
.Re


.Rs ChaCha20 and Poly1305 for IETF Protocols
.Re

HISTORY

AEAD is based on the implementation by
.An Adam Langley for Chromium/BoringSSL and first appeared in
.Ox 5.6 .
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.