...
Run Format

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

View as plain text