example_test.go

Documentation: crypto/cipher

		 1  // Copyright 2012 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_test
		 6  
		 7  import (
		 8  	"bytes"
		 9  	"crypto/aes"
		10  	"crypto/cipher"
		11  	"crypto/rand"
		12  	"encoding/hex"
		13  	"fmt"
		14  	"io"
		15  	"os"
		16  )
		17  
		18  func ExampleNewGCM_encrypt() {
		19  	// Load your secret key from a safe place and reuse it across multiple
		20  	// Seal/Open calls. (Obviously don't use this example key for anything
		21  	// real.) If you want to convert a passphrase to a key, use a suitable
		22  	// package like bcrypt or scrypt.
		23  	// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
		24  	key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
		25  	plaintext := []byte("exampleplaintext")
		26  
		27  	block, err := aes.NewCipher(key)
		28  	if err != nil {
		29  		panic(err.Error())
		30  	}
		31  
		32  	// Never use more than 2^32 random nonces with a given key because of the risk of a repeat.
		33  	nonce := make([]byte, 12)
		34  	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
		35  		panic(err.Error())
		36  	}
		37  
		38  	aesgcm, err := cipher.NewGCM(block)
		39  	if err != nil {
		40  		panic(err.Error())
		41  	}
		42  
		43  	ciphertext := aesgcm.Seal(nil, nonce, plaintext, nil)
		44  	fmt.Printf("%x\n", ciphertext)
		45  }
		46  
		47  func ExampleNewGCM_decrypt() {
		48  	// Load your secret key from a safe place and reuse it across multiple
		49  	// Seal/Open calls. (Obviously don't use this example key for anything
		50  	// real.) If you want to convert a passphrase to a key, use a suitable
		51  	// package like bcrypt or scrypt.
		52  	// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
		53  	key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
		54  	ciphertext, _ := hex.DecodeString("c3aaa29f002ca75870806e44086700f62ce4d43e902b3888e23ceff797a7a471")
		55  	nonce, _ := hex.DecodeString("64a9433eae7ccceee2fc0eda")
		56  
		57  	block, err := aes.NewCipher(key)
		58  	if err != nil {
		59  		panic(err.Error())
		60  	}
		61  
		62  	aesgcm, err := cipher.NewGCM(block)
		63  	if err != nil {
		64  		panic(err.Error())
		65  	}
		66  
		67  	plaintext, err := aesgcm.Open(nil, nonce, ciphertext, nil)
		68  	if err != nil {
		69  		panic(err.Error())
		70  	}
		71  
		72  	fmt.Printf("%s\n", plaintext)
		73  	// Output: exampleplaintext
		74  }
		75  
		76  func ExampleNewCBCDecrypter() {
		77  	// Load your secret key from a safe place and reuse it across multiple
		78  	// NewCipher calls. (Obviously don't use this example key for anything
		79  	// real.) If you want to convert a passphrase to a key, use a suitable
		80  	// package like bcrypt or scrypt.
		81  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
		82  	ciphertext, _ := hex.DecodeString("73c86d43a9d700a253a96c85b0f6b03ac9792e0e757f869cca306bd3cba1c62b")
		83  
		84  	block, err := aes.NewCipher(key)
		85  	if err != nil {
		86  		panic(err)
		87  	}
		88  
		89  	// The IV needs to be unique, but not secure. Therefore it's common to
		90  	// include it at the beginning of the ciphertext.
		91  	if len(ciphertext) < aes.BlockSize {
		92  		panic("ciphertext too short")
		93  	}
		94  	iv := ciphertext[:aes.BlockSize]
		95  	ciphertext = ciphertext[aes.BlockSize:]
		96  
		97  	// CBC mode always works in whole blocks.
		98  	if len(ciphertext)%aes.BlockSize != 0 {
		99  		panic("ciphertext is not a multiple of the block size")
	 100  	}
	 101  
	 102  	mode := cipher.NewCBCDecrypter(block, iv)
	 103  
	 104  	// CryptBlocks can work in-place if the two arguments are the same.
	 105  	mode.CryptBlocks(ciphertext, ciphertext)
	 106  
	 107  	// If the original plaintext lengths are not a multiple of the block
	 108  	// size, padding would have to be added when encrypting, which would be
	 109  	// removed at this point. For an example, see
	 110  	// https://tools.ietf.org/html/rfc5246#section-6.2.3.2. However, it's
	 111  	// critical to note that ciphertexts must be authenticated (i.e. by
	 112  	// using crypto/hmac) before being decrypted in order to avoid creating
	 113  	// a padding oracle.
	 114  
	 115  	fmt.Printf("%s\n", ciphertext)
	 116  	// Output: exampleplaintext
	 117  }
	 118  
	 119  func ExampleNewCBCEncrypter() {
	 120  	// Load your secret key from a safe place and reuse it across multiple
	 121  	// NewCipher calls. (Obviously don't use this example key for anything
	 122  	// real.) If you want to convert a passphrase to a key, use a suitable
	 123  	// package like bcrypt or scrypt.
	 124  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 125  	plaintext := []byte("exampleplaintext")
	 126  
	 127  	// CBC mode works on blocks so plaintexts may need to be padded to the
	 128  	// next whole block. For an example of such padding, see
	 129  	// https://tools.ietf.org/html/rfc5246#section-6.2.3.2. Here we'll
	 130  	// assume that the plaintext is already of the correct length.
	 131  	if len(plaintext)%aes.BlockSize != 0 {
	 132  		panic("plaintext is not a multiple of the block size")
	 133  	}
	 134  
	 135  	block, err := aes.NewCipher(key)
	 136  	if err != nil {
	 137  		panic(err)
	 138  	}
	 139  
	 140  	// The IV needs to be unique, but not secure. Therefore it's common to
	 141  	// include it at the beginning of the ciphertext.
	 142  	ciphertext := make([]byte, aes.BlockSize+len(plaintext))
	 143  	iv := ciphertext[:aes.BlockSize]
	 144  	if _, err := io.ReadFull(rand.Reader, iv); err != nil {
	 145  		panic(err)
	 146  	}
	 147  
	 148  	mode := cipher.NewCBCEncrypter(block, iv)
	 149  	mode.CryptBlocks(ciphertext[aes.BlockSize:], plaintext)
	 150  
	 151  	// It's important to remember that ciphertexts must be authenticated
	 152  	// (i.e. by using crypto/hmac) as well as being encrypted in order to
	 153  	// be secure.
	 154  
	 155  	fmt.Printf("%x\n", ciphertext)
	 156  }
	 157  
	 158  func ExampleNewCFBDecrypter() {
	 159  	// Load your secret key from a safe place and reuse it across multiple
	 160  	// NewCipher calls. (Obviously don't use this example key for anything
	 161  	// real.) If you want to convert a passphrase to a key, use a suitable
	 162  	// package like bcrypt or scrypt.
	 163  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 164  	ciphertext, _ := hex.DecodeString("7dd015f06bec7f1b8f6559dad89f4131da62261786845100056b353194ad")
	 165  
	 166  	block, err := aes.NewCipher(key)
	 167  	if err != nil {
	 168  		panic(err)
	 169  	}
	 170  
	 171  	// The IV needs to be unique, but not secure. Therefore it's common to
	 172  	// include it at the beginning of the ciphertext.
	 173  	if len(ciphertext) < aes.BlockSize {
	 174  		panic("ciphertext too short")
	 175  	}
	 176  	iv := ciphertext[:aes.BlockSize]
	 177  	ciphertext = ciphertext[aes.BlockSize:]
	 178  
	 179  	stream := cipher.NewCFBDecrypter(block, iv)
	 180  
	 181  	// XORKeyStream can work in-place if the two arguments are the same.
	 182  	stream.XORKeyStream(ciphertext, ciphertext)
	 183  	fmt.Printf("%s", ciphertext)
	 184  	// Output: some plaintext
	 185  }
	 186  
	 187  func ExampleNewCFBEncrypter() {
	 188  	// Load your secret key from a safe place and reuse it across multiple
	 189  	// NewCipher calls. (Obviously don't use this example key for anything
	 190  	// real.) If you want to convert a passphrase to a key, use a suitable
	 191  	// package like bcrypt or scrypt.
	 192  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 193  	plaintext := []byte("some plaintext")
	 194  
	 195  	block, err := aes.NewCipher(key)
	 196  	if err != nil {
	 197  		panic(err)
	 198  	}
	 199  
	 200  	// The IV needs to be unique, but not secure. Therefore it's common to
	 201  	// include it at the beginning of the ciphertext.
	 202  	ciphertext := make([]byte, aes.BlockSize+len(plaintext))
	 203  	iv := ciphertext[:aes.BlockSize]
	 204  	if _, err := io.ReadFull(rand.Reader, iv); err != nil {
	 205  		panic(err)
	 206  	}
	 207  
	 208  	stream := cipher.NewCFBEncrypter(block, iv)
	 209  	stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
	 210  
	 211  	// It's important to remember that ciphertexts must be authenticated
	 212  	// (i.e. by using crypto/hmac) as well as being encrypted in order to
	 213  	// be secure.
	 214  	fmt.Printf("%x\n", ciphertext)
	 215  }
	 216  
	 217  func ExampleNewCTR() {
	 218  	// Load your secret key from a safe place and reuse it across multiple
	 219  	// NewCipher calls. (Obviously don't use this example key for anything
	 220  	// real.) If you want to convert a passphrase to a key, use a suitable
	 221  	// package like bcrypt or scrypt.
	 222  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 223  	plaintext := []byte("some plaintext")
	 224  
	 225  	block, err := aes.NewCipher(key)
	 226  	if err != nil {
	 227  		panic(err)
	 228  	}
	 229  
	 230  	// The IV needs to be unique, but not secure. Therefore it's common to
	 231  	// include it at the beginning of the ciphertext.
	 232  	ciphertext := make([]byte, aes.BlockSize+len(plaintext))
	 233  	iv := ciphertext[:aes.BlockSize]
	 234  	if _, err := io.ReadFull(rand.Reader, iv); err != nil {
	 235  		panic(err)
	 236  	}
	 237  
	 238  	stream := cipher.NewCTR(block, iv)
	 239  	stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
	 240  
	 241  	// It's important to remember that ciphertexts must be authenticated
	 242  	// (i.e. by using crypto/hmac) as well as being encrypted in order to
	 243  	// be secure.
	 244  
	 245  	// CTR mode is the same for both encryption and decryption, so we can
	 246  	// also decrypt that ciphertext with NewCTR.
	 247  
	 248  	plaintext2 := make([]byte, len(plaintext))
	 249  	stream = cipher.NewCTR(block, iv)
	 250  	stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:])
	 251  
	 252  	fmt.Printf("%s\n", plaintext2)
	 253  	// Output: some plaintext
	 254  }
	 255  
	 256  func ExampleNewOFB() {
	 257  	// Load your secret key from a safe place and reuse it across multiple
	 258  	// NewCipher calls. (Obviously don't use this example key for anything
	 259  	// real.) If you want to convert a passphrase to a key, use a suitable
	 260  	// package like bcrypt or scrypt.
	 261  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 262  	plaintext := []byte("some plaintext")
	 263  
	 264  	block, err := aes.NewCipher(key)
	 265  	if err != nil {
	 266  		panic(err)
	 267  	}
	 268  
	 269  	// The IV needs to be unique, but not secure. Therefore it's common to
	 270  	// include it at the beginning of the ciphertext.
	 271  	ciphertext := make([]byte, aes.BlockSize+len(plaintext))
	 272  	iv := ciphertext[:aes.BlockSize]
	 273  	if _, err := io.ReadFull(rand.Reader, iv); err != nil {
	 274  		panic(err)
	 275  	}
	 276  
	 277  	stream := cipher.NewOFB(block, iv)
	 278  	stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext)
	 279  
	 280  	// It's important to remember that ciphertexts must be authenticated
	 281  	// (i.e. by using crypto/hmac) as well as being encrypted in order to
	 282  	// be secure.
	 283  
	 284  	// OFB mode is the same for both encryption and decryption, so we can
	 285  	// also decrypt that ciphertext with NewOFB.
	 286  
	 287  	plaintext2 := make([]byte, len(plaintext))
	 288  	stream = cipher.NewOFB(block, iv)
	 289  	stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:])
	 290  
	 291  	fmt.Printf("%s\n", plaintext2)
	 292  	// Output: some plaintext
	 293  }
	 294  
	 295  func ExampleStreamReader() {
	 296  	// Load your secret key from a safe place and reuse it across multiple
	 297  	// NewCipher calls. (Obviously don't use this example key for anything
	 298  	// real.) If you want to convert a passphrase to a key, use a suitable
	 299  	// package like bcrypt or scrypt.
	 300  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 301  
	 302  	encrypted, _ := hex.DecodeString("cf0495cc6f75dafc23948538e79904a9")
	 303  	bReader := bytes.NewReader(encrypted)
	 304  
	 305  	block, err := aes.NewCipher(key)
	 306  	if err != nil {
	 307  		panic(err)
	 308  	}
	 309  
	 310  	// If the key is unique for each ciphertext, then it's ok to use a zero
	 311  	// IV.
	 312  	var iv [aes.BlockSize]byte
	 313  	stream := cipher.NewOFB(block, iv[:])
	 314  
	 315  	reader := &cipher.StreamReader{S: stream, R: bReader}
	 316  	// Copy the input to the output stream, decrypting as we go.
	 317  	if _, err := io.Copy(os.Stdout, reader); err != nil {
	 318  		panic(err)
	 319  	}
	 320  
	 321  	// Note that this example is simplistic in that it omits any
	 322  	// authentication of the encrypted data. If you were actually to use
	 323  	// StreamReader in this manner, an attacker could flip arbitrary bits in
	 324  	// the output.
	 325  
	 326  	// Output: some secret text
	 327  }
	 328  
	 329  func ExampleStreamWriter() {
	 330  	// Load your secret key from a safe place and reuse it across multiple
	 331  	// NewCipher calls. (Obviously don't use this example key for anything
	 332  	// real.) If you want to convert a passphrase to a key, use a suitable
	 333  	// package like bcrypt or scrypt.
	 334  	key, _ := hex.DecodeString("6368616e676520746869732070617373")
	 335  
	 336  	bReader := bytes.NewReader([]byte("some secret text"))
	 337  
	 338  	block, err := aes.NewCipher(key)
	 339  	if err != nil {
	 340  		panic(err)
	 341  	}
	 342  
	 343  	// If the key is unique for each ciphertext, then it's ok to use a zero
	 344  	// IV.
	 345  	var iv [aes.BlockSize]byte
	 346  	stream := cipher.NewOFB(block, iv[:])
	 347  
	 348  	var out bytes.Buffer
	 349  
	 350  	writer := &cipher.StreamWriter{S: stream, W: &out}
	 351  	// Copy the input to the output buffer, encrypting as we go.
	 352  	if _, err := io.Copy(writer, bReader); err != nil {
	 353  		panic(err)
	 354  	}
	 355  
	 356  	// Note that this example is simplistic in that it omits any
	 357  	// authentication of the encrypted data. If you were actually to use
	 358  	// StreamReader in this manner, an attacker could flip arbitrary bits in
	 359  	// the decrypted result.
	 360  
	 361  	fmt.Printf("%x\n", out.Bytes())
	 362  	// Output: cf0495cc6f75dafc23948538e79904a9
	 363  }
	 364
View as plain text