package cipher

Import Path
	crypto/cipher (on go.dev)

Dependency Relation
	imports 6 packages, and imported by 8 packages

Involved Source Files

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

	    ctr.go
	    gcm.go
	    io.go
	    ofb.go
Code Examples

	NewCBCDecrypter
		package main
		
		import (
			"crypto/aes"
			"crypto/cipher"
			"encoding/hex"
			"fmt"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
			ciphertext, _ := hex.DecodeString("73c86d43a9d700a253a96c85b0f6b03ac9792e0e757f869cca306bd3cba1c62b")
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// The IV needs to be unique, but not secure. Therefore it's common to
			// include it at the beginning of the ciphertext.
			if len(ciphertext) < aes.BlockSize {
				panic("ciphertext too short")
			}
			iv := ciphertext[:aes.BlockSize]
			ciphertext = ciphertext[aes.BlockSize:]
		
			// CBC mode always works in whole blocks.
			if len(ciphertext)%aes.BlockSize != 0 {
				panic("ciphertext is not a multiple of the block size")
			}
		
			mode := cipher.NewCBCDecrypter(block, iv)
		
			// CryptBlocks can work in-place if the two arguments are the same.
			mode.CryptBlocks(ciphertext, ciphertext)
		
			// If the original plaintext lengths are not a multiple of the block
			// size, padding would have to be added when encrypting, which would be
			// removed at this point. For an example, see
			// https://tools.ietf.org/html/rfc5246#section-6.2.3.2. However, it's
			// critical to note that ciphertexts must be authenticated (i.e. by
			// using crypto/hmac) before being decrypted in order to avoid creating
			// a padding oracle.
		
			fmt.Printf("%s\n", ciphertext)
		}

	NewCBCEncrypter
		package main
		
		import (
			"crypto/aes"
			"crypto/cipher"
			"crypto/rand"
			"encoding/hex"
			"fmt"
			"io"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
			plaintext := []byte("exampleplaintext")
		
			// CBC mode works on blocks so plaintexts may need to be padded to the
			// next whole block. For an example of such padding, see
			// https://tools.ietf.org/html/rfc5246#section-6.2.3.2. Here we'll
			// assume that the plaintext is already of the correct length.
			if len(plaintext)%aes.BlockSize != 0 {
				panic("plaintext is not a multiple of the block size")
			}
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// The IV needs to be unique, but not secure. Therefore it's common to
			// include it at the beginning of the ciphertext.
			ciphertext := make([]byte, aes.BlockSize+len(plaintext))
			iv := ciphertext[:aes.BlockSize]
			if _, err := io.ReadFull(rand.Reader, iv); err != nil {
				panic(err)
			}
		
			mode := cipher.NewCBCEncrypter(block, iv)
			mode.CryptBlocks(ciphertext[aes.BlockSize:], plaintext)
		
			// It's important to remember that ciphertexts must be authenticated
			// (i.e. by using crypto/hmac) as well as being encrypted in order to
			// be secure.
		
			fmt.Printf("%x\n", ciphertext)
		}

	NewCFBDecrypter
		package main
		
		import (
			"crypto/aes"
			"crypto/cipher"
			"encoding/hex"
			"fmt"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
			ciphertext, _ := hex.DecodeString("7dd015f06bec7f1b8f6559dad89f4131da62261786845100056b353194ad")
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// The IV needs to be unique, but not secure. Therefore it's common to
			// include it at the beginning of the ciphertext.
			if len(ciphertext) < aes.BlockSize {
				panic("ciphertext too short")
			}
			iv := ciphertext[:aes.BlockSize]
			ciphertext = ciphertext[aes.BlockSize:]
		
			stream := cipher.NewCFBDecrypter(block, iv)
		
			// XORKeyStream can work in-place if the two arguments are the same.
			stream.XORKeyStream(ciphertext, ciphertext)
			fmt.Printf("%s", ciphertext)
		}

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

	NewCTR
		package main
		
		import (
			"crypto/aes"
			"crypto/cipher"
			"crypto/rand"
			"encoding/hex"
			"fmt"
			"io"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
			plaintext := []byte("some plaintext")
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// The IV needs to be unique, but not secure. Therefore it's common to
			// include it at the beginning of the ciphertext.
			ciphertext := make([]byte, aes.BlockSize+len(plaintext))
			iv := ciphertext[:aes.BlockSize]
			if _, err := io.ReadFull(rand.Reader, iv); err != nil {
				panic(err)
			}
		
			stream := cipher.NewCTR(block, iv)
			stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
		
			// It's important to remember that ciphertexts must be authenticated
			// (i.e. by using crypto/hmac) as well as being encrypted in order to
			// be secure.
		
			// CTR mode is the same for both encryption and decryption, so we can
			// also decrypt that ciphertext with NewCTR.
		
			plaintext2 := make([]byte, len(plaintext))
			stream = cipher.NewCTR(block, iv)
			stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:])
		
			fmt.Printf("%s\n", plaintext2)
		}

	NewGCM_decrypt
		package main
		
		import (
			"crypto/aes"
			"crypto/cipher"
			"encoding/hex"
			"fmt"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// Seal/Open calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
			key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
			ciphertext, _ := hex.DecodeString("c3aaa29f002ca75870806e44086700f62ce4d43e902b3888e23ceff797a7a471")
			nonce, _ := hex.DecodeString("64a9433eae7ccceee2fc0eda")
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err.Error())
			}
		
			aesgcm, err := cipher.NewGCM(block)
			if err != nil {
				panic(err.Error())
			}
		
			plaintext, err := aesgcm.Open(nil, nonce, ciphertext, nil)
			if err != nil {
				panic(err.Error())
			}
		
			fmt.Printf("%s\n", plaintext)
		}

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

	NewOFB
		package main
		
		import (
			"crypto/aes"
			"crypto/cipher"
			"crypto/rand"
			"encoding/hex"
			"fmt"
			"io"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
			plaintext := []byte("some plaintext")
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// The IV needs to be unique, but not secure. Therefore it's common to
			// include it at the beginning of the ciphertext.
			ciphertext := make([]byte, aes.BlockSize+len(plaintext))
			iv := ciphertext[:aes.BlockSize]
			if _, err := io.ReadFull(rand.Reader, iv); err != nil {
				panic(err)
			}
		
			stream := cipher.NewOFB(block, iv)
			stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
		
			// It's important to remember that ciphertexts must be authenticated
			// (i.e. by using crypto/hmac) as well as being encrypted in order to
			// be secure.
		
			// OFB mode is the same for both encryption and decryption, so we can
			// also decrypt that ciphertext with NewOFB.
		
			plaintext2 := make([]byte, len(plaintext))
			stream = cipher.NewOFB(block, iv)
			stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:])
		
			fmt.Printf("%s\n", plaintext2)
		}

	StreamReader
		package main
		
		import (
			"bytes"
			"crypto/aes"
			"crypto/cipher"
			"encoding/hex"
			"io"
			"os"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
		
			encrypted, _ := hex.DecodeString("cf0495cc6f75dafc23948538e79904a9")
			bReader := bytes.NewReader(encrypted)
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// If the key is unique for each ciphertext, then it's ok to use a zero
			// IV.
			var iv [aes.BlockSize]byte
			stream := cipher.NewOFB(block, iv[:])
		
			reader := &cipher.StreamReader{S: stream, R: bReader}
			// Copy the input to the output stream, decrypting as we go.
			if _, err := io.Copy(os.Stdout, reader); err != nil {
				panic(err)
			}
		
			// Note that this example is simplistic in that it omits any
			// authentication of the encrypted data. If you were actually to use
			// StreamReader in this manner, an attacker could flip arbitrary bits in
			// the output.
		
		}

	StreamWriter
		package main
		
		import (
			"bytes"
			"crypto/aes"
			"crypto/cipher"
			"encoding/hex"
			"fmt"
			"io"
		)
		
		func main() {
			// Load your secret key from a safe place and reuse it across multiple
			// NewCipher calls. (Obviously don't use this example key for anything
			// real.) If you want to convert a passphrase to a key, use a suitable
			// package like bcrypt or scrypt.
			key, _ := hex.DecodeString("6368616e676520746869732070617373")
		
			bReader := bytes.NewReader([]byte("some secret text"))
		
			block, err := aes.NewCipher(key)
			if err != nil {
				panic(err)
			}
		
			// If the key is unique for each ciphertext, then it's ok to use a zero
			// IV.
			var iv [aes.BlockSize]byte
			stream := cipher.NewOFB(block, iv[:])
		
			var out bytes.Buffer
		
			writer := &cipher.StreamWriter{S: stream, W: &out}
			// Copy the input to the output buffer, encrypting as we go.
			if _, err := io.Copy(writer, bReader); err != nil {
				panic(err)
			}
		
			// Note that this example is simplistic in that it omits any
			// authentication of the encrypted data. If you were actually to use
			// StreamReader in this manner, an attacker could flip arbitrary bits in
			// the decrypted result.
		
			fmt.Printf("%x\n", out.Bytes())
		}


Package-Level Type Names (total 6)

	/* sort by: alphabet | popularity */
	 type AEAD (interface)
		AEAD is a cipher mode providing authenticated encryption with associated
		data. For a description of the methodology, see
		https://en.wikipedia.org/wiki/Authenticated_encryption.

		Methods (total 4)
			( AEAD) NonceSize() int
				NonceSize returns the size of the nonce that must be passed to Seal
				and Open.

			( AEAD) Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
				Open decrypts and authenticates ciphertext, authenticates the
				additional data and, if successful, appends the resulting plaintext
				to dst, returning the updated slice. The nonce must be NonceSize()
				bytes long and both it and the additional data must match the
				value passed to Seal.
				
				To reuse ciphertext's storage for the decrypted output, use ciphertext[:0]
				as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.
				
				Even if the function fails, the contents of dst, up to its capacity,
				may be overwritten.

			( AEAD) Overhead() int
				Overhead returns the maximum difference between the lengths of a
				plaintext and its ciphertext.

			( AEAD) Seal(dst, nonce, plaintext, additionalData []byte) []byte
				Seal encrypts and authenticates plaintext, authenticates the
				additional data and appends the result to dst, returning the updated
				slice. The nonce must be NonceSize() bytes long and unique for all
				time, for a given key.
				
				To reuse plaintext's storage for the encrypted output, use plaintext[:0]
				as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.

		As Outputs Of (at least 6)
			func NewGCM(cipher Block) (AEAD, error)
			func NewGCMWithNonceSize(cipher Block, size int) (AEAD, error)
			func NewGCMWithTagSize(cipher Block, tagSize int) (AEAD, error)
			func crypto/internal/boring.NewGCMTLS(Block) (AEAD, error)
			func vendor/golang.org/x/crypto/chacha20poly1305.New(key []byte) (AEAD, error)
			func vendor/golang.org/x/crypto/chacha20poly1305.NewX(key []byte) (AEAD, error)

	 type Block (interface)
		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.

		Methods (total 3)
			( Block) BlockSize() int
				BlockSize returns the cipher's block size.

			( Block) Decrypt(dst, src []byte)
				Decrypt decrypts the first block in src into dst.
				Dst and src must overlap entirely or not at all.

			( Block) Encrypt(dst, src []byte)
				Encrypt encrypts the first block in src into dst.
				Dst and src must overlap entirely or not at all.

		As Outputs Of (at least 4)
			func crypto/aes.NewCipher(key []byte) (Block, error)
			func crypto/des.NewCipher(key []byte) (Block, error)
			func crypto/des.NewTripleDESCipher(key []byte) (Block, error)
			func crypto/internal/boring.NewAESCipher(key []byte) (Block, error)
		As Inputs Of (at least 10)
			func NewCBCDecrypter(b Block, iv []byte) BlockMode
			func NewCBCEncrypter(b Block, iv []byte) BlockMode
			func NewCFBDecrypter(block Block, iv []byte) Stream
			func NewCFBEncrypter(block Block, iv []byte) Stream
			func NewCTR(block Block, iv []byte) Stream
			func NewGCM(cipher Block) (AEAD, error)
			func NewGCMWithNonceSize(cipher Block, size int) (AEAD, error)
			func NewGCMWithTagSize(cipher Block, tagSize int) (AEAD, error)
			func NewOFB(b Block, iv []byte) Stream
			func crypto/internal/boring.NewGCMTLS(Block) (AEAD, error)

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

		Methods (total 2)
			( BlockMode) BlockSize() int
				BlockSize returns the mode's block size.

			( BlockMode) CryptBlocks(dst, src []byte)
				CryptBlocks encrypts or decrypts a number of blocks. The length of
				src must be a multiple of the block size. Dst and src must overlap
				entirely or not at all.
				
				If len(dst) < len(src), CryptBlocks should panic. It is acceptable
				to pass a dst bigger than src, and in that case, CryptBlocks will
				only update dst[:len(src)] and will not touch the rest of dst.
				
				Multiple calls to CryptBlocks behave as if the concatenation of
				the src buffers was passed in a single run. That is, BlockMode
				maintains state and does not reset at each CryptBlocks call.

		As Outputs Of (at least 2)
			func NewCBCDecrypter(b Block, iv []byte) BlockMode
			func NewCBCEncrypter(b Block, iv []byte) BlockMode

	 type Stream (interface)
		A Stream represents a stream cipher.

		Methods (only one)
			( Stream) XORKeyStream(dst, src []byte)
				XORKeyStream XORs each byte in the given slice with a byte from the
				cipher's key stream. Dst and src must overlap entirely or not at all.
				
				If len(dst) < len(src), XORKeyStream should panic. It is acceptable
				to pass a dst bigger than src, and in that case, XORKeyStream will
				only update dst[:len(src)] and will not touch the rest of dst.
				
				Multiple calls to XORKeyStream behave as if the concatenation of
				the src buffers was passed in a single run. That is, Stream
				maintains state and does not reset at each XORKeyStream call.

		Implemented By (at least 2)
			*crypto/rc4.Cipher
			*vendor/golang.org/x/crypto/chacha20.Cipher
		As Outputs Of (at least 4)
			func NewCFBDecrypter(block Block, iv []byte) Stream
			func NewCFBEncrypter(block Block, iv []byte) Stream
			func NewCTR(block Block, iv []byte) Stream
			func NewOFB(b Block, iv []byte) Stream

	 type StreamReader (struct)
		StreamReader wraps a [Stream] into an [io.Reader]. It calls XORKeyStream
		to process each slice of data which passes through.

		Fields (total 2)
			R io.Reader
			S Stream
		Methods (only one)
			( StreamReader) Read(dst []byte) (n int, err error)
		Implements (at least one exported)
			 StreamReader : io.Reader

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

		Fields (total 3)
			Err error
				// unused

			S Stream
			W io.Writer
		Methods (total 2)
			( StreamWriter) Close() error
				Close closes the underlying Writer and returns its Close return value, if the Writer
				is also an io.Closer. Otherwise it returns nil.

			( StreamWriter) Write(src []byte) (n int, err error)
		Implements (at least 4)
			 StreamWriter : internal/bisect.Writer
			 StreamWriter : io.Closer
			 StreamWriter : io.WriteCloser
			 StreamWriter : io.Writer


Package-Level Functions (total 9)

	 func NewCBCDecrypter(b Block, iv []byte) 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.

	 func NewCBCEncrypter(b Block, iv []byte) 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.

	 func NewCFBDecrypter(block Block, iv []byte) Stream
		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.

	 func NewCFBEncrypter(block Block, iv []byte) Stream
		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.

	 func NewCTR(block Block, iv []byte) Stream
		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.

	 func NewGCM(cipher Block) (AEAD, 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.

	 func NewGCMWithNonceSize(cipher Block, size int) (AEAD, error)
		NewGCMWithNonceSize returns the given 128-bit, block cipher wrapped in Galois
		Counter Mode, which accepts nonces of the given length. The length must not
		be zero.
		
		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.

	 func NewGCMWithTagSize(cipher Block, tagSize int) (AEAD, error)
		NewGCMWithTagSize returns the given 128-bit, block cipher wrapped in Galois
		Counter Mode, which generates tags with the given length.
		
		Tag sizes between 12 and 16 bytes are allowed.
		
		Only use this function if you require compatibility with an existing
		cryptosystem that uses non-standard tag lengths. All other users should use
		[NewGCM], which is more resistant to misuse.

	 func NewOFB(b Block, iv []byte) Stream
		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.

The pages are generated with Golds v0.6.9-preview. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.