From a9aef26a558f6e9c44d6aac5d85ad3c16f1bc0f9 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Wed, 9 Nov 2011 14:40:49 -0800 Subject: [PATCH] effective_go: fix up the description of cipher blocks and streams R=golang-dev, r, agl, dsymonds CC=golang-dev https://golang.org/cl/5374046 --- doc/effective_go.html | 56 +++++++++++++++++++++++++------------------ doc/effective_go.tmpl | 53 ++++++++++++++++++++++++---------------- 2 files changed, 65 insertions(+), 44 deletions(-) diff --git a/doc/effective_go.html b/doc/effective_go.html index 41c7206b8b..bec95e5fb6 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -1915,42 +1915,53 @@ the rest of the code is unaffected by the change of algorithm.

A similar approach allows the streaming cipher algorithms -in the crypto/block package to be +in the various crypto packages to be separated from the block ciphers they chain together. -By analogy with the bufio package, -they wrap a Cipher interface -and return hash.Hash, -io.Reader, or io.Writer -interface values, not specific implementations. +The Block interface +in the crypto/cipherpackage specifies the +behavior of a block cipher, which provides encryption +of a single block of data. +Then, by analogy with the bufio package, +cipher packages that implement this interface +can be used to construct streaming ciphers, represented +by the Stream interface, without +knowing the details of the block encryption.

-The interface to crypto/block includes: +The crypto/cipher interfaces look like this: 

-type Cipher interface {
+type Block interface {
     BlockSize() int
     Encrypt(src, dst []byte)
     Decrypt(src, dst []byte)
 }
 
-// NewECBDecrypter returns a reader that reads data
-// from r and decrypts it using c in electronic codebook (ECB) mode.
-func NewECBDecrypter(c Cipher, r io.Reader) io.Reader
+type Stream interface {
+    XORKeyStream(dst, src []byte)
+}
+
+ +

+Here's the definition of the counter mode (CTR) stream, +which turns a block cipher into a streaming cipher; notice +that the block cipher's details are abstracted away: +

-// NewCBCDecrypter returns a reader that reads data -// from r and decrypts it using c in cipher block chaining (CBC) mode -// with the initialization vector iv. -func NewCBCDecrypter(c Cipher, iv []byte, r io.Reader) io.Reader +
+// NewCTR returns a Stream that encrypts/decrypts using the given Block in
+// counter mode. The length of iv must be the same as the Block's block size.
+func NewCTR(block Block, iv []byte) Stream

-NewECBDecrypter and NewCBCReader apply not +NewCTR applies not just to one specific encryption algorithm and data source but to any -implementation of the Cipher interface and any -io.Reader. Because they return io.Reader -interface values, replacing ECB -encryption with CBC encryption is a localized change. The constructor +implementation of the Block interface and any +Stream. Because they return +interface values, replacing CTR +encryption with other encryption modes is a localized change. The constructor calls must be edited, but because the surrounding code must treat the result only -as an io.Reader, it won't notice the difference. +as a Stream, it won't notice the difference.

Interfaces and methods

@@ -2930,8 +2941,7 @@ import ( "text/template" ) -var // Q=17, R=18 -addr = flag.String("addr", ":1718", "http service address") +var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18 var templ = template.Must(template.New("qr").Parse(templateStr)) diff --git a/doc/effective_go.tmpl b/doc/effective_go.tmpl index 22e1c1d80a..69a16239a1 100644 --- a/doc/effective_go.tmpl +++ b/doc/effective_go.tmpl @@ -1853,42 +1853,53 @@ the rest of the code is unaffected by the change of algorithm.

A similar approach allows the streaming cipher algorithms -in the crypto/block package to be +in the various crypto packages to be separated from the block ciphers they chain together. -By analogy with the bufio package, -they wrap a Cipher interface -and return hash.Hash, -io.Reader, or io.Writer -interface values, not specific implementations. +The Block interface +in the crypto/cipherpackage specifies the +behavior of a block cipher, which provides encryption +of a single block of data. +Then, by analogy with the bufio package, +cipher packages that implement this interface +can be used to construct streaming ciphers, represented +by the Stream interface, without +knowing the details of the block encryption.

-The interface to crypto/block includes: +The crypto/cipher interfaces look like this: 

-type Cipher interface {
+type Block interface {
     BlockSize() int
     Encrypt(src, dst []byte)
     Decrypt(src, dst []byte)
 }
 
-// NewECBDecrypter returns a reader that reads data
-// from r and decrypts it using c in electronic codebook (ECB) mode.
-func NewECBDecrypter(c Cipher, r io.Reader) io.Reader
+type Stream interface {
+    XORKeyStream(dst, src []byte)
+}
+
+ +

+Here's the definition of the counter mode (CTR) stream, +which turns a block cipher into a streaming cipher; notice +that the block cipher's details are abstracted away: +

-// NewCBCDecrypter returns a reader that reads data -// from r and decrypts it using c in cipher block chaining (CBC) mode -// with the initialization vector iv. -func NewCBCDecrypter(c Cipher, iv []byte, r io.Reader) io.Reader +
+// NewCTR returns a Stream that encrypts/decrypts using the given Block in
+// counter mode. The length of iv must be the same as the Block's block size.
+func NewCTR(block Block, iv []byte) Stream

-NewECBDecrypter and NewCBCReader apply not +NewCTR applies not just to one specific encryption algorithm and data source but to any -implementation of the Cipher interface and any -io.Reader. Because they return io.Reader -interface values, replacing ECB -encryption with CBC encryption is a localized change. The constructor +implementation of the Block interface and any +Stream. Because they return +interface values, replacing CTR +encryption with other encryption modes is a localized change. The constructor calls must be edited, but because the surrounding code must treat the result only -as an io.Reader, it won't notice the difference. +as a Stream, it won't notice the difference.

Interfaces and methods

-- 2.52.0