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