Prefix mode constants with MODE_

Remove PGP mode; add CTR mode, and a reference to the NIST publication
Other minor changes

pep-0272.txt

@@ -19,30 +19,38 @@ Introduction
 
     Encryption algorithms transform their input data (called
     plaintext) in some way that is dependent on a variable key,
-    producing ciphertext.  The transformation can easily be reversed,
+    producing ciphertext.  The transformation can easily be reversed
     if and only if one knows the key.  The key is a sequence of bits
-    chosen from some very large space of possible keys.
+    chosen from some very large space of possible keys.  There are two
+    classes of encryption algorithms: block ciphers and stream ciphers.
 
     Block ciphers encrypt multibyte inputs of a fixed size (frequently
     8 or 16 bytes long), and can be operated in various feedback
     modes.  The feedback modes supported in this specification are:
 
         Number    Constant      Description
-        1         ECB           Electronic Code Book     
-        2         CBC           Cipher Block Chaining
-        3         CFB           Cipher FeedBack 
-        4         PGP           Variant of CFB
+        1         MODE_ECB      Electronic Code Book     
+        2         MODE_CBC      Cipher Block Chaining
+        3         MODE_CFB      Cipher FeedBack 
+        5         MODE_OFB      Output Feedback
+        6         MODE_CTR      Counter
 
-    See _Applied Cryptography_ for descriptions of the first three
-    feedback modes.  The PGP feedback mode is described in the OpenPGP
-    RFC.
+    These modes are to be implemented as described in NIST publication
+    SP-800A[1].  Descriptions of the first three feedback modes can
+    also be found in Bruce Schneier's book _Applied
+    Cryptography_ [2]. 
+
+    (The value of 4 is reserved for MODE_PGP, a variant of CFB
+    described in RFC 2440: "OpenPGP Message Format"[3]. This mode
+    isn't considered important enough to make it worth requiring it
+    for all block encryption ciphers.)
 
     In a strict formal sense, stream ciphers encrypt data bit-by-bit;
     practically, stream ciphers work on a character-by-character
-    basis.  Stream ciphers use exactly the same interface as block
-    ciphers, with a block length that will always be 1; this is how
-    block and stream ciphers can be distinguished.  The only feedback
-    mode available for stream ciphers is ECB mode.
+    basis.  Stream ciphers can use exactly the same interface as block
+    ciphers, fixing the block length at 1; this is how block and
+    stream ciphers can be distinguished.  The only feedback mode
+    available for stream ciphers is ECB mode.
 
 
 Specification
@@ -55,7 +63,7 @@ Specification
 
     Returns a ciphering object, using the secret key contained in the
     string 'key', and using the feedback mode 'mode', which must be
-    one of the constants from the following table.  
+    one of the constants from the table above. 
 
     If 'mode' is CBC or CFB, 'IV' must be provided, and must be a
     string of the same length as the block size.  Not providing a
@@ -74,7 +82,7 @@ Specification
         An integer value; the size of the blocks encrypted by this
         module.  For all feedback modes, the length of strings passed to
         the encrypt() and decrypt() must be a multiple of the block size.
-        For stream ciphers, \code{block_size} will be 1.
+        For stream ciphers, block_size will be 1.
 
     key_size
 
@@ -119,7 +127,7 @@ Specification
     Here's an example, using a module named 'DES':
 
     >>> import DES
-    >>> obj = DES.new('abcdefgh', DES.ECB)
+    >>> obj = DES.new('abcdefgh', DES.MODE_ECB)
     >>> plain="Guido van Rossum is a space alien."
     >>> len(plain)
     34
@@ -136,10 +144,14 @@ Specification
 
 References
 
-    RFC2440: "OpenPGP Message Format" (http://rfc2440.x42.com,
+    [1] NIST publication SP 800-38A, "Recommendation for Block Cipher
+    Modes of Operation" (http://csrc.nist.gov/encryption/modes/)
+
+    [2] Applied Cryptography
+
+    [3] RFC2440: "OpenPGP Message Format" (http://rfc2440.x42.com,
     http://www.faqs.org/rfcs/rfc2440.html)
 
-    Applied Cryptography
 
 
 Copyright