Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
EVP_AEAD_CTX_INIT(3)	 BSD Library Functions Manual	  EVP_AEAD_CTX_INIT(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 addi-
     tional data

SYNOPSIS
     #include <openssl/evp.h>

     int
     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);

     void
     EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx);

     int
     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);

     int
     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);

     size_t
     EVP_AEAD_key_length(const EVP_AEAD	*aead);

     size_t
     EVP_AEAD_max_overhead(const EVP_AEAD *aead);

     size_t
     EVP_AEAD_max_tag_len(const	EVP_AEAD *aead);

     size_t
     EVP_AEAD_nonce_length(const EVP_AEAD *aead);

     const EVP_AEAD *
     EVP_aead_aes_128_gcm(void);

     const EVP_AEAD *
     EVP_aead_aes_256_gcm(void);

     const EVP_AEAD *
     EVP_aead_chacha20_poly1305(void);

     const EVP_AEAD *
     EVP_aead_chacha20_poly1305_ietf(void);

DESCRIPTION
     AEAD (Authenticated Encryption with Additional Data) couples confiden-
     tiality 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 au-
     thenticated but not included in the output.

     EVP_AEAD_CTX_init() initializes the context ctx for the given AEAD	algo-
     rithm aead.  The impl argument must be NULL for the default implementa-
     tion; 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 func-
     tion may be called	(with the same EVP_AEAD_CTX) concurrently with itself
     or	with EVP_AEAD_CTX_seal().  At most the number of input bytes are writ-
     ten 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 authenti-
     cates any additional data provided	in ad, the encrypted input and authen-
     tication tag being	written	as output out.	This function may be called
     (with the same 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_max_overhead().	 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
     A.	Langley	and W. Chang, ChaCha20 and Poly1305 based Cipher Suites	for
     TLS, draft-agl-tls-chacha20poly1305-04, November 2013.

     Y.	Nir and	A. Langley, ChaCha20 and Poly1305 for IETF Protocols, RFC
     7539, May 2015.

HISTORY
     AEAD is based on the implementation by Adam Langley for Chromium/Bor-
     ingSSL and	first appeared in OpenBSD 5.6.

BSD			       November	21, 2016			   BSD

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=EVP_AEAD_CTX_init&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help