Document the correct nonce length for AES-GCM.
It would be nice to restrict these, limiting the incorrect sizes to a
separate EVP_AEAD, but start by documenting this.
Bug: 34
Change-Id: I09845882f76a53a010355ceefd168d4fc10a0681
Reviewed-on: https://boringssl-review.googlesource.com/28745
Commit-Queue: David Benjamin <davidben@google.com>
Commit-Queue: Adam Langley <agl@google.com>
Reviewed-by: Adam Langley <agl@google.com>
CQ-Verified: CQ bot account: commit-bot@chromium.org <commit-bot@chromium.org>
diff --git a/include/openssl/aead.h b/include/openssl/aead.h
index 1d50197..ccce6f5 100644
--- a/include/openssl/aead.h
+++ b/include/openssl/aead.h
@@ -91,9 +91,21 @@
// AEAD algorithms.
// EVP_aead_aes_128_gcm is AES-128 in Galois Counter Mode.
+//
+// Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it
+// is specified to take a variable-length nonce, nonces with other lengths are
+// effectively randomized, which means one must consider collisions. Unless
+// implementing an existing protocol which has already specified incorrect
+// parameters, only use 12-byte nonces.
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_128_gcm(void);
// EVP_aead_aes_256_gcm is AES-256 in Galois Counter Mode.
+//
+// Note: AES-GCM should only be used with 12-byte (96-bit) nonces. Although it
+// is specified to take a variable-length nonce, nonces with other lengths are
+// effectively randomized, which means one must consider collisions. Unless
+// implementing an existing protocol which has already specified incorrect
+// parameters, only use 12-byte nonces.
OPENSSL_EXPORT const EVP_AEAD *EVP_aead_aes_256_gcm(void);
// EVP_aead_chacha20_poly1305 is the AEAD built from ChaCha20 and
