合规国际互联网加速 OSASE为企业客户提供高速稳定SD-WAN国际加速解决方案。 广告
# package cipher `import "crypto/cipher"` cipher包实现了多个标准的用于包装底层块加密算法的加密算法实现。 参见[http://csrc.nist.gov/groups/ST/toolkit/BCM/current_modes.html](http://csrc.nist.gov/groups/ST/toolkit/BCM/current_modes.html)和NIST Special Publication 800-38A。 ## Index * [type Block](#Block) * [type BlockMode](#BlockMode) * [func NewCBCDecrypter(b Block, iv []byte) BlockMode](#NewCBCDecrypter) * [func NewCBCEncrypter(b Block, iv []byte) BlockMode](#NewCBCEncrypter) * [type Stream](#Stream) * [func NewCFBDecrypter(block Block, iv []byte) Stream](#NewCFBDecrypter) * [func NewCFBEncrypter(block Block, iv []byte) Stream](#NewCFBEncrypter) * [func NewCTR(block Block, iv []byte) Stream](#NewCTR) * [func NewOFB(b Block, iv []byte) Stream](#NewOFB) * [type StreamReader](#StreamReader) * [func (r StreamReader) Read(dst []byte) (n int, err error)](#StreamReader.Read) * [type StreamWriter](#StreamWriter) * [func (w StreamWriter) Write(src []byte) (n int, err error)](#StreamWriter.Write) * [func (w StreamWriter) Close() error](#StreamWriter.Close) * [type AEAD](#AEAD) * [func NewGCM(cipher Block) (AEAD, error)](#NewGCM) ### Examples * [NewCBCDecrypter](#example-NewCBCDecrypter) * [NewCBCEncrypter](#example-NewCBCEncrypter) * [NewCFBDecrypter](#example-NewCFBDecrypter) * [NewCFBEncrypter](#example-NewCFBEncrypter) * [NewCTR](#example-NewCTR) * [NewOFB](#example-NewOFB) * [StreamReader](#example-StreamReader) * [StreamWriter](#example-StreamWriter) ## type [Block](https://github.com/golang/go/blob/master/src/crypto/cipher/cipher.go#L15 "View Source") ``` type Block interface { // 返回加密字节块的大小 BlockSize() int // 加密src的第一块数据并写入dst,src和dst可指向同一内存地址 Encrypt(dst, src []byte) // 解密src的第一块数据并写入dst,src和dst可指向同一内存地址 Decrypt(dst, src []byte) } ``` Block接口代表一个使用特定密钥的底层块加/解密器。它提供了加密和解密独立数据块的能力。 ## type [BlockMode](https://github.com/golang/go/blob/master/src/crypto/cipher/cipher.go#L37 "View Source") ``` type BlockMode interface { // 返回加密字节块的大小 BlockSize() int // 加密或解密连续的数据块,src的尺寸必须是块大小的整数倍,src和dst可指向同一内存地址 CryptBlocks(dst, src []byte) } ``` BlockMode接口代表一个工作在块模式(如CBC、ECB等)的加/解密器。 ### func [NewCBCEncrypter](https://github.com/golang/go/blob/master/src/crypto/cipher/cbc.go#L35 "View Source") ``` func NewCBCEncrypter(b Block, iv []byte) BlockMode ``` 返回一个密码分组链接模式的、底层用b加密的BlockMode接口,初始向量iv的长度必须等于b的块尺寸。 Example ``` key := []byte("example key 1234") plaintext := []byte("exampleplaintext") // CBC mode works on blocks so plaintexts may need to be padded to the // next whole block. For an example of such padding, see // https://tools.ietf.org/html/rfc5246#section-6.2.3.2\. Here we'll // assume that the plaintext is already of the correct length. if len(plaintext)%aes.BlockSize != 0 { panic("plaintext is not a multiple of the block size") } block, err := aes.NewCipher(key) if err != nil { panic(err) } // The IV needs to be unique, but not secure. Therefore it's common to // include it at the beginning of the ciphertext. ciphertext := make([]byte, aes.BlockSize+len(plaintext)) iv := ciphertext[:aes.BlockSize] if _, err := io.ReadFull(rand.Reader, iv); err != nil { panic(err) } mode := cipher.NewCBCEncrypter(block, iv) mode.CryptBlocks(ciphertext[aes.BlockSize:], plaintext) // It's important to remember that ciphertexts must be authenticated // (i.e. by using crypto/hmac) as well as being encrypted in order to // be secure. fmt.Printf("%x\n", ciphertext) ``` ### func [NewCBCDecrypter](https://github.com/golang/go/blob/master/src/crypto/cipher/cbc.go#L81 "View Source") ``` func NewCBCDecrypter(b Block, iv []byte) BlockMode ``` 返回一个密码分组链接模式的、底层用b解密的BlockMode接口,初始向量iv必须和加密时使用的iv相同。 Example ``` key := []byte("example key 1234") ciphertext, _ := hex.DecodeString("f363f3ccdcb12bb883abf484ba77d9cd7d32b5baecb3d4b1b3e0e4beffdb3ded") block, err := aes.NewCipher(key) if err != nil { panic(err) } // The IV needs to be unique, but not secure. Therefore it's common to // include it at the beginning of the ciphertext. if len(ciphertext) < aes.BlockSize { panic("ciphertext too short") } iv := ciphertext[:aes.BlockSize] ciphertext = ciphertext[aes.BlockSize:] // CBC mode always works in whole blocks. if len(ciphertext)%aes.BlockSize != 0 { panic("ciphertext is not a multiple of the block size") } mode := cipher.NewCBCDecrypter(block, iv) // CryptBlocks can work in-place if the two arguments are the same. mode.CryptBlocks(ciphertext, ciphertext) // If the original plaintext lengths are not a multiple of the block // size, padding would have to be added when encrypting, which would be // removed at this point. For an example, see // https://tools.ietf.org/html/rfc5246#section-6.2.3.2\. However, it's // critical to note that ciphertexts must be authenticated (i.e. by // using crypto/hmac) before being decrypted in order to avoid creating // a padding oracle. fmt.Printf("%s\n", ciphertext) ``` Output: ``` exampleplaintext ``` ## type [Stream](https://github.com/golang/go/blob/master/src/crypto/cipher/cipher.go#L29 "View Source") ``` type Stream interface { // 从加密器的key流和src中依次取出字节二者xor后写入dst,src和dst可指向同一内存地址 XORKeyStream(dst, src []byte) } ``` Stream接口代表一个流模式的加/解密器。 ### func [NewCFBEncrypter](https://github.com/golang/go/blob/master/src/crypto/cipher/cfb.go#L45 "View Source") ``` func NewCFBEncrypter(block Block, iv []byte) Stream ``` 返回一个密码反馈模式的、底层用block加密的Stream接口,初始向量iv的长度必须等于block的块尺寸。 Example ``` key := []byte("example key 1234") plaintext := []byte("some plaintext") block, err := aes.NewCipher(key) if err != nil { panic(err) } // The IV needs to be unique, but not secure. Therefore it's common to // include it at the beginning of the ciphertext. ciphertext := make([]byte, aes.BlockSize+len(plaintext)) iv := ciphertext[:aes.BlockSize] if _, err := io.ReadFull(rand.Reader, iv); err != nil { panic(err) } stream := cipher.NewCFBEncrypter(block, iv) stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext) // It's important to remember that ciphertexts must be authenticated // (i.e. by using crypto/hmac) as well as being encrypted in order to // be secure. ``` ### func [NewCFBDecrypter](https://github.com/golang/go/blob/master/src/crypto/cipher/cfb.go#L52 "View Source") ``` func NewCFBDecrypter(block Block, iv []byte) Stream ``` 返回一个密码反馈模式的、底层用block解密的Stream接口,初始向量iv必须和加密时使用的iv相同。 Example ``` key := []byte("example key 1234") ciphertext, _ := hex.DecodeString("22277966616d9bc47177bd02603d08c9a67d5380d0fe8cf3b44438dff7b9") block, err := aes.NewCipher(key) if err != nil { panic(err) } // The IV needs to be unique, but not secure. Therefore it's common to // include it at the beginning of the ciphertext. if len(ciphertext) < aes.BlockSize { panic("ciphertext too short") } iv := ciphertext[:aes.BlockSize] ciphertext = ciphertext[aes.BlockSize:] stream := cipher.NewCFBDecrypter(block, iv) // XORKeyStream can work in-place if the two arguments are the same. stream.XORKeyStream(ciphertext, ciphertext) fmt.Printf("%s", ciphertext) ``` Output: ``` some plaintext ``` ### func [NewOFB](https://github.com/golang/go/blob/master/src/crypto/cipher/ofb.go#L19 "View Source") ``` func NewOFB(b Block, iv []byte) Stream ``` 返回一个输出反馈模式的、底层采用b生成key流的Stream接口,初始向量iv的长度必须等于b的块尺寸。 Example ``` key := []byte("example key 1234") plaintext := []byte("some plaintext") block, err := aes.NewCipher(key) if err != nil { panic(err) } // The IV needs to be unique, but not secure. Therefore it's common to // include it at the beginning of the ciphertext. ciphertext := make([]byte, aes.BlockSize+len(plaintext)) iv := ciphertext[:aes.BlockSize] if _, err := io.ReadFull(rand.Reader, iv); err != nil { panic(err) } stream := cipher.NewOFB(block, iv) stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext) // It's important to remember that ciphertexts must be authenticated // (i.e. by using crypto/hmac) as well as being encrypted in order to // be secure. // OFB mode is the same for both encryption and decryption, so we can // also decrypt that ciphertext with NewOFB. plaintext2 := make([]byte, len(plaintext)) stream = cipher.NewOFB(block, iv) stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:]) fmt.Printf("%s\n", plaintext2) ``` Output: ``` some plaintext ``` ### func [NewCTR](https://github.com/golang/go/blob/master/src/crypto/cipher/ctr.go#L26 "View Source") ``` func NewCTR(block Block, iv []byte) Stream ``` 返回一个计数器模式的、底层采用block生成key流的Stream接口,初始向量iv的长度必须等于block的块尺寸。 Example ``` key := []byte("example key 1234") plaintext := []byte("some plaintext") block, err := aes.NewCipher(key) if err != nil { panic(err) } // The IV needs to be unique, but not secure. Therefore it's common to // include it at the beginning of the ciphertext. ciphertext := make([]byte, aes.BlockSize+len(plaintext)) iv := ciphertext[:aes.BlockSize] if _, err := io.ReadFull(rand.Reader, iv); err != nil { panic(err) } stream := cipher.NewCTR(block, iv) stream.XORKeyStream(ciphertext[aes.BlockSize:], plaintext) // It's important to remember that ciphertexts must be authenticated // (i.e. by using crypto/hmac) as well as being encrypted in order to // be secure. // CTR mode is the same for both encryption and decryption, so we can // also decrypt that ciphertext with NewCTR. plaintext2 := make([]byte, len(plaintext)) stream = cipher.NewCTR(block, iv) stream.XORKeyStream(plaintext2, ciphertext[aes.BlockSize:]) fmt.Printf("%s\n", plaintext2) ``` Output: ``` some plaintext ``` ## type [StreamReader](https://github.com/golang/go/blob/master/src/crypto/cipher/io.go#L14 "View Source") ``` type StreamReader struct { S Stream R io.Reader } ``` 将一个Stream与一个io.Reader接口关联起来,Read方法会调用XORKeyStream方法来处理获取的所有切片。 Example ``` key := []byte("example key 1234") inFile, err := os.Open("encrypted-file") if err != nil { panic(err) } defer inFile.Close() block, err := aes.NewCipher(key) if err != nil { panic(err) } // If the key is unique for each ciphertext, then it's ok to use a zero // IV. var iv [aes.BlockSize]byte stream := cipher.NewOFB(block, iv[:]) outFile, err := os.OpenFile("decrypted-file", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600) if err != nil { panic(err) } defer outFile.Close() reader := &cipher.StreamReader{S: stream, R: inFile} // Copy the input file to the output file, decrypting as we go. if _, err := io.Copy(outFile, reader); err != nil { panic(err) } // Note that this example is simplistic in that it omits any // authentication of the encrypted data. It you were actually to use // StreamReader in this manner, an attacker could flip arbitrary bits in // the output. ``` ### func (StreamReader) [Read](https://github.com/golang/go/blob/master/src/crypto/cipher/io.go#L19 "View Source") ``` func (r StreamReader) Read(dst []byte) (n int, err error) ``` ## type [StreamWriter](https://github.com/golang/go/blob/master/src/crypto/cipher/io.go#L30 "View Source") ``` type StreamWriter struct { S Stream W io.Writer Err error // unused } ``` 将一个Stream与一个io.Writer接口关联起来,Write方法会调用XORKeyStream方法来处理提供的所有切片。如果Write方法返回的n小于提供的切片的长度,则表示StreamWriter不同步,必须丢弃。StreamWriter没有内建的缓存,不需要调用Close方法去清空缓存。 Example ``` key := []byte("example key 1234") inFile, err := os.Open("plaintext-file") if err != nil { panic(err) } defer inFile.Close() block, err := aes.NewCipher(key) if err != nil { panic(err) } // If the key is unique for each ciphertext, then it's ok to use a zero // IV. var iv [aes.BlockSize]byte stream := cipher.NewOFB(block, iv[:]) outFile, err := os.OpenFile("encrypted-file", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600) if err != nil { panic(err) } defer outFile.Close() writer := &cipher.StreamWriter{S: stream, W: outFile} // Copy the input file to the output file, encrypting as we go. if _, err := io.Copy(writer, inFile); err != nil { panic(err) } // Note that this example is simplistic in that it omits any // authentication of the encrypted data. It you were actually to use // StreamReader in this manner, an attacker could flip arbitrary bits in // the decrypted result. ``` ### func (StreamWriter) [Write](https://github.com/golang/go/blob/master/src/crypto/cipher/io.go#L36 "View Source") ``` func (w StreamWriter) Write(src []byte) (n int, err error) ``` ### func (StreamWriter) [Close](https://github.com/golang/go/blob/master/src/crypto/cipher/io.go#L50 "View Source") ``` func (w StreamWriter) Close() error ``` 如果w.W字段实现了io.Closer接口,本方法会调用其Close方法并返回该方法的返回值;否则不做操作返回nil。 ## type [AEAD](https://github.com/golang/go/blob/master/src/crypto/cipher/gcm.go#L14 "View Source") ``` type AEAD interface { // 返回提供给Seal和Open方法的随机数nonce的字节长度 NonceSize() int // 返回原始文本和加密文本的最大长度差异 Overhead() int // 加密并认证明文,认证附加的data,将结果添加到dst,返回更新后的切片。 // nonce的长度必须是NonceSize()字节,且对给定的key和时间都是独一无二的。 // plaintext和dst可以是同一个切片,也可以不同。 Seal(dst, nonce, plaintext, data []byte) []byte // 解密密文并认证,认证附加的data,如果认证成功,将明文添加到dst,返回更新后的切片。 // nonce的长度必须是NonceSize()字节,nonce和data都必须和加密时使用的相同。 // ciphertext和dst可以是同一个切片,也可以不同。 Open(dst, nonce, ciphertext, data []byte) ([]byte, error) } ``` AEAD接口是一种提供了使用关联数据进行认证加密的功能的加密模式。 ### func [NewGCM](https://github.com/golang/go/blob/master/src/crypto/cipher/gcm.go#L62 "View Source") ``` func NewGCM(cipher Block) (AEAD, error) ``` 函数用迦洛瓦计数器模式包装提供的128位Block接口,并返回AEAD接口。