From 19327490cf29adf518c7c392be6cbdf208888ebb Mon Sep 17 00:00:00 2001 From: "A.M. Kuchling" Date: Mon, 31 Dec 2007 16:47:12 -0500 Subject: [project @ amk@amk.ca-20071231214712-yz0kkn8hgc7xeck8] More conversion work --- Doc/pycrypt.rst | 206 +++++++++++++++++++++++++++----------------------------- 1 file changed, 101 insertions(+), 105 deletions(-) (limited to 'Doc') diff --git a/Doc/pycrypt.rst b/Doc/pycrypt.rst index 2c9aa44..2a98485 100644 --- a/Doc/pycrypt.rst +++ b/Doc/pycrypt.rst @@ -111,7 +111,6 @@ public-key algorithm, can be used to implement digital signatures. The hashing algorithms currently implemented are: -\begin{tableii}{c|l}{} ============= ============= Hash function Digest length ============= ============= @@ -188,7 +187,7 @@ her private key. Bob could then compute a different contract that has the same hash value, and it would appear that Alice signed that bogus contract; she'd have no way to prove otherwise. Finding such a message by brute force takes ``pow(2, b-1)`` operations, where the -hash function produces \emph{b}-bit hashes. +hash function produces *b*-bit hashes. If Bob can only find two messages with the same hash value but can't choose the resulting hash value, he can look for two messages with @@ -230,7 +229,7 @@ MD5 code was implemented by Colin Plumb. The SHA1 code was originally written by Peter Gutmann. The RIPEMD code was written by Antoon Bosselaers, and adapted for the toolkit by Hirendra Hindocha. The SHA256 code was written by Tom St.~Denis and is part of the -LibTomCrypt library (\url{http://www.libtomcrypt.org/}); it was +LibTomCrypt library (http://www.libtomcrypt.org/); it was adapted for the toolkit by Jeethu Rao and Taylor Boon. @@ -284,15 +283,18 @@ non-PGP programs, it's quite non-standard. The currently available block ciphers are listed in the following table, and are in the ``Crypto.Cipher`` package: -\begin{tableii}{c|l}{}{Cipher}{Key Size/Block Size} -AES}{16, 24, or 32 bytes/16 bytes} -ARC2}{Variable/8 bytes} -Blowfish}{Variable/8 bytes} -CAST}{Variable/8 bytes} -DES}{8 bytes/8 bytes} -DES3 (Triple DES)}{16 bytes/8 bytes} -IDEA}{16 bytes/8 bytes} -RC5}{Variable/8 bytes} +================= ============================ +Cipher Key Size/Block Size +================= ============================ +AES 16, 24, or 32 bytes/16 bytes +ARC2 Variable/8 bytes +Blowfish Variable/8 bytes +CAST Variable/8 bytes +DES 8 bytes/8 bytes +DES3 (Triple DES) 16 bytes/8 bytes +IDEA 16 bytes/8 bytes +RC5 Variable/8 bytes +================= ============================ In a strict formal sense, **stream ciphers** encrypt data bit-by-bit; @@ -347,7 +349,6 @@ Returns a ciphering object, using ``key`` and feedback mode and must be a string of the same length as the block size. Some algorithms support additional keyword arguments to this function; see the "Algorithm-specific Notes for Encryption Algorithms" section below for the details. -\end{funcdesc} \begin{datadesc}{block_size} An integer value; the size of the blocks encrypted by this module. @@ -408,15 +409,15 @@ RC5 has a bunch of parameters; see Ronald Rivest's paper at implementation details. The keyword parameters are: * ``version``: The version of the RC5 algorithm to use; currently -the only legal value is ``0x10`` for RC5 1.0. + the only legal value is ``0x10`` for RC5 1.0. * ``wordsize``: The word size to use; 16 or 32 are the only legal -values. (A larger word size is better, so usually 32 will be used. -16-bit RC5 is probably only of academic interest.) + values. (A larger word size is better, so usually 32 will be used. + 16-bit RC5 is probably only of academic interest.) * ``rounds``: The number of rounds to apply, the larger the more -secure: this can be any value from 0 to 255, so you will have to -choose a value balanced between speed and security. + secure: this can be any value from 0 to 255, so you will have to + choose a value balanced between speed and security. Security Notes @@ -462,7 +463,7 @@ Credits The code for Blowfish was written by Bryan Olson, partially based on a previous implementation by Bruce Schneier, who also invented the algorithm; the Blowfish algorithm has been placed in the public domain -and can be used freely. (See \url{http://www.counterpane.com} for more +and can be used freely. (See http://www.counterpane.com for more information about Blowfish.) The CAST implementation was written by Wim Lewis. The DES implementation was written by Eric Young, and the IDEA implementation by Colin Plumb. The RC5 implementation @@ -625,11 +626,14 @@ one thing, others can both encrypt and authenticate. The currently available public-key algorithms are listed in the following table: -\begin{tableii}{c|l}{}{Algorithm}{Capabilities} -RSA}{Encryption, authentication/signatures} -ElGamal}{Encryption, authentication/signatures} -DSA}{Authentication/signatures} -qNEW}{Authentication/signatures} +============= ========================================== +Algorithm Capabilities +============= ========================================== +RSA Encryption, authentication/signatures +ElGamal Encryption, authentication/signatures +DSA Authentication/signatures +qNEW Authentication/signatures +============= ========================================== Many of these algorithms are patented. Before using any of them in a commercial product, consult a patent attorney; you may have to arrange @@ -655,7 +659,6 @@ Public-key modules make the following functions available: Constructs a key object from a tuple of data. This is algorithm-specific; look at the source code for the details. (To be documented later.) -\end{funcdesc} \begin{funcdesc}{generate}{size, randfunc, progress_func=``None}} Generate a fresh public/private key pair. ``size`` is a @@ -669,19 +672,18 @@ An N-bit keys can encrypt messages up to N-1 bits long. accept a single integer ``N`` and return a string of random data ``N`` bytes long. You should always use a cryptographically secure random number generator, such as the one defined in the -\module{Crypto.Util.randpool`` module; \emph{don't} just use the -current time and the \module{random`` module. +``Crypto.Util.randpool`` module; **don't** just use the +current time and the ``random`` module. -``progress_func} is an optional function that will be called with a short +``progress_func`` is an optional function that will be called with a short string containing the key parameter currently being generated; it's useful for interactive applications where a user is waiting for a key to be generated. -\end{funcdesc} If you want to interface with some other program, you will have to know the details of the algorithm being used; this isn't a big loss. If you don't care about working with non-Python software, simply use the -\module{pickle`` module when you need to write a key or a signature to a +``pickle`` module when you need to write a key or a signature to a file. It's portable across all the architectures that Python supports, and it's simple to use. @@ -707,19 +709,19 @@ otherwise. To test if a given key object can sign data, use \begin{methoddesc}{decrypt}{tuple} -Decrypts ``tuple} with the private key, returning another string. +Decrypts ``tuple`` with the private key, returning another string. This requires the private key to be present, and will raise an exception -if it isn't present. It will also raise an exception if ``string} is +if it isn't present. It will also raise an exception if ``string`` is too long. \begin{methoddesc}{encrypt}{string, K} -Encrypts ``string} with the private key, returning a tuple of +Encrypts ``string`` with the private key, returning a tuple of strings; the length of the tuple varies from algorithm to algorithm. -``K} should be a string of random data that is as long as +``K`` should be a string of random data that is as long as possible. Encryption does not require the private key to be present -inside the key object. It will raise an exception if ``string} is -too long. For ElGamal objects, the value of ``K} expressed as a +inside the key object. It will raise an exception if ``string`` is +too long. For ElGamal objects, the value of ``K`` expressed as a big-endian integer must be relatively prime to ``self.p-1}; an exception is raised if it is not. @@ -738,11 +740,11 @@ data. \begin{methoddesc}{sign}{string, K} Sign ``string}, returning a signature, which is just a tuple; in theory the signature may be made up of any Python objects at all; in -practice they'll be either strings or numbers. ``K} should be a +practice they'll be either strings or numbers. ``K`` should be a string of random data that is as long as possible. Different algorithms will return tuples of different sizes. ``sign()`` raises an -exception if ``string} is too long. For ElGamal objects, the value -of ``K} expressed as a big-endian integer must be relatively prime to +exception if ``string`` is too long. For ElGamal objects, the value +of ``K`` expressed as a big-endian integer must be relatively prime to ``self.p-1}; an exception is raised if it is not. @@ -757,52 +759,52 @@ it's simplest to just divide the size by 8 and round down. \begin{methoddesc}{verify}{string, signature} Returns true if the signature is valid, and false otherwise. -``string} is not processed in any way; ``verify`` does +``string`` is not processed in any way; ``verify`` does not run a hash function over the data, but you can easily do that yourself. The ElGamal and DSA algorithms ================================================== -For RSA, the ``K} parameters are unused; if you like, you can just +For RSA, the ``K`` parameters are unused; if you like, you can just pass empty strings. The ElGamal and DSA algorithms require a real -``K} value for technical reasons; see Schneier's book for a detailed +``K`` value for technical reasons; see Schneier's book for a detailed explanation of the respective algorithms. This presents a possible hazard that can inadvertently reveal the private key. Without going into the -mathematical details, the danger is as follows. ``K} is never derived +mathematical details, the danger is as follows. ``K`` is never derived or needed by others; theoretically, it can be thrown away once the encryption or signing operation is performed. However, revealing -``K} for a given message would enable others to derive the secret key -data; worse, reusing the same value of ``K} for two different +``K`` for a given message would enable others to derive the secret key +data; worse, reusing the same value of ``K`` for two different messages would also enable someone to derive the secret key data. An adversary could intercept and store every message, and then try deriving the secret key from each pair of messages. This places implementors on the horns of a dilemma. On the one hand, -you want to store the ``K} values to avoid reusing one; on the other +you want to store the ``K`` values to avoid reusing one; on the other hand, storing them means they could fall into the hands of an adversary. -One can randomly generate ``K} values of a suitable length such as +One can randomly generate ``K`` values of a suitable length such as 128 or 144 bits, and then trust that the random number generator probably won't produce a duplicate anytime soon. This is an implementation decision that depends on the desired level of security and the expected usage lifetime of a private key. I can't choose and -enforce one policy for this, so I've added the ``K} parameter to the -``encrypt} and ``sign} methods. You must choose ``K} by +enforce one policy for this, so I've added the ``K`` parameter to the +``encrypt`` and ``sign`` methods. You must choose ``K`` by generating a string of random data; for ElGamal, when interpreted as a big-endian number (with the most significant byte being the first byte -of the string), ``K} must be relatively prime to ``self.p-1``; any +of the string), ``K`` must be relatively prime to ``self.p-1``; any size will do, but brute force searches would probably start with small primes, so it's probably good to choose fairly large numbers. It might be simplest to generate a prime number of a suitable length using the -\module{Crypto.Util.number} module. +``Crypto.Util.number`` module. Security Notes for Public-key Algorithms ================================================== Any of these algorithms can be trivially broken; for example, RSA can be -broken by factoring the modulus \emph{n} into its two prime factors. +broken by factoring the modulus *n* into its two prime factors. This is easily done by the following code:: for i in range(2, n): @@ -837,33 +839,28 @@ Crypto.Util.number This module contains various number-theoretic functions. \begin{funcdesc}{GCD}{x,y} -Return the greatest common divisor of ``x} and ``y``. -\end{funcdesc} +Return the greatest common divisor of ``x`` and ``y``. \begin{funcdesc}{getPrime}{N, randfunc} -Return an ``N}-bit random prime number, using random data obtained -from the function ``randfunc``. ``randfunc} must take a single +Return an ``N``-bit random prime number, using random data obtained +from the function ``randfunc``. ``randfunc`` must take a single integer argument, and return a string of random data of the -corresponding length; the ``get_bytes()} method of a -``RandomPool} object will serve the purpose nicely, as will the -``read()} method of an opened file such as ``/dev/random``. -\end{funcdesc} +corresponding length; the ``get_bytes()`` method of a +``RandomPool`` object will serve the purpose nicely, as will the +``read()`` method of an opened file such as ``/dev/random``. \begin{funcdesc}{getRandomNumber}{N, randfunc} -Return an ``N}-bit random number, using random data obtained from the -function ``randfunc``. As usual, ``randfunc} must take a single +Return an ``N``-bit random number, using random data obtained from the +function ``randfunc``. As usual, ``randfunc`` must take a single integer argument and return a string of random data of the corresponding length. -\end{funcdesc} \begin{funcdesc}{inverse}{u, v} -Return the inverse of ``u} modulo ``v``. -\end{funcdesc} +Return the inverse of ``u`` modulo ``v``. \begin{funcdesc}{isPrime}{N} -Returns true if the number ``N} is prime, as determined by a +Returns true if the number ``N`` is prime, as determined by a Rabin-Miller test. -\end{funcdesc} Crypto.Util.randpool @@ -911,34 +908,34 @@ adversary could compute them all to find your private key. See \rfc{1750}, "Randomness Recommendations for Security", for an interesting discussion of the issues related to random number generation. -The \module{randpool} module implements a strong random number generator -in the ``RandomPool} class. The internal state consists of a string +The ``randpool`` module implements a strong random number generator +in the ``RandomPool`` class. The internal state consists of a string of random data, which is returned as callers request it. The class keeps track of the number of bits of entropy left, and provides a function to add new random data; this data can be obtained in various ways, such as by using the variance in a user's keystroke timings. \begin{classdesc}{RandomPool}{\optional{numbytes, cipher, hash} } -An object of the ``RandomPool} class can be created without -parameters if desired. ``numbytes} sets the number of bytes of -random data in the pool, and defaults to 160 (1280 bits). ``hash} +An object of the ``RandomPool`` class can be created without +parameters if desired. ``numbytes`` sets the number of bytes of +random data in the pool, and defaults to 160 (1280 bits). ``hash`` can be a string containing the module name of the hash function to use in stirring the random data, or a module object supporting the hashing interface. The default action is to use SHA. -The ``cipher} argument is vestigial; it was removed from version +The ``cipher`` argument is vestigial; it was removed from version 1.1 so RandomPool would work even in the limited exportable subset of -the code. I recommend passing ``hash} using a keyword argument so -that someday I can safely delete the ``cipher} argument +the code. I recommend passing ``hash`` using a keyword argument so +that someday I can safely delete the ``cipher`` argument ``RandomPool`` objects define the following variables and methods: \begin{methoddesc}{add_event}{time\optional{, string}} -Adds an event to the random pool. ``time} should be set to the +Adds an event to the random pool. ``time`` should be set to the current system time, measured at the highest resolution available. -``string} can be a string of data that will be XORed into the pool, +``string`` can be a string of data that will be XORed into the pool, and can be used to increase the entropy of the pool. For example, if you're encrypting a document, you might use the hash value of the document; an adversary presumably won't have the plaintext of the @@ -947,12 +944,12 @@ generator. The return value is the value of \member{self.entropy} after the data has been added. The function works in the following manner: the time -between successive calls to the ``add_event()} method is determined, +between successive calls to the ``add_event()`` method is determined, and the entropy of the data is guessed; the larger the time between calls, the better. The system time is then read and added to the pool, -along with the ``string} parameter, if present. The hope is that the +along with the ``string`` parameter, if present. The hope is that the low-order bits of the time are effectively random. In an application, -it is recommended that ``add_event()} be called as frequently as +it is recommended that ``add_event()`` be called as frequently as possible, with whatever random data can be found. \begin{memberdesc}{bits} @@ -966,12 +963,12 @@ the pool. \begin{memberdesc}{entropy} An integer value containing the number of bits of entropy currently in -the pool. The value is incremented by the ``add_event()} method, -and decreased by the ``get_bytes()} method. +the pool. The value is incremented by the ``add_event()`` method, +and decreased by the ``get_bytes()`` method. \begin{methoddesc}{get_bytes}{num} -Returns a string containing ``num} bytes of random data, and +Returns a string containing ``num`` bytes of random data, and decrements the amount of entropy available. It is not an error to reduce the entropy to zero, or to call this function when the entropy is zero. This simply means that, in theory, enough random information has been @@ -985,16 +982,16 @@ Scrambles the random pool using the previously chosen encryption and hash function. An adversary may attempt to learn or alter the state of the pool in order to affect its future output; this function destroys the existing state of the pool in a non-reversible way. It -is recommended that ``stir()} be called before and after using -the ``RandomPool} object. Even better, several calls to +is recommended that ``stir()`` be called before and after using +the ``RandomPool`` object. Even better, several calls to ``stir()`` can be interleaved with calls to ``add_event()``. -The ``PersistentRandomPool} class is a subclass of ``RandomPool} +The ``PersistentRandomPool`` class is a subclass of ``RandomPool`` that adds the capability to save and load the pool from a disk file. \begin{classdesc}{PersistentRandomPool}{filename, \optional{numbytes, cipher, hash}} -The path given in ``filename} will be automatically opened, and an +The path given in ``filename`` will be automatically opened, and an existing random pool read; if no such file exists, the pool will be initialized as usual. If omitted, the filename defaults to the empty string, which will prevent it from being saved to a file. These @@ -1004,11 +1001,11 @@ constructor. \begin{methoddesc}{save}{} Opens the file named by the \member{filename} attribute, and saves the -random data into the file using the \module{pickle} module. +random data into the file using the ``pickle`` module. -The ``KeyboardRandomPool} class is a subclass of -``PersistentRandomPool} that provides a method to obtain random +The ``KeyboardRandomPool`` class is a subclass of +``PersistentRandomPool`` that provides a method to obtain random data from the keyboard: \begin{methoddesc}{randomize}{} @@ -1043,15 +1040,13 @@ SLOW REIN RULE MOT". Accepts a string of arbitrary data ``key}, and returns a string containing uppercase English words separated by spaces. ``key``'s length must be a multiple of 8. -\end{funcdesc} \begin{funcdesc}{english_to_key}{string} -Accepts ``string} containing English words, and returns a string of +Accepts ``string`` containing English words, and returns a string of binary data representing the key. Words must be separated by whitespace, and can be any mixture of uppercase and lowercase characters. 6 words are required for 8 bytes of key data, so the number of words in ``string`` must be a multiple of 6. -\end{funcdesc} Extending the Toolkit @@ -1062,10 +1057,11 @@ idea. This chapter explains how to write new modules for the Toolkit. The basic process is as follows: -1. Add a new ``.c} file containing an implementation of the new +1. Add a new ``.c`` file containing an implementation of the new algorithm. This file must define 3 or 4 standard functions, -a few constants, and a C ``struct} encapsulating the state variables required by the algorithm. +a few constants, and a C ``struct`` encapsulating the state +variables required by the algorithm. 2. Add the new algorithm to ``setup.py``. @@ -1091,10 +1087,10 @@ There are four functions that need to be written: to initialize the algorithm's state, to hash a string into the algorithm's state, to get a digest from the current state, and to copy a state. -* ``void hash_init(hash_state *self);} -* ``void hash_update(hash_state *self, unsigned char *buffer, int length);} -* ``PyObject *hash_digest(hash_state *self);} -* ``void hash_copy(hash_state *source, hash_state *dest);} +* ``void hash_init(hash_state *self);`` +* ``void hash_update(hash_state *self, unsigned char *buffer, int length);`` +* ``PyObject *hash_digest(hash_state *self);`` +* ``void hash_copy(hash_state *source, hash_state *dest);`` Put ``\#include "hash_template.c"`` at the end of the file to include the actual implementation of the module. @@ -1118,9 +1114,9 @@ The C structure must be named \ctype{block_state}:: There are three functions that need to be written: to initialize the algorithm's state, and to encrypt and decrypt a single block. -* ``void block_init(block_state *self, unsigned char *key, int keylen);} -* ``void block_encrypt(block_state *self, unsigned char *in, unsigned char *out);} -* ``void block_decrypt(block_state *self, unsigned char *in, unsigned char *out);} +* ``void block_init(block_state *self, unsigned char *key, int keylen);`` +* ``void block_encrypt(block_state *self, unsigned char *in, unsigned char *out);`` +* ``void block_decrypt(block_state *self, unsigned char *in, unsigned char *out);`` Put ``\#include "block_template.c"`` at the end of the file to include the actual implementation of the module. @@ -1144,9 +1140,9 @@ The C structure must be named \ctype{stream_state}:: There are three functions that need to be written: to initialize the algorithm's state, and to encrypt and decrypt a single block. -* ``void stream_init(stream_state *self, unsigned char *key, int keylen);} -* ``void stream_encrypt(stream_state *self, unsigned char *block, int length);} -* ``void stream_decrypt(stream_state *self, unsigned char *block, int length);} +* ``void stream_init(stream_state *self, unsigned char *key, int keylen);`` +* ``void stream_encrypt(stream_state *self, unsigned char *block, int length);`` +* ``void stream_decrypt(stream_state *self, unsigned char *block, int length);`` Put ``\#include "stream_template.c"`` at the end of the file to include the actual implementation of the module. -- cgit v1.2.1