commit 1b3a95122de541aa4afb50c8360bc83ce6d676d4
author David Benjamin <davidben@chromium.org> Tue Mar 17 18:09:23 2015 -0400
committer Adam Langley <agl@google.com> Tue Mar 17 23:55:56 2015 +0000
tree 7461a96265affbdd927432f13460794ab064bdf0
parent 1d1562d9b538fd2b63ca2a0e0958080f21a41b06

Document exactly how the stateful AEADs are weird.

Probably worth spelling that out.

Change-Id: Ie8815fc645e2836f4fb5bf7d09df1e5326751544
Reviewed-on: https://boringssl-review.googlesource.com/3970
Reviewed-by: Adam Langley <agl@google.com>

include/openssl/aead.h

diff --git a/include/openssl/aead.h b/include/openssl/aead.h
index 861de99..8aedb1b 100644
--- a/include/openssl/aead.h
+++ b/include/openssl/aead.h
@@ -120,13 +120,14 @@
 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 +145,13 @@
 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);