[Python-checkins] CVS: python/nondist/peps pep-0272.txt,NONE,1.1

2001年9月20日 09:06:18 -0700

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv25751
Added Files:
	pep-0272.txt 
Log Message:
Initial check-in of PEP 272, "API for Secret-Key Encryption Algorithms"
--- NEW FILE: pep-0272.txt ---
PEP: XXX
Title: API for Secret-Key Encryption Algorithms
Version: $Revision: 1.1 $
Author: A.M. Kuchling <akuchlin@mems-exchange.org>
Status: Draft
Type: Informational
Created: 18-Sep-2001
Post-History:
Abstract
 This document specifies a standard API for secret-key encryption
 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.
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.
 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: 
 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
 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.
Specification
 All cipher algorithms share a common interface. After importing a
 given module, there is exactly one function and two variables
 available.
 Secret-key encryption modules define one function:
 new(key, mode, [IV], **kwargs)
 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. 
 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
 value of 'IV' will result in a XXXError 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
 argument will likely be 'rounds', to set the number of rounds to
 be used.
 Secret-key encryption modules define two variables:
 blocksize
 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.
 keysize
 An integer value; the size of the keys required by this
 module. If keysize 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:
 blocksize
 An integer value equal to the size of the blocks encrypted by
 this object. For algorithms with a variable block size, this
 value is equal to the block size selected for this object.
 IV
 
 Contains the initial value which will be used to start a
 cipher feedback mode; it will always be a string exactly one
 block in length. After encrypting or decrypting a string,
 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:
 decrypt(string)
 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.
 Returns a string containing the plaintext.
 encrypt(string)
 Encrypts a non-null 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
 length. Returns a string containing the ciphertext.
 Here's an example, using a module named 'DES':
 >>> import DES
 >>> obj = DES.new('abcdefgh', DES.ECB)
 >>> plain="Guido van Rossum is a space alien."
 >>> len(plain)
 34
 >>> obj.encrypt(plain)
 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')
 >>> ciph
 '021,円343円Nq214円DY337円T342円pA372円255円311円s210円363,円300円j330円250円312円347円342円I3215円w03561円303円dgb/006円'
 >>> obj.decrypt(ciph)
 'Guido van Rossum is a space alien.XXXXXX'
References
 RFC2440: "OpenPGP Message Format" (http://rfc2440.x42.com,
 http://www.faqs.org/rfcs/rfc2440.html)
 Applied Cryptography
Copyright
 This document has been placed in the public domain.

Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: