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 5package cipher_test 6 7import ( 8 "bytes" 9 "crypto/aes" 10 "crypto/cipher" 11 "crypto/rand" 12 "encoding/hex" 13 "fmt" 14 "io" 15 "os" 16) 17 18func 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 47func 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 76func 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 119func 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 158func 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 187func 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 217func 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 256func 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 295func 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 329func 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