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>

diff --git a/src/crypto/cipher/gcm.go b/src/crypto/cipher/gcm.go
index 3a0474f502436ed10700efaeda7e3e62bbfcb5ab..cf13319dfe6e1727799090b236cc052dc1abf926 100644 (file)
--- 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