Describe the segment_size and counter keyword arguments.

Another bunch of rewrites and clarifications.

I now think this PEP is complete enough to implement.  My next step
will be to implement it and see if any parts turn out to be horribly
complicated or inefficient.  If nothing turns up, I'll finalize the
PEP; if there are problems, the PEP will be revised in light of
implementation experience

pep-0272.txt

@@ -36,28 +36,32 @@ Introduction
         6         MODE_CTR      Counter
 
     These modes are to be implemented as described in NIST publication
-    SP-800A[1].  Descriptions of the first three feedback modes can
+    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
+    (The numeric value 4 is reserved for MODE_PGP, a variant of CFB
-    described in RFC 2440: "OpenPGP Message Format"[3]. This mode
+    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.)
+    for all block encryption ciphers, though supporting it is a nice
+    extra feature.)
 
     In a strict formal sense, stream ciphers encrypt data bit-by-bit;
     practically, stream ciphers work on a character-by-character
-    basis.  Stream ciphers can use exactly the same interface as block
+    basis.  Stream ciphers can support the API described here by using
-    ciphers, fixing the block length at 1; this is how block and
+    fixing the block length at 1; this is how block and stream ciphers
-    stream ciphers can be distinguished.  The only feedback mode
+    could be distinguished.  The only feedback mode available for
-    available for stream ciphers is ECB mode.
+    stream ciphers is ECB mode.
 
 
 Specification
 
-    All cipher algorithms share a common interface.  
+    Encryption modules can add additional functions, methods, and
+    attributes beyond those described in this PEP, but all of the
+    features described in this PEP must be present for a module to 
+    claim compliance with it.  
 
-    Secret-key encryption modules define one function:
+    Secret-key encryption modules should define one function:
 
     new(key, mode, [IV], **kwargs)
 
@@ -65,33 +69,73 @@ Specification
     string 'key', and using the feedback mode 'mode', which must be
     one of the constants from the table above. 
 
-    If 'mode' is CBC or CFB, 'IV' must be provided, and must be a
+    If 'mode' is MODE_CBC or MODE_CFB, 'IV' must be provided and must
-    string of the same length as the block size.  Not providing a
+    be a string of the same length as the block size.  Not providing a
-    value of 'IV' will result in a XXXError exception being raised.
+    value of 'IV' will result in a ValueError exception being raised.
-    (what exception?  ValueError?  ciphermodule.error?)    
 
     Depending on the algorithm, a module may support additional
-    keyword arguments to this function.  The most common keyword
+    keyword arguments to this function.  Some keyword arguments are
-    argument will likely be 'rounds', to set the number of rounds to
+    specified by this PEP, and modules are free to add additional
-    be used.
+    keyword arguments.  If a value isn't provided for a given keyword,
+    a secure default value should be used.  For example, if an
+    algorithm has a selectable number of rounds between 1 and 16, and
+    1-round encryption is insecure and 8-round encryption is believed
+    secure, the default value for 'rounds' should be 8 or more.
+    (Module implementors can choose a very slow but secure value, too,
+    such as 16 in this example.  This decision is left up to the
+    implementor.)
 
-    Secret-key encryption modules define two variables:
+    The following table lists keyword arguments defined by this PEP:
+    
+      Keyword                 Meaning
+    counter               Callable object that returns counter blocks 
+                          (see below; CTR mode only) 
+
+    rounds                Number of rounds of encryption to use
+
+    segment_size          Size of data and ciphertext segments, 
+                          measured in bits (see below; CFB mode only)
+                               
+    The Counter feedback mode requires a sequence of input blocks,
+    called counters, that are used to produce the output.  When 'mode'
+    is MODE_CTR, the 'counter' keyword argument must be provided, and
+    its value must be a callable object, such as a function or method.
+    Successive calls to this callable object must return a sequence of
+    strings that are of the length 'block_size' and that never
+    repeats.  (Appendix B of the NIST publication gives a way to
+    generate such a sequence, but that's beyond the scope of this
+    PEP.)
+    
+    The CFB mode operates on segments of the plaintext and ciphertext
+    that are 'segment_size' bits long.  Therefore, when using this
+    mode, the input and output strings must be a multiple of
+    'segment_size' bits in length.  'segment_size' must be an integer
+    between 1 and block_size*8, inclusive.  (The factor of 8 comes
+    from 'block_size' being measured in bytes and not in bits).  The
+    default value for this parameter should be block_size*8.
+    Implementors are allowed to constrain 'segment_size' to be a
+    multiple of 8 for simplicity, but they're encouraged to support
+    arbitrary values for generality.
+
+    Secret-key encryption modules should define two variables:
 
     block_size
 
         An integer value; the size of the blocks encrypted by this
-        module.  For all feedback modes, the length of strings passed to
+        module, measured in bytes.  For all feedback modes, the length
-        the encrypt() and decrypt() must be a multiple of the block size.
+        of strings passed to the encrypt() and decrypt() must be a
-        For stream ciphers, block_size will be 1.
+        multiple of the block size.  For stream ciphers, block_size
+        will be 1.
 
     key_size
 
         An integer value; the size of the keys required by this
-        module.  If key_size is None, then the algorithm accepts
+        module, measured in bytes.  If key_size is None, then the
-        arbitrary-length keys.  You cannot pass a key of length 0
+        algorithm accepts arbitrary-length keys.  You cannot pass a
-        (that is, the null string '') as such a variable-length key.
+        key of length 0 (that is, the null string '') as such a
+        variable-length key.
 
-    Cipher objects require two attributes:
+    Cipher objects should have two attributes:
 
     block_size
 
@@ -111,34 +155,36 @@ Specification
 
     decrypt(string)
 
-        Decrypts 'string, using the key-dependent data in the object,
+        Decrypts '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.
+        must be an exact multiple of the algorithm's block size or, in
-        Returns a string containing the plaintext.
+        CFB mode, of the segment size.  Returns a string containing
+        the plaintext.
 
     encrypt(string)
 
         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
+        block size or, in CFB mode, of the segment size.  For stream
-        length.  Returns a string containing the ciphertext.
+        ciphers, the string can be of any length.  Returns a string
+        containing the ciphertext.
 
     Here's an example, using a module named 'DES':
 
     >>> import DES
     >>> obj = DES.new('abcdefgh', DES.MODE_ECB)
-    >>> plain="Guido van Rossum is a space alien."
+    >>> plaintext = "Guido van Rossum is a space alien."
-    >>> len(plain)
+    >>> len(plaintext)
     34
-    >>> obj.encrypt(plain)
+    >>> obj.encrypt(plaintext)
     Traceback (innermost last):
       File "<stdin>", line 1, in ?
     ValueError: Strings for DES must be a multiple of 8 in length
-    >>> ciph=obj.encrypt(plain+'XXXXXX')
+    >>> ciphertext = obj.encrypt(plain+'XXXXXX')   # Add padding
-    >>> ciph
+    >>> ciphertext
     '\021,\343Nq\214DY\337T\342pA\372\255\311s\210\363,\300j\330\250\312\347\342I\3215w\03561\303dgb/\006'
-    >>> obj.decrypt(ciph)
+    >>> obj.decrypt(ciphertext)
     'Guido van Rossum is a space alien.XXXXXX'
 
 
@@ -153,7 +199,6 @@ References
     http://www.faqs.org/rfcs/rfc2440.html)
 
 
-
 Copyright
 
     This document has been placed in the public domain.