libgo/go/crypto/cipher/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 // Utility routines
  64
  65 func dup(p []byte) []byte {
  66         q := make([]byte, len(p))
  67         copy(q, p)
  68         return q
  69 }