cipher.go

     1  // Copyright 2010 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package cipher implements standard block cipher modes that can be wrapped
     6  // around low-level block cipher implementations.
     7  // See https://csrc.nist.gov/groups/ST/toolkit/BCM/current_modes.html
     8  // and NIST Special Publication 800-38A.
     9  package cipher
    10  
    11  // A Block represents an implementation of block cipher
    12  // using a given key. It provides the capability to encrypt
    13  // or decrypt individual blocks. The mode implementations
    14  // extend that capability to streams of blocks.
    15  type Block interface {
    16  	// BlockSize returns the cipher's block size.
    17  	BlockSize() int
    18  
    19  	// Encrypt encrypts the first block in src into dst.
    20  	// Dst and src must overlap entirely or not at all.
    21  	Encrypt(dst, src []byte)
    22  
    23  	// Decrypt decrypts the first block in src into dst.
    24  	// Dst and src must overlap entirely or not at all.
    25  	Decrypt(dst, src []byte)
    26  }
    27  
    28  // A Stream represents a stream cipher.
    29  type Stream interface {
    30  	// XORKeyStream XORs each byte in the given slice with a byte from the
    31  	// cipher's key stream. Dst and src must overlap entirely or not at all.
    32  	//
    33  	// If len(dst) < len(src), XORKeyStream should panic. It is acceptable
    34  	// to pass a dst bigger than src, and in that case, XORKeyStream will
    35  	// only update dst[:len(src)] and will not touch the rest of dst.
    36  	//
    37  	// Multiple calls to XORKeyStream behave as if the concatenation of
    38  	// the src buffers was passed in a single run. That is, Stream
    39  	// maintains state and does not reset at each XORKeyStream call.
    40  	XORKeyStream(dst, src []byte)
    41  }
    42  
    43  // A BlockMode represents a block cipher running in a block-based mode (CBC,
    44  // ECB etc).
    45  type BlockMode interface {
    46  	// BlockSize returns the mode's block size.
    47  	BlockSize() int
    48  
    49  	// CryptBlocks encrypts or decrypts a number of blocks. The length of
    50  	// src must be a multiple of the block size. Dst and src must overlap
    51  	// entirely or not at all.
    52  	//
    53  	// If len(dst) < len(src), CryptBlocks should panic. It is acceptable
    54  	// to pass a dst bigger than src, and in that case, CryptBlocks will
    55  	// only update dst[:len(src)] and will not touch the rest of dst.
    56  	//
    57  	// Multiple calls to CryptBlocks behave as if the concatenation of
    58  	// the src buffers was passed in a single run. That is, BlockMode
    59  	// maintains state and does not reset at each CryptBlocks call.
    60  	CryptBlocks(dst, src []byte)
    61  }
    62  
    63  // AEAD is a cipher mode providing authenticated encryption with associated
    64  // data. For a description of the methodology, see
    65  // https://en.wikipedia.org/wiki/Authenticated_encryption.
    66  type AEAD interface {
    67  	// NonceSize returns the size of the nonce that must be passed to Seal
    68  	// and Open.
    69  	NonceSize() int
    70  
    71  	// Overhead returns the maximum difference between the lengths of a
    72  	// plaintext and its ciphertext.
    73  	Overhead() int
    74  
    75  	// Seal encrypts and authenticates plaintext, authenticates the
    76  	// additional data and appends the result to dst, returning the updated
    77  	// slice. The nonce must be NonceSize() bytes long and unique for all
    78  	// time, for a given key.
    79  	//
    80  	// To reuse plaintext's storage for the encrypted output, use plaintext[:0]
    81  	// as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.
    82  	// dst and additionalData may not overlap.
    83  	Seal(dst, nonce, plaintext, additionalData []byte) []byte
    84  
    85  	// Open decrypts and authenticates ciphertext, authenticates the
    86  	// additional data and, if successful, appends the resulting plaintext
    87  	// to dst, returning the updated slice. The nonce must be NonceSize()
    88  	// bytes long and both it and the additional data must match the
    89  	// value passed to Seal.
    90  	//
    91  	// To reuse ciphertext's storage for the decrypted output, use ciphertext[:0]
    92  	// as dst. Otherwise, the remaining capacity of dst must not overlap ciphertext.
    93  	// dst and additionalData may not overlap.
    94  	//
    95  	// Even if the function fails, the contents of dst, up to its capacity,
    96  	// may be overwritten.
    97  	Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
    98  }
    99
View as plain text