crypto/cipher: Add AES-GCM encryption and decryption example

Add example of how to use the aes package to
implement AES encryption and decryption
within an application.

Per feedback, use more secure AES-GCM implementation as an
example in crypto/cipher instead of AES directly.

Change-Id: I84453ebb18e0bc79344a24171a031ec0d7ccec2e
Reviewed-on: https://go-review.googlesource.com/18803
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/crypto/cipher/example_test.go b/src/crypto/cipher/example_test.go
index 1cfa982df4ba4d7de1fa2db172078002ed64a6dc..f6cc38650610ad23fa474df2a913eabbb5ef106e 100644 (file)
--- a/src/crypto/cipher/example_test.go
+++ b/src/crypto/cipher/example_test.go
@@ -14,6 +14,58 @@ import (
        "os"
 )
 
+func ExampleNewGCMEncrypter() {
+       // The key argument should be the AES key, either 16 or 32 bytes
+       // to select AES-128 or AES-256.
+       key := []byte("AES256Key-32Characters1234567890")
+       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)
+}
+
+func ExampleNewGCMDecrypter() {
+       // The key argument should be the AES key, either 16 or 32 bytes
+       // to select AES-128 or AES-256.
+       key := []byte("AES256Key-32Characters1234567890")
+       ciphertext, _ := hex.DecodeString("f90fbef747e7212ad7410d0eee2d965de7e890471695cddd2a5bc0ef5da1d04ad8147b62141ad6e4914aee8c512f64fba9037603d41de0d50b718bd665f019cdcd")
+
+       nonce, _ := hex.DecodeString("bb8ef84243d2ee95a41c6c57")
+
+       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", string(plaintext))
+}
+
 func ExampleNewCBCDecrypter() {
        key := []byte("example key 1234")
        ciphertext, _ := hex.DecodeString("f363f3ccdcb12bb883abf484ba77d9cd7d32b5baecb3d4b1b3e0e4beffdb3ded")