Overview

Package cipher implements standard block cipher modes that can be wrapped around
low-level block cipher implementations. See
http://csrc.nist.gov/groups/ST/toolkit/BCM/current_modes.html and NIST Special
Publication 800-38A.

Index

Package files

cbc.go cipher.go gcm.go ofb.go

AEAD is a cipher mode providing authenticated encryption with associated data.
For a description of the methodology, see

  1. https://en.wikipedia.org/wiki/Authenticated_encryption

func NewGCM

  1. func NewGCM(cipher Block) (, error)

NewGCM returns the given 128-bit, block cipher wrapped in Galois Counter Mode
with the standard nonce length.

In general, the GHASH operation performed by this implementation of GCM is not
constant-time. An exception is when the underlying Block was created by
aes.NewCipher on systems with hardware support for AES. See the crypto/aes
package documentation for details.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // Seal/Open calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. // When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
  6. key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
  7. ciphertext, _ := hex.DecodeString("c3aaa29f002ca75870806e44086700f62ce4d43e902b3888e23ceff797a7a471")
  8. nonce, _ := hex.DecodeString("64a9433eae7ccceee2fc0eda")
  10. block, err := aes.NewCipher(key)
  11. if err != nil {
  12.     panic(err.Error())
  13. }
  15. aesgcm, err := cipher.NewGCM(block)
  16. if err != nil {
  17.     panic(err.Error())
  18. }
  20. plaintext, err := aesgcm.Open(nil, nonce, ciphertext, nil)
  21. if err != nil {
  22.     panic(err.Error())
  23. }
  25. fmt.Printf("%s\n", plaintext)
  26. // Output: exampleplaintext


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // Seal/Open calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. // When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
  6. key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
  7. plaintext := []byte("exampleplaintext")
  9. block, err := aes.NewCipher(key)
  10. if err != nil {
  11.     panic(err.Error())
  12. }
  14. // Never use more than 2^32 random nonces with a given key because of the risk of a repeat.
  15. nonce := make([]byte, 12)
  16. if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
  17.     panic(err.Error())
  18. }
  20. aesgcm, err := cipher.NewGCM(block)
  21. if err != nil {
  22.     panic(err.Error())
  23. }
  25. ciphertext := aesgcm.Seal(nil, nonce, plaintext, nil)
  26. fmt.Printf("%x\n", ciphertext)

func 

  1. func NewGCMWithNonceSize(cipher , size int) (, error)

NewGCMWithNonceSize returns the given 128-bit, block cipher wrapped in Galois
Counter Mode, which accepts nonces of the given length.

Only use this function if you require compatibility with an existing
cryptosystem that uses non-standard nonce lengths. All other users should use
NewGCM, which is faster and more resistant to misuse.

type 

  1. type Block interface {
  2.     // BlockSize returns the cipher's block size.
  3.     BlockSize() 
  4.  
  5.     // Encrypt encrypts the first block in src into dst.
  6.     // Dst and src must overlap entirely or not at all.
  7.     Encrypt(dst, src []byte)
  8.  
  9.     // Decrypt decrypts the first block in src into dst.
  10.     // Dst and src must overlap entirely or not at all.
  11.     Decrypt(dst, src [])
  12. }

A Block represents an implementation of block cipher using a given key. It
provides the capability to encrypt or decrypt individual blocks. The mode
implementations extend that capability to streams of blocks.

type BlockMode

  1. type BlockMode interface {
  2.     // BlockSize returns the mode's block size.
  3.     BlockSize() int
  4.  
  5.     // CryptBlocks encrypts or decrypts a number of blocks. The length of
  6.     // src must be a multiple of the block size. Dst and src must overlap
  7.     // entirely or not at all.
  8.     //
  9.     // If len(dst) < len(src), CryptBlocks should panic. It is acceptable
  10.     // to pass a dst bigger than src, and in that case, CryptBlocks will
  11.     // only update dst[:len(src)] and will not touch the rest of dst.
  12.     //
  13.     // Multiple calls to CryptBlocks behave as if the concatenation of
  14.     // the src buffers was passed in a single run. That is, BlockMode
  15.     // maintains state and does not reset at each CryptBlocks call.
  16.     CryptBlocks(dst, src [])

A BlockMode represents a block cipher running in a block-based mode (CBC, ECB
etc).

  1. func NewCBCDecrypter(b Block, iv []) BlockMode

NewCBCDecrypter returns a BlockMode which decrypts in cipher block chaining
mode, using the given Block. The length of iv must be the same as the Block’s
block size and must match the iv used to encrypt the data.


Example:

func NewCBCEncrypter

  1. func NewCBCEncrypter(b Block, iv []) BlockMode

NewCBCEncrypter returns a BlockMode which encrypts in cipher block chaining
mode, using the given Block. The length of iv must be the same as the Block’s
block size.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // NewCipher calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. key, _ := hex.DecodeString("6368616e676520746869732070617373")
  6. plaintext := []byte("exampleplaintext")
  8. // CBC mode works on blocks so plaintexts may need to be padded to the
  9. // next whole block. For an example of such padding, see
  10. // https://tools.ietf.org/html/rfc5246#section-6.2.3.2. Here we'll
  11. // assume that the plaintext is already of the correct length.
  12. if len(plaintext)%aes.BlockSize != 0 {
  13.     panic("plaintext is not a multiple of the block size")
  14. }
  16. block, err := aes.NewCipher(key)
  17. if err != nil {
  18.     panic(err)
  19. }
  21. // The IV needs to be unique, but not secure. Therefore it's common to
  22. // include it at the beginning of the ciphertext.
  23. ciphertext := make([]byte, aes.BlockSize+len(plaintext))
  24. iv := ciphertext[:aes.BlockSize]
  25. if _, err := io.ReadFull(rand.Reader, iv); err != nil {
  26.     panic(err)
  27. }
  29. mode := cipher.NewCBCEncrypter(block, iv)
  30. mode.CryptBlocks(ciphertext[aes.BlockSize:], plaintext)
  33. // (i.e. by using crypto/hmac) as well as being encrypted in order to
  34. // be secure.
  36. fmt.Printf("%x\n", ciphertext)

  1. type Stream interface {
  2.     // XORKeyStream XORs each byte in the given slice with a byte from the
  3.     // cipher's key stream. Dst and src must overlap entirely or not at all.
  4.     //
  5.     // If len(dst) < len(src), XORKeyStream should panic. It is acceptable
  6.     // to pass a dst bigger than src, and in that case, XORKeyStream will
  7.     // only update dst[:len(src)] and will not touch the rest of dst.
  8.     //
  9.     // Multiple calls to XORKeyStream behave as if the concatenation of
  10.     // the src buffers was passed in a single run. That is, Stream
  11.     // maintains state and does not reset at each XORKeyStream call.
  12.     XORKeyStream(dst, src []byte)
  13. }

A Stream represents a stream cipher.

func 

  1. func NewCFBDecrypter(block , iv []byte)

NewCFBDecrypter returns a Stream which decrypts with cipher feedback mode, using
the given Block. The iv must be the same length as the Block’s block size.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // NewCipher calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. key, _ := hex.DecodeString("6368616e676520746869732070617373")
  6. ciphertext, _ := hex.DecodeString("7dd015f06bec7f1b8f6559dad89f4131da62261786845100056b353194ad")
  8. block, err := aes.NewCipher(key)
  9. if err != nil {
  10.     panic(err)
  11. }
  13. // The IV needs to be unique, but not secure. Therefore it's common to
  14. // include it at the beginning of the ciphertext.
  15. if len(ciphertext) < aes.BlockSize {
  16.     panic("ciphertext too short")
  17. }
  18. iv := ciphertext[:aes.BlockSize]
  19. ciphertext = ciphertext[aes.BlockSize:]
  21. stream := cipher.NewCFBDecrypter(block, iv)
  23. // XORKeyStream can work in-place if the two arguments are the same.
  24. stream.XORKeyStream(ciphertext, ciphertext)
  25. fmt.Printf("%s", ciphertext)
  26. // Output: some plaintext

func 

  1. func NewCFBEncrypter(block , iv []byte)

NewCFBEncrypter returns a Stream which encrypts with cipher feedback mode, using
the given Block. The iv must be the same length as the Block’s block size.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // NewCipher calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. key, _ := hex.DecodeString("6368616e676520746869732070617373")
  6. plaintext := []byte("some plaintext")
  8. block, err := aes.NewCipher(key)
  9. if err != nil {
  10.     panic(err)
  11. }
  13. // The IV needs to be unique, but not secure. Therefore it's common to
  14. // include it at the beginning of the ciphertext.
  15. ciphertext := make([]byte, aes.BlockSize+len(plaintext))
  16. iv := ciphertext[:aes.BlockSize]
  17. if _, err := io.ReadFull(rand.Reader, iv); err != nil {
  18.     panic(err)
  19. }
  21. stream := cipher.NewCFBEncrypter(block, iv)
  22. stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
  24. // It's important to remember that ciphertexts must be authenticated
  25. // (i.e. by using crypto/hmac) as well as being encrypted in order to
  26. // be secure.
  27. fmt.Printf("%x\n", ciphertext)

  1. func NewCTR(block , iv []byte)

NewCTR returns a Stream which encrypts/decrypts using the given Block in counter
mode. The length of iv must be the same as the Block’s block size.


Example:

func 

  1. func NewOFB(b , iv []byte)

NewOFB returns a Stream that encrypts or decrypts using the block cipher b in
output feedback mode. The initialization vector iv’s length must be equal to b’s
block size.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // NewCipher calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. key, _ := hex.DecodeString("6368616e676520746869732070617373")
  6. plaintext := []byte("some plaintext")
  7. block, err := aes.NewCipher(key)
  8. if err != nil {
  9.     panic(err)
  10. }
  12. // The IV needs to be unique, but not secure. Therefore it's common to
  13. // include it at the beginning of the ciphertext.
  14. ciphertext := make([]byte, aes.BlockSize+len(plaintext))
  15. iv := ciphertext[:aes.BlockSize]
  16. if _, err := io.ReadFull(rand.Reader, iv); err != nil {
  17.     panic(err)
  18. }
  20. stream := cipher.NewOFB(block, iv)
  21. stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
  23. // It's important to remember that ciphertexts must be authenticated
  24. // (i.e. by using crypto/hmac) as well as being encrypted in order to
  25. // be secure.
  28. // also decrypt that ciphertext with NewOFB.
  30. plaintext2 := make([]byte, len(plaintext))
  31. stream = cipher.NewOFB(block, iv)
  32. stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:])
  34. fmt.Printf("%s\n", plaintext2)
  35. // Output: some plaintext

type 

  1. type StreamReader struct {
  2.     S 
  3.     R io.
  4. }

StreamReader wraps a Stream into an io.Reader. It calls XORKeyStream to process
each slice of data which passes through.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // NewCipher calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. key, _ := hex.DecodeString("6368616e676520746869732070617373")
  7. inFile, err := os.Open("encrypted-file")
  8. if err != nil {
  9.     panic(err)
  10. }
  11. defer inFile.Close()
  13. block, err := aes.NewCipher(key)
  14. if err != nil {
  15.     panic(err)
  16. }
  18. // If the key is unique for each ciphertext, then it's ok to use a zero
  19. // IV.
  20. var iv [aes.BlockSize]byte
  21. stream := cipher.NewOFB(block, iv[:])
  23. outFile, err := os.OpenFile("decrypted-file", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
  24. if err != nil {
  25.     panic(err)
  26. }
  27. defer outFile.Close()
  29. reader := &cipher.StreamReader{S: stream, R: inFile}
  30. // Copy the input file to the output file, decrypting as we go.
  31. if _, err := io.Copy(outFile, reader); err != nil {
  32.     panic(err)
  33. }
  35. // Note that this example is simplistic in that it omits any
  36. // authentication of the encrypted data. If you were actually to use
  37. // StreamReader in this manner, an attacker could flip arbitrary bits in
  38. // the output.

func (StreamReader) 

  1. func (r ) Read(dst []byte) (n , err error)

type 

  1. type StreamWriter struct {
  2.     S   
  3.     W   io.
  4.     Err error // unused
  5. }

StreamWriter wraps a Stream into an io.Writer. It calls XORKeyStream to process
each slice of data which passes through. If any Write call returns short then
the StreamWriter is out of sync and must be discarded. A StreamWriter has no
internal buffering; Close does not need to be called to flush write data.


Example:

  1. // Load your secret key from a safe place and reuse it across multiple
  2. // NewCipher calls. (Obviously don't use this example key for anything
  3. // real.) If you want to convert a passphrase to a key, use a suitable
  4. // package like bcrypt or scrypt.
  5. key, _ := hex.DecodeString("6368616e676520746869732070617373")
  7. inFile, err := os.Open("plaintext-file")
  8. if err != nil {
  9.     panic(err)
  10. }
  11. defer inFile.Close()
  13. block, err := aes.NewCipher(key)
  14. if err != nil {
  15.     panic(err)
  16. }
  18. // If the key is unique for each ciphertext, then it's ok to use a zero
  19. // IV.
  20. var iv [aes.BlockSize]byte
  21. stream := cipher.NewOFB(block, iv[:])
  23. outFile, err := os.OpenFile("encrypted-file", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
  24. if err != nil {
  25.     panic(err)
  26. }
  27. defer outFile.Close()
  29. writer := &cipher.StreamWriter{S: stream, W: outFile}
  30. // Copy the input file to the output file, encrypting as we go.
  31. if _, err := io.Copy(writer, inFile); err != nil {
  32.     panic(err)
  33. }
  35. // Note that this example is simplistic in that it omits any
  36. // authentication of the encrypted data. If you were actually to use
  37. // StreamReader in this manner, an attacker could flip arbitrary bits in

func (StreamWriter) Close

  1. func (w StreamWriter) Close()

Close closes the underlying Writer and returns its Close return value, if the
Writer is also an io.Closer. Otherwise it returns nil.