From ce0dbc438863b478d7e0b8e5e8c6a28c2189d6c0 Mon Sep 17 00:00:00 2001 From: Adam Langley Date: Wed, 31 Oct 2012 16:37:26 -0400 Subject: crypto/cipher: add examples Fixes issue 1390. R=golang-dev, minux.ma, adg, agl CC=golang-dev http://codereview.appspot.com/6631044 --- src/pkg/crypto/cipher/example_test.go | 283 ++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 src/pkg/crypto/cipher/example_test.go (limited to 'src/pkg/crypto/cipher/example_test.go') diff --git a/src/pkg/crypto/cipher/example_test.go b/src/pkg/crypto/cipher/example_test.go new file mode 100644 index 000000000..c888eb2c6 --- /dev/null +++ b/src/pkg/crypto/cipher/example_test.go @@ -0,0 +1,283 @@ +// 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() + + reader := &cipher.StreamReader{stream, inFile} + // 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 + // StreamReader in this manner, an attacker could flip arbitary bits in + // 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() + + writer := &cipher.StreamWriter{stream, outFile, nil} + // 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 + // StreamReader in this manner, an attacker could flip arbitary bits in + // the decrypted result. +} -- cgit v1.2.1