From 4e6750af81996424f26115be1b2d13665764db8a Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Tue, 22 Dec 2015 12:46:23 -0800 Subject: [PATCH] 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 --- src/crypto/cipher/gcm.go | 15 +++++++++------ 1 file 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 -- 2.50.0