diff options
Diffstat (limited to 'src/include/openssl/aead.h')
| -rw-r--r-- | src/include/openssl/aead.h | 60 |
1 files changed, 49 insertions, 11 deletions
diff --git a/src/include/openssl/aead.h b/src/include/openssl/aead.h index 61cf3cd..dc453e3 100644 --- a/src/include/openssl/aead.h +++ b/src/include/openssl/aead.h @@ -115,18 +115,28 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_key_wrap(void); * See |EVP_aead_aes_128_key_wrap| for details. */ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_key_wrap(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. */ +OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_ctr_hmac_sha256(void); + +/* EVP_aead_aes_128_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_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); -/* TLS specific AEAD algorithms. +/* TLS-specific AEAD algorithms. * * These AEAD primitives do not meet the definition of generic AEADs. They are - * all specific to TLS in some fashion and should not be used outside of that - * context. They require an additional data of length 11 (the standard TLS one - * with the length omitted). They are also stateful, so a given |EVP_AEAD_CTX| - * may only be used for one of seal or open, but not both. */ + * 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_rc4_md5_tls(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_sha1_tls(void); @@ -144,11 +154,13 @@ OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_des_ede3_cbc_sha1_tls_implicit_iv(void); -/* SSLv3 specific AEAD algorithms. +/* SSLv3-specific AEAD algorithms. * * These AEAD primitives do not meet the definition of generic AEADs. They are - * all specific to SSLv3 in some fashion and should not be used outside of that - * context. */ + * 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_rc4_md5_ssl3(void); OPENSSL_EXPORT const EVP_AEAD *EVP_aead_rc4_sha1_ssl3(void); @@ -205,17 +217,35 @@ typedef struct evp_aead_ctx_st { * be used. */ #define EVP_AEAD_DEFAULT_TAG_LENGTH 0 -/* EVP_AEAD_init initializes |ctx| for the given AEAD algorithm from |impl|. +/* 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 initializes |ctx| for the given AEAD algorithm from |impl|. * The |impl| argument may be NULL to choose the default implementation. * 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. */ + * + * 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|. */ +/* 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_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 @@ -270,6 +300,14 @@ OPENSSL_EXPORT int EVP_AEAD_CTX_open(const EVP_AEAD_CTX *ctx, uint8_t *out, const uint8_t *ad, size_t ad_len); +/* Obscure functions. */ + +/* EVP_AEAD_CTX_get_rc4_state sets |*out_key| to point to an RC4 key structure. + * It returns one on success or zero if |ctx| doesn't have an RC4 key. */ +OPENSSL_EXPORT int EVP_AEAD_CTX_get_rc4_state(const EVP_AEAD_CTX *ctx, + const RC4_KEY **out_key); + + #if defined(__cplusplus) } /* extern C */ #endif |