Lots of small corrections by Andrew Kuchling (plus all new rotor docs)

Doc/librotor.tex

@@ -1,6 +1,105 @@
 \section{Built-in module \sectcode{rotor}}
 \bimodindex{rotor}
 
-This module implements a rotor-based encryption algorithm, contributed
-by Lance Ellinghouse.  Currently no further documentation is available
---- you are kindly advised to read the source...
+This module implements a rotor-based encryption algorithm, contributed by
+Lance Ellinghouse.  The design is derived from the Enigma device, a machine
+used during World War II to encipher messages.  A rotor is simply a
+permutation.  For example, if the character `A' is the origin of the rotor,
+then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
+To encrypt, we choose several different rotors, and set the origins of the
+rotors to known positions; their initial position is the ciphering key.  To
+encipher a character, we permute the original character by the first rotor,
+and then apply the second rotor's permutation to the result. We continue
+until we've applied all the rotors; the resulting character is our
+ciphertext.  We then change the origin of the final rotor by one position,
+from `A' to `B'; if the final rotor has made a complete revolution, then we
+rotate the next-to-last rotor by one position, and apply the same procedure
+recursively.  In other words, after enciphering one character, we advance
+the rotors in the same fashion as a car's odometer. Decoding works in the
+same way, except we reverse the permutations and apply them in the opposite
+order.
+\index{Ellinghouse, Lance}
+\indexii{Enigma}{cipher}
+
+The available functions in this module are:
+
+\renewcommand{\indexsubitem}{(in module rotor)}
+\begin{funcdesc}{newrotor}{key\optional{\, numrotors}}
+Returns a rotor object. \var{key} is a string containing the encryption key
+for the object; it can contain arbitrary binary data. The key will be used
+to randomly generate the rotor permutations and their initial positions.
+\var{numrotors} is the number of rotor permutations in the returned object;
+if it is omitted, a default value of 6 will be used.
+\end{funcdesc}
+
+Rotor objects have the following methods:
+
+\renewcommand{\indexsubitem}{(rotor method)}
+\begin{funcdesc}{setkey}{}
+Resets the rotor to its initial state.
+\end{funcdesc}
+
+\begin{funcdesc}{encrypt}{plaintext}
+Resets the rotor object to its initial state and encrypts \var{plaintext},
+returning a string containing the ciphertext.  The ciphertext is always the
+same length as the original plaintext.
+\end{funcdesc}
+
+\begin{funcdesc}{encryptmore}{plaintext}
+Encrypts \var{plaintext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decrypt}{ciphertext}
+Resets the rotor object to its initial state and decrypts \var{ciphertext},
+returning a string containing the ciphertext.  The plaintext string will
+always be the same length as the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decryptmore}{ciphertext}
+Decrypts \var{ciphertext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+An example usage:
+\bcode\begin{verbatim}
+>>> import rotor
+>>> rt = rotor.newrotor('key', 12)
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.encryptmore('bar')
+'\357\375$'
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.decrypt('\2534\363')
+'bar'
+>>> rt.decryptmore('\357\375$')
+'bar'
+>>> rt.decrypt('\357\375$')
+'l(\315'
+>>> del rt
+\end{verbatim}\ecode
+
+The module's code is not an exact simulation of the original Enigma device;
+it implements the rotor encryption scheme differently from the original. The
+most important difference is that in the original Enigma, there were only 5
+or 6 different rotors in existence, and they were applied twice to each
+character; the cipher key was the order in which they were placed in the
+machine.  The Python rotor module uses the supplied key to initialize a
+random number generator; the rotor permutations and their initial positions
+are then randomly generated.  The original device only enciphered the
+letters of the alphabet, while this module can handle any 8-bit binary data;
+it also produces binary output.  This module can also operate with an
+arbitrary number of rotors.
+
+The original Enigma cipher was broken in 1944. % XXX: Is this right?
+The version implemented here is probably a good deal more difficult to crack
+(especially if you use many rotors), but it won't be impossible for
+a truly skilful and determined attacker to break the cipher.  So if you want
+to keep the NSA out of your files, this rotor cipher may well be unsafe, but
+for discouraging casual snooping through your files, it will probably be
+just fine, and may be somewhat safer than using the Unix \file{crypt}
+command.
+\index{National Security Agency}\index{crypt(1)}
+% XXX How were Unix commands represented in the docs?
+