diff --git a/src/crypto/cipher/gcm.go b/src/crypto/cipher/gcm.go index 3a0474f502436..cf13319dfe6e1 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