Skip to content
Snippets Groups Projects
example_test.go 7.92 KiB
Newer Older
  • Learn to ignore specific revisions
  • Adam Langley's avatar
    Adam Langley committed
    // Copyright 2012 The Go Authors. All rights reserved.
    // Use of this source code is governed by a BSD-style
    // license that can be found in the LICENSE file.
    
    package cipher_test
    
    import (
    	"crypto/aes"
    	"crypto/cipher"
    	"crypto/rand"
    	"encoding/hex"
    	"fmt"
    	"io"
    	"os"
    )
    
    func ExampleNewCBCDecrypter() {
    	key := []byte("example key 1234")
    	ciphertext, _ := hex.DecodeString("f363f3ccdcb12bb883abf484ba77d9cd7d32b5baecb3d4b1b3e0e4beffdb3ded")
    
    	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)
    	// Output: exampleplaintext
    }
    
    func ExampleNewCBCEncrypter() {
    	key := []byte("example key 1234")
    	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)
    }
    
    func ExampleNewCFBDecrypter() {
    	key := []byte("example key 1234")
    	ciphertext, _ := hex.DecodeString("22277966616d9bc47177bd02603d08c9a67d5380d0fe8cf3b44438dff7b9")
    
    	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)
    	// Output: some plaintext
    }
    
    func ExampleNewCFBEncrypter() {
    	key := []byte("example key 1234")
    	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.
    }
    
    func ExampleNewCTR() {
    	key := []byte("example key 1234")
    	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)
    	// Output: some plaintext
    }
    
    func ExampleNewOFB() {
    	key := []byte("example key 1234")
    	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)
    	// Output: some plaintext
    }
    
    func ExampleStreamReader() {
    	key := []byte("example key 1234")
    
    	inFile, err := os.Open("encrypted-file")
    	if err != nil {
    		panic(err)
    	}
    	defer inFile.Close()
    
    	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[:])
    
    	outFile, err := os.OpenFile("decrypted-file", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
    	if err != nil {
    		panic(err)
    	}
    	defer outFile.Close()
    
    
    Russ Cox's avatar
    Russ Cox committed
    	reader := &cipher.StreamReader{S: stream, R: inFile}
    
    Adam Langley's avatar
    Adam Langley committed
    	// Copy the input file to the output file, decrypting as we go.
    	if _, err := io.Copy(outFile, reader); err != nil {
    		panic(err)
    	}
    
    	// Note that this example is simplistic in that it omits any
    	// authentication of the encrypted data. It you were actually to use
    
    Shenghou Ma's avatar
    Shenghou Ma committed
    	// StreamReader in this manner, an attacker could flip arbitrary bits in
    
    Adam Langley's avatar
    Adam Langley committed
    	// the output.
    }
    
    func ExampleStreamWriter() {
    	key := []byte("example key 1234")
    
    	inFile, err := os.Open("plaintext-file")
    	if err != nil {
    		panic(err)
    	}
    	defer inFile.Close()
    
    	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[:])
    
    	outFile, err := os.OpenFile("encrypted-file", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
    	if err != nil {
    		panic(err)
    	}
    	defer outFile.Close()
    
    
    Russ Cox's avatar
    Russ Cox committed
    	writer := &cipher.StreamWriter{S: stream, W: outFile}
    
    Adam Langley's avatar
    Adam Langley committed
    	// Copy the input file to the output file, encrypting as we go.
    	if _, err := io.Copy(writer, inFile); err != nil {
    		panic(err)
    	}
    
    	// Note that this example is simplistic in that it omits any
    	// authentication of the encrypted data. It you were actually to use
    
    Shenghou Ma's avatar
    Shenghou Ma committed
    	// StreamReader in this manner, an attacker could flip arbitrary bits in
    
    Adam Langley's avatar
    Adam Langley committed
    	// the decrypted result.
    }