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.
9package 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.
15type 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.
29type 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).
45type 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