diff options
Diffstat (limited to 'src/include/openssl/aead.h')
| -rw-r--r-- | src/include/openssl/aead.h | 498 |
1 files changed, 249 insertions, 249 deletions
diff --git a/src/include/openssl/aead.h b/src/include/openssl/aead.h index dd2e4187..7424e29c 100644 --- a/src/include/openssl/aead.h +++ b/src/include/openssl/aead.h @@ -22,271 +22,271 @@ extern "C" { #endif -/* Authenticated Encryption with Additional Data. - * - * AEAD couples confidentiality and integrity in a single primitive. AEAD - * algorithms take a key and then can 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 ciphertext. - * - * The |EVP_AEAD_CTX_init| function initialises an |EVP_AEAD_CTX| structure and - * performs any precomputation needed to use |aead| with |key|. The length of - * the key, |key_len|, is given in bytes. - * - * The |tag_len| argument contains the length of the tags, in bytes, and allows - * for the processing of truncated authenticators. A zero value indicates that - * the default tag length should be used and this is defined as - * |EVP_AEAD_DEFAULT_TAG_LENGTH| in order to make the code clear. Using - * truncated tags increases an attacker's chance of creating a valid forgery. - * Be aware that the attacker's chance may increase more than exponentially as - * would naively be expected. - * - * When no longer needed, the initialised |EVP_AEAD_CTX| structure must be - * passed to |EVP_AEAD_CTX_cleanup|, which will deallocate any memory used. - * - * With an |EVP_AEAD_CTX| in hand, one can seal and open messages. These - * operations are intended to meet the standard notions of privacy and - * authenticity for authenticated encryption. For formal definitions see - * Bellare and Namprempre, "Authenticated encryption: relations among notions - * and analysis of the generic composition paradigm," Lecture Notes in Computer - * Science B<1976> (2000), 531–545, - * http://www-cse.ucsd.edu/~mihir/papers/oem.html. - * - * When sealing messages, a nonce must be given. The length of the nonce is - * fixed by the AEAD in use and is returned by |EVP_AEAD_nonce_length|. *The - * nonce must be unique for all messages with the same key*. This is critically - * important - nonce reuse may completely undermine the security of the AEAD. - * Nonces may be predictable and public, so long as they are unique. Uniqueness - * may be achieved with a simple counter or, if large enough, may be generated - * randomly. The nonce must be passed into the "open" operation by the receiver - * so must either be implicit (e.g. a counter), or must be transmitted along - * with the sealed message. - * - * The "seal" and "open" operations are atomic - an entire message must be - * encrypted or decrypted in a single call. Large messages may have to be split - * up in order to accommodate this. When doing so, be mindful of the need not to - * repeat nonces and the possibility that an attacker could duplicate, reorder - * or drop message chunks. For example, using a single key for a given (large) - * message and sealing chunks with nonces counting from zero would be secure as - * long as the number of chunks was securely transmitted. (Otherwise an - * attacker could truncate the message by dropping chunks from the end.) - * - * The number of chunks could be transmitted by prefixing it to the plaintext, - * for example. This also assumes that no other message would ever use the same - * key otherwise the rule that nonces must be unique for a given key would be - * violated. - * - * The "seal" and "open" operations also permit additional data to be - * authenticated via the |ad| parameter. This data is not included in the - * ciphertext and must be identical for both the "seal" and "open" call. This - * permits implicit context to be authenticated but may be empty if not needed. - * - * The "seal" and "open" operations may work in-place if the |out| and |in| - * arguments are equal. Otherwise, if |out| and |in| alias, input data may be - * overwritten before it is read. This situation will cause an error. - * - * The "seal" and "open" operations return one on success and zero on error. */ - - -/* AEAD algorithms. */ - -/* EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode. */ +// Authenticated Encryption with Additional Data. +// +// AEAD couples confidentiality and integrity in a single primitive. AEAD +// algorithms take a key and then can 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 ciphertext. +// +// The |EVP_AEAD_CTX_init| function initialises an |EVP_AEAD_CTX| structure and +// performs any precomputation needed to use |aead| with |key|. The length of +// the key, |key_len|, is given in bytes. +// +// The |tag_len| argument contains the length of the tags, in bytes, and allows +// for the processing of truncated authenticators. A zero value indicates that +// the default tag length should be used and this is defined as +// |EVP_AEAD_DEFAULT_TAG_LENGTH| in order to make the code clear. Using +// truncated tags increases an attacker's chance of creating a valid forgery. +// Be aware that the attacker's chance may increase more than exponentially as +// would naively be expected. +// +// When no longer needed, the initialised |EVP_AEAD_CTX| structure must be +// passed to |EVP_AEAD_CTX_cleanup|, which will deallocate any memory used. +// +// With an |EVP_AEAD_CTX| in hand, one can seal and open messages. These +// operations are intended to meet the standard notions of privacy and +// authenticity for authenticated encryption. For formal definitions see +// Bellare and Namprempre, "Authenticated encryption: relations among notions +// and analysis of the generic composition paradigm," Lecture Notes in Computer +// Science B<1976> (2000), 531–545, +// http://www-cse.ucsd.edu/~mihir/papers/oem.html. +// +// When sealing messages, a nonce must be given. The length of the nonce is +// fixed by the AEAD in use and is returned by |EVP_AEAD_nonce_length|. *The +// nonce must be unique for all messages with the same key*. This is critically +// important - nonce reuse may completely undermine the security of the AEAD. +// Nonces may be predictable and public, so long as they are unique. Uniqueness +// may be achieved with a simple counter or, if large enough, may be generated +// randomly. The nonce must be passed into the "open" operation by the receiver +// so must either be implicit (e.g. a counter), or must be transmitted along +// with the sealed message. +// +// The "seal" and "open" operations are atomic - an entire message must be +// encrypted or decrypted in a single call. Large messages may have to be split +// up in order to accommodate this. When doing so, be mindful of the need not to +// repeat nonces and the possibility that an attacker could duplicate, reorder +// or drop message chunks. For example, using a single key for a given (large) +// message and sealing chunks with nonces counting from zero would be secure as +// long as the number of chunks was securely transmitted. (Otherwise an +// attacker could truncate the message by dropping chunks from the end.) +// +// The number of chunks could be transmitted by prefixing it to the plaintext, +// for example. This also assumes that no other message would ever use the same +// key otherwise the rule that nonces must be unique for a given key would be +// violated. +// +// The "seal" and "open" operations also permit additional data to be +// authenticated via the |ad| parameter. This data is not included in the +// ciphertext and must be identical for both the "seal" and "open" call. This +// permits implicit context to be authenticated but may be empty if not needed. +// +// The "seal" and "open" operations may work in-place if the |out| and |in| +// arguments are equal. Otherwise, if |out| and |in| alias, input data may be +// overwritten before it is read. This situation will cause an error. +// +// The "seal" and "open" operations return one on success and zero on error. + + +// AEAD algorithms. + +// EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void); -/* EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode. */ +// EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void); -/* EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and - * Poly1305 as described in RFC 7539. */ +// EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and +// Poly1305 as described in RFC 7539. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_chacha20_poly1305(void); -/* EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for - * authentication. The nonce is 12 bytes; the bottom 32-bits are used as the - * block counter, thus the maximum plaintext size is 64GB. */ +// EVP_aead_aes_128_ctr_hmac_sha256 is AES-128 in CTR mode with HMAC-SHA256 for +// authentication. The nonce is 12 bytes; the bottom 32-bits are used as the +// block counter, thus the maximum plaintext size is 64GB. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void); -/* EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for - * authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. */ +// EVP_aead_aes_256_ctr_hmac_sha256 is AES-256 in CTR mode with HMAC-SHA256 for +// authentication. See |EVP_aead_aes_128_ctr_hmac_sha256| for details. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_ctr_hmac_sha256(void); -/* EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See - * https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 */ +// EVP_aead_aes_128_gcm_siv is AES-128 in GCM-SIV mode. See +// https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_siv(void); -/* EVP_aead_aes_256_gcm_siv is AES-256 in GCM-SIV mode. See - * https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 */ +// EVP_aead_aes_256_gcm_siv is AES-256 in GCM-SIV mode. See +// https://tools.ietf.org/html/draft-irtf-cfrg-gcmsiv-02 OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_siv(void); -/* EVP_has_aes_hardware returns one if we enable hardware support for fast and - * constant-time AES-GCM. */ +// EVP_has_aes_hardware returns one if we enable hardware support for fast and +// constant-time AES-GCM. OPENSSL_EXPORT int EVP_has_aes_hardware(void); -/* Utility functions. */ +// Utility functions. -/* EVP_AEAD_key_length returns the length, in bytes, of the keys used by - * |aead|. */ +// EVP_AEAD_key_length returns the length, in bytes, of the keys used by +// |aead|. OPENSSL_EXPORT size_t EVP_AEAD_key_length(const EVP_AEAD *aead); -/* EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce - * for |aead|. */ +// EVP_AEAD_nonce_length returns the length, in bytes, of the per-message nonce +// for |aead|. OPENSSL_EXPORT size_t EVP_AEAD_nonce_length(const EVP_AEAD *aead); -/* EVP_AEAD_max_overhead returns the maximum number of additional bytes added - * by the act of sealing data with |aead|. */ +// EVP_AEAD_max_overhead returns the maximum number of additional bytes added +// by the act of sealing data with |aead|. OPENSSL_EXPORT size_t EVP_AEAD_max_overhead(const EVP_AEAD *aead); -/* EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This - * is the largest value that can be passed as |tag_len| to - * |EVP_AEAD_CTX_init|. */ +// EVP_AEAD_max_tag_len returns the maximum tag length when using |aead|. This +// is the largest value that can be passed as |tag_len| to +// |EVP_AEAD_CTX_init|. OPENSSL_EXPORT size_t EVP_AEAD_max_tag_len(const EVP_AEAD *aead); -/* AEAD operations. */ +// AEAD operations. -/* An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key - * and message-independent IV. */ +// An EVP_AEAD_CTX represents an AEAD algorithm configured with a specific key +// and message-independent IV. typedef struct evp_aead_ctx_st { const EVP_AEAD *aead; - /* aead_state is an opaque pointer to whatever state the AEAD needs to - * maintain. */ + // aead_state is an opaque pointer to whatever state the AEAD needs to + // maintain. void *aead_state; - /* tag_len may contain the actual length of the authentication tag if it is - * known at initialization time. */ + // tag_len may contain the actual length of the authentication tag if it is + // known at initialization time. uint8_t tag_len; } EVP_AEAD_CTX; -/* EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by - * any AEAD defined in this header. */ +// EVP_AEAD_MAX_KEY_LENGTH contains the maximum key length used by +// any AEAD defined in this header. #define EVP_AEAD_MAX_KEY_LENGTH 80 -/* EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by - * any AEAD defined in this header. */ +// EVP_AEAD_MAX_NONCE_LENGTH contains the maximum nonce length used by +// any AEAD defined in this header. #define EVP_AEAD_MAX_NONCE_LENGTH 16 -/* EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD - * defined in this header. */ +// EVP_AEAD_MAX_OVERHEAD contains the maximum overhead used by any AEAD +// defined in this header. #define EVP_AEAD_MAX_OVERHEAD 64 -/* EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to - * EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should - * be used. */ +// EVP_AEAD_DEFAULT_TAG_LENGTH is a magic value that can be passed to +// EVP_AEAD_CTX_init to indicate that the default tag length for an AEAD should +// be used. #define EVP_AEAD_DEFAULT_TAG_LENGTH 0 -/* EVP_AEAD_CTX_zero sets an uninitialized |ctx| to the zero state. It must be - * initialized with |EVP_AEAD_CTX_init| before use. It is safe, but not - * necessary, to call |EVP_AEAD_CTX_cleanup| in this state. This may be used for - * more uniform cleanup of |EVP_AEAD_CTX|. */ +// EVP_AEAD_CTX_zero sets an uninitialized |ctx| to the zero state. It must be +// initialized with |EVP_AEAD_CTX_init| before use. It is safe, but not +// necessary, to call |EVP_AEAD_CTX_cleanup| in this state. This may be used for +// more uniform cleanup of |EVP_AEAD_CTX|. OPENSSL_EXPORT void EVP_AEAD_CTX_zero(EVP_AEAD_CTX *ctx); -/* EVP_AEAD_CTX_new allocates an |EVP_AEAD_CTX|, calls |EVP_AEAD_CTX_init| and - * returns the |EVP_AEAD_CTX|, or NULL on error. */ +// EVP_AEAD_CTX_new allocates an |EVP_AEAD_CTX|, calls |EVP_AEAD_CTX_init| and +// returns the |EVP_AEAD_CTX|, or NULL on error. OPENSSL_EXPORT EVP_AEAD_CTX *EVP_AEAD_CTX_new(const EVP_AEAD *aead, const uint8_t *key, size_t key_len, size_t tag_len); -/* EVP_AEAD_CTX_free calls |EVP_AEAD_CTX_cleanup| and |OPENSSL_free| on - * |ctx|. */ +// EVP_AEAD_CTX_free calls |EVP_AEAD_CTX_cleanup| and |OPENSSL_free| on +// |ctx|. OPENSSL_EXPORT void EVP_AEAD_CTX_free(EVP_AEAD_CTX *ctx); -/* EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm. The |impl| - * argument is ignored and should be NULL. Authentication tags may be truncated - * by passing a size as |tag_len|. A |tag_len| of zero indicates the default - * tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for - * readability. - * - * Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In - * the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's - * harmless to do so. */ +// EVP_AEAD_CTX_init initializes |ctx| for the given AEAD algorithm. The |impl| +// argument is ignored and should be NULL. Authentication tags may be truncated +// by passing a size as |tag_len|. A |tag_len| of zero indicates the default +// tag length and this is defined as EVP_AEAD_DEFAULT_TAG_LENGTH for +// readability. +// +// Returns 1 on success. Otherwise returns 0 and pushes to the error stack. In +// the error case, you do not need to call |EVP_AEAD_CTX_cleanup|, but it's +// harmless to do so. OPENSSL_EXPORT int EVP_AEAD_CTX_init(EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len, size_t tag_len, ENGINE *impl); -/* EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to - * call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to - * all zeros. */ +// EVP_AEAD_CTX_cleanup frees any data allocated by |ctx|. It is a no-op to +// call |EVP_AEAD_CTX_cleanup| on a |EVP_AEAD_CTX| that has been |memset| to +// all zeros. OPENSSL_EXPORT void EVP_AEAD_CTX_cleanup(EVP_AEAD_CTX *ctx); -/* EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and - * authenticates |ad_len| bytes from |ad| and writes the result to |out|. It - * returns one on success and zero otherwise. - * - * This function may be called concurrently with itself or any other seal/open - * function on the same |EVP_AEAD_CTX|. - * - * At most |max_out_len| bytes are written to |out| and, in order to ensure - * success, |max_out_len| should be |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 |nonce|, |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. If any error occurs, |out| will be - * filled with zero bytes and |*out_len| set to zero. - * - * If |in| and |out| alias then |out| must be == |in|. */ +// EVP_AEAD_CTX_seal encrypts and authenticates |in_len| bytes from |in| and +// authenticates |ad_len| bytes from |ad| and writes the result to |out|. It +// returns one on success and zero otherwise. +// +// This function may be called concurrently with itself or any other seal/open +// function on the same |EVP_AEAD_CTX|. +// +// At most |max_out_len| bytes are written to |out| and, in order to ensure +// success, |max_out_len| should be |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 |nonce|, |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. If any error occurs, |out| will be +// filled with zero bytes and |*out_len| set to zero. +// +// If |in| and |out| alias then |out| must be == |in|. OPENSSL_EXPORT int EVP_AEAD_CTX_seal(const EVP_AEAD_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len, const uint8_t *nonce, size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *ad, size_t ad_len); -/* EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes - * from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on - * success and zero otherwise. - * - * This function may be called concurrently with itself or any other seal/open - * function on the same |EVP_AEAD_CTX|. - * - * At most |in_len| bytes are written to |out|. In order to ensure success, - * |max_out_len| should be at least |in_len|. On successful return, |*out_len| - * is set to the the actual number of bytes written. - * - * The length of |nonce|, |nonce_len|, must be equal to the result of - * |EVP_AEAD_nonce_length| for this AEAD. - * - * |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is - * insufficient, zero will be returned. If any error occurs, |out| will be - * filled with zero bytes and |*out_len| set to zero. - * - * If |in| and |out| alias then |out| must be == |in|. */ +// EVP_AEAD_CTX_open authenticates |in_len| bytes from |in| and |ad_len| bytes +// from |ad| and decrypts at most |in_len| bytes into |out|. It returns one on +// success and zero otherwise. +// +// This function may be called concurrently with itself or any other seal/open +// function on the same |EVP_AEAD_CTX|. +// +// At most |in_len| bytes are written to |out|. In order to ensure success, +// |max_out_len| should be at least |in_len|. On successful return, |*out_len| +// is set to the the actual number of bytes written. +// +// The length of |nonce|, |nonce_len|, must be equal to the result of +// |EVP_AEAD_nonce_length| for this AEAD. +// +// |EVP_AEAD_CTX_open| never results in a partial output. If |max_out_len| is +// insufficient, zero will be returned. If any error occurs, |out| will be +// filled with zero bytes and |*out_len| set to zero. +// +// If |in| and |out| alias then |out| must be == |in|. OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out, size_t *out_len, size_t max_out_len, const uint8_t *nonce, size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *ad, size_t ad_len); -/* EVP_AEAD_CTX_seal_scatter encrypts and authenticates |in_len| bytes from |in| - * and authenticates |ad_len| bytes from |ad|. It writes |in_len| bytes of - * ciphertext to |out| and the authentication tag to |out_tag|. It returns one - * on success and zero otherwise. - * - * This function may be called concurrently with itself or any other seal/open - * function on the same |EVP_AEAD_CTX|. - * - * Exactly |in_len| bytes are written to |out|, and up to - * |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful - * return, |*out_tag_len| is set to the actual number of bytes written to - * |out_tag|. - * - * |extra_in| may point to an additional plaintext input buffer if the cipher - * supports it. If present, |extra_in_len| additional bytes of plaintext are - * encrypted and authenticated, and the ciphertext is written (before the tag) - * to |out_tag|. |max_out_tag_len| must be sized to allow for the additional - * |extra_in_len| bytes. - * - * The length of |nonce|, |nonce_len|, must be equal to the result of - * |EVP_AEAD_nonce_length| for this AEAD. - * - * |EVP_AEAD_CTX_seal_scatter| never results in a partial output. If - * |max_out_tag_len| is insufficient, zero will be returned. If any error - * occurs, |out| and |out_tag| will be filled with zero bytes and |*out_tag_len| - * set to zero. - * - * If |in| and |out| alias then |out| must be == |in|. |out_tag| may not alias - * any other argument. */ +// EVP_AEAD_CTX_seal_scatter encrypts and authenticates |in_len| bytes from |in| +// and authenticates |ad_len| bytes from |ad|. It writes |in_len| bytes of +// ciphertext to |out| and the authentication tag to |out_tag|. It returns one +// on success and zero otherwise. +// +// This function may be called concurrently with itself or any other seal/open +// function on the same |EVP_AEAD_CTX|. +// +// Exactly |in_len| bytes are written to |out|, and up to +// |EVP_AEAD_max_overhead+extra_in_len| bytes to |out_tag|. On successful +// return, |*out_tag_len| is set to the actual number of bytes written to +// |out_tag|. +// +// |extra_in| may point to an additional plaintext input buffer if the cipher +// supports it. If present, |extra_in_len| additional bytes of plaintext are +// encrypted and authenticated, and the ciphertext is written (before the tag) +// to |out_tag|. |max_out_tag_len| must be sized to allow for the additional +// |extra_in_len| bytes. +// +// The length of |nonce|, |nonce_len|, must be equal to the result of +// |EVP_AEAD_nonce_length| for this AEAD. +// +// |EVP_AEAD_CTX_seal_scatter| never results in a partial output. If +// |max_out_tag_len| is insufficient, zero will be returned. If any error +// occurs, |out| and |out_tag| will be filled with zero bytes and |*out_tag_len| +// set to zero. +// +// If |in| and |out| alias then |out| must be == |in|. |out_tag| may not alias +// any other argument. OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter( const EVP_AEAD_CTX *ctx, uint8_t *out, uint8_t *out_tag, size_t *out_tag_len, size_t max_out_tag_len, @@ -295,39 +295,39 @@ OPENSSL_EXPORT int EVP_AEAD_CTX_seal_scatter( const uint8_t *extra_in, size_t extra_in_len, const uint8_t *ad, size_t ad_len); -/* EVP_AEAD_CTX_open_gather decrypts and authenticates |in_len| bytes from |in| - * and authenticates |ad_len| bytes from |ad| using |in_tag_len| bytes of - * authentication tag from |in_tag|. If successful, it writes |in_len| bytes of - * plaintext to |out|. It returns one on success and zero otherwise. - * - * This function may be called concurrently with itself or any other seal/open - * function on the same |EVP_AEAD_CTX|. - * - * The length of |nonce|, |nonce_len|, must be equal to the result of - * |EVP_AEAD_nonce_length| for this AEAD. - * - * |EVP_AEAD_CTX_open_gather| never results in a partial output. If any error - * occurs, |out| will be filled with zero bytes. - * - * If |in| and |out| alias then |out| must be == |in|. */ +// EVP_AEAD_CTX_open_gather decrypts and authenticates |in_len| bytes from |in| +// and authenticates |ad_len| bytes from |ad| using |in_tag_len| bytes of +// authentication tag from |in_tag|. If successful, it writes |in_len| bytes of +// plaintext to |out|. It returns one on success and zero otherwise. +// +// This function may be called concurrently with itself or any other seal/open +// function on the same |EVP_AEAD_CTX|. +// +// The length of |nonce|, |nonce_len|, must be equal to the result of +// |EVP_AEAD_nonce_length| for this AEAD. +// +// |EVP_AEAD_CTX_open_gather| never results in a partial output. If any error +// occurs, |out| will be filled with zero bytes. +// +// If |in| and |out| alias then |out| must be == |in|. OPENSSL_EXPORT int EVP_AEAD_CTX_open_gather( const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *nonce, size_t nonce_len, const uint8_t *in, size_t in_len, const uint8_t *in_tag, size_t in_tag_len, const uint8_t *ad, size_t ad_len); -/* EVP_AEAD_CTX_aead returns the underlying AEAD for |ctx|, or NULL if one has - * not been set. */ +// EVP_AEAD_CTX_aead returns the underlying AEAD for |ctx|, or NULL if one has +// not been set. OPENSSL_EXPORT const EVP_AEAD *EVP_AEAD_CTX_aead(const EVP_AEAD_CTX *ctx); -/* TLS-specific AEAD algorithms. - * - * These AEAD primitives do not meet the definition of generic AEADs. They are - * all specific to TLS and should not be used outside of that context. They must - * be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may - * not be used concurrently. Any nonces are used as IVs, so they must be - * unpredictable. They only accept an |ad| parameter of length 11 (the standard - * TLS one with length omitted). */ +// TLS-specific AEAD algorithms. +// +// These AEAD primitives do not meet the definition of generic AEADs. They are +// all specific to TLS and should not be used outside of that context. They must +// be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, and may +// not be used concurrently. Any nonces are used as IVs, so they must be +// unpredictable. They only accept an |ad| parameter of length 11 (the standard +// TLS one with length omitted). OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_tls_implicit_iv(void); @@ -343,22 +343,22 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_tls(void); -/* EVP_aead_aes_128_gcm_tls12 is AES-128 in Galois Counter Mode using the TLS - * 1.2 nonce construction. */ +// EVP_aead_aes_128_gcm_tls12 is AES-128 in Galois Counter Mode using the TLS +// 1.2 nonce construction. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm_tls12(void); -/* EVP_aead_aes_256_gcm_tls12 is AES-256 in Galois Counter Mode using the TLS - * 1.2 nonce construction. */ +// EVP_aead_aes_256_gcm_tls12 is AES-256 in Galois Counter Mode using the TLS +// 1.2 nonce construction. OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm_tls12(void); -/* SSLv3-specific AEAD algorithms. - * - * These AEAD primitives do not meet the definition of generic AEADs. They are - * all specific to SSLv3 and should not be used outside of that context. They - * must be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, - * and may not be used concurrently. They only accept an |ad| parameter of - * length 9 (the standard TLS one with length and version omitted). */ +// SSLv3-specific AEAD algorithms. +// +// These AEAD primitives do not meet the definition of generic AEADs. They are +// all specific to SSLv3 and should not be used outside of that context. They +// must be initialized with |EVP_AEAD_CTX_init_with_direction|, are stateful, +// and may not be used concurrently. They only accept an |ad| parameter of +// length 9 (the standard TLS one with length and version omitted). OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_cbc_sha1_ssl3(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_cbc_sha1_ssl3(void); @@ -366,33 +366,33 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_ssl3(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_null_sha1_ssl3(void); -/* Obscure functions. */ +// Obscure functions. -/* evp_aead_direction_t denotes the direction of an AEAD operation. */ +// evp_aead_direction_t denotes the direction of an AEAD operation. enum evp_aead_direction_t { evp_aead_open, evp_aead_seal, }; -/* EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal - * AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a - * given direction. */ +// EVP_AEAD_CTX_init_with_direction calls |EVP_AEAD_CTX_init| for normal +// AEADs. For TLS-specific and SSL3-specific AEADs, it initializes |ctx| for a +// given direction. OPENSSL_EXPORT int EVP_AEAD_CTX_init_with_direction( EVP_AEAD_CTX *ctx, const EVP_AEAD *aead, const uint8_t *key, size_t key_len, size_t tag_len, enum evp_aead_direction_t dir); -/* EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and - * sets |*out_iv| to point to that many bytes of the current IV. This is only - * meaningful for AEADs with implicit IVs (i.e. CBC mode in SSLv3 and TLS 1.0). - * - * It returns one on success or zero on error. */ +// EVP_AEAD_CTX_get_iv sets |*out_len| to the length of the IV for |ctx| and +// sets |*out_iv| to point to that many bytes of the current IV. This is only +// meaningful for AEADs with implicit IVs (i.e. CBC mode in SSLv3 and TLS 1.0). +// +// It returns one on success or zero on error. OPENSSL_EXPORT int EVP_AEAD_CTX_get_iv(const EVP_AEAD_CTX *ctx, const uint8_t **out_iv, size_t *out_len); -/* EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by - * |EVP_AEAD_CTX_seal_scatter| and writes it to |*out_tag_len|. It returns one - * on success or zero on error. |in_len| and |extra_in_len| must equal the - * arguments of the same names passed to |EVP_AEAD_CTX_seal_scatter|. */ +// EVP_AEAD_CTX_tag_len computes the exact byte length of the tag written by +// |EVP_AEAD_CTX_seal_scatter| and writes it to |*out_tag_len|. It returns one +// on success or zero on error. |in_len| and |extra_in_len| must equal the +// arguments of the same names passed to |EVP_AEAD_CTX_seal_scatter|. OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx, size_t *out_tag_len, const size_t in_len, @@ -400,7 +400,7 @@ OPENSSL_EXPORT int EVP_AEAD_CTX_tag_len(const EVP_AEAD_CTX *ctx, #if defined(__cplusplus) -} /* extern C */ +} // extern C #if !defined(BORINGSSL_NO_CXX) extern "C++" { @@ -420,4 +420,4 @@ BORINGSSL_MAKE_DELETER(EVP_AEAD_CTX, EVP_AEAD_CTX_free) #endif -#endif /* OPENSSL_HEADER_AEAD_H */ +#endif // OPENSSL_HEADER_AEAD_H |