'blocksize' -> 'block_size', 'keysize' -> 'key_size'

Rip out the key_size attribute of cipher objects
Set PEP number
Various rewrites

pep-0272.txt

@@ -1,4 +1,4 @@
-PEP: XXX
+PEP: 272
 Title: API for Secret-Key Encryption Algorithms
 Version: $Revision$
 Author: A.M. Kuchling <akuchlin@mems-exchange.org>
@@ -10,7 +10,7 @@ Post-History:
 Abstract
 
     This document specifies a standard API for secret-key encryption
-    algorithms, such as DES or Rijndael, making it easier to switch
+    algorithms such as DES or Rijndael, making it easier to switch
     between different algorithms and implementations.  The API is
     intended to be suitable for both block and stream ciphers.
 
@@ -20,19 +20,22 @@ 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,
-    if and only if one knows the key (we hope).  The key is a sequence
-    of bits chosen from some very large space of possible keys.
+    if and only if one knows the key.  The key is a sequence of bits
+    chosen from some very large space of possible keys.
 
-    Block ciphers take multibyte inputs of a fixed size (frequently 8
-    or 16 bytes long) and encrypt them.  Block ciphers can be operated
-    in various feedback modes.  The feedback modes supported in this
-    specification are: 
+    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 used by the OpenPGP standard
+        4         PGP           Variant of CFB
+
+    See _Applied Cryptography_ for descriptions of the first three
+    feedback modes.  The PGP feedback mode is described in the OpenPGP
+    RFC.
 
     In a strict formal sense, stream ciphers encrypt data bit-by-bit;
     practically, stream ciphers work on a character-by-character
@@ -44,9 +47,7 @@ Introduction
 
 Specification
 
-    All cipher algorithms share a common interface.  After importing a
-    given module, there is exactly one function and two variables
-    available.
+    All cipher algorithms share a common interface.  
 
     Secret-key encryption modules define one function:
 
@@ -68,23 +69,23 @@ Specification
 
     Secret-key encryption modules define two variables:
 
-    blocksize
+    block_size
 
         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{blocksize} will be 1.
+        For stream ciphers, \code{block_size} will be 1.
 
-    keysize
+    key_size
 
         An integer value; the size of the keys required by this
-        module.  If keysize is zero, then the algorithm accepts
+        module.  If key_size is zero, then the algorithm accepts
         arbitrary-length keys.  You cannot pass a key of length 0
         (that is, the null string '') as such a variable-length key.
 
-    All cipher objects have at least three attributes:
+    Cipher objects require two attributes:
 
-    blocksize
+    block_size
 
         An integer value equal to the size of the blocks encrypted by
         this object.  For algorithms with a variable block size, this
@@ -98,17 +99,7 @@ Specification
         this value is updated to reflect the modified feedback text.
         It is read-only, and cannot be assigned a new value.
 
-    keysize (XXX this is in mxCrypto, but do we actually need this?  
-        I can't remember why it was there, and it seems stupid.)
-
-        An integer value equal to the size of the keys used by this
-        object.  If keysize is zero, then the algorithm accepts
-        arbitrary-length keys.  For algorithms that support variable
-        length keys, this will be 0.  Identical to the module variable
-        of the same name.  It does *not* contain the size of the key
-        actually
-
-    The methods for secret-key encryption objects are as follows:
+    Cipher objects require the following methods:
 
     decrypt(string)
 
@@ -119,7 +110,7 @@ Specification
 
     encrypt(string)
 
-        Encrypts a non-null string, using the key-dependent data in
+        Encrypts a non-empty string, using the key-dependent data in
         the object, and with the appropriate feedback mode.  The
         string's length must be an exact multiple of the algorithm's
         block size; for stream ciphers, the string can be of any