example_test.go

     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