crypto/cipher: improve documentation for AEAD

Give a link to the wikipedia page describing the mechanism and
explain better how to use the same buffer for input and output.

Change-Id: If6dfd6cf9c6dff0517cb715f60a11349dbdd91e0
Reviewed-on: https://go-review.googlesource.com/18103
Reviewed-by: Russ Cox <rsc@golang.org>

1 files changed, 9 insertions, 6 deletions

diff --git a/src/crypto/cipher/gcm.go b/src/crypto/cipher/gcm.go
index 3a0474f502..cf13319dfe 100644
--- a/src/crypto/cipher/gcm.go
+++ b/src/crypto/cipher/gcm.go
@@ -10,14 +10,15 @@ import (
 )
 
 // AEAD is a cipher mode providing authenticated encryption with associated
-// data.
+// data. For a description of the methodology, see
+//	https://en.wikipedia.org/wiki/Authenticated_encryption
 type AEAD interface {
 	// NonceSize returns the size of the nonce that must be passed to Seal
 	// and Open.
 	NonceSize() int
 
 	// Overhead returns the maximum difference between the lengths of a
-	// plaintext and ciphertext.
+	// plaintext and its ciphertext.
 	Overhead() int
 
 	// Seal encrypts and authenticates plaintext, authenticates the
@@ -25,8 +26,9 @@ type AEAD interface {
 	// slice. The nonce must be NonceSize() bytes long and unique for all
 	// time, for a given key.
 	//
-	// The plaintext and dst may alias exactly or not at all.
-	Seal(dst, nonce, plaintext, data []byte) []byte
+	// The plaintext and dst may alias exactly or not at all. To reuse
+	// plaintext's storage for the encrypted output, use plaintext[:0] as dst.
+	Seal(dst, nonce, plaintext, additionalData []byte) []byte
 
 	// Open decrypts and authenticates ciphertext, authenticates the
 	// additional data and, if successful, appends the resulting plaintext
@@ -34,8 +36,9 @@ type AEAD interface {
 	// bytes long and both it and the additional data must match the
 	// value passed to Seal.
 	//
-	// The ciphertext and dst may alias exactly or not at all.
-	Open(dst, nonce, ciphertext, data []byte) ([]byte, error)
+	// The ciphertext and dst may alias exactly or not at all. To reuse
+	// ciphertext's storage for the encrypted output, use ciphertext[:0] as dst.
+	Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
 }
 
 // gcmAble is an interface implemented by ciphers that have a specific optimized