mirror of
https://github.com/python/cpython
synced 2024-11-02 14:48:31 +00:00
e47da0ae04
* \bcode, \ecode added everywhere
* \label{module-foo} added everywhere
* A few \seealso sections added.
* Indentation fixed inside verbatim in lib*tex files
106 lines
4.5 KiB
TeX
106 lines
4.5 KiB
TeX
\section{Built-in Module \sectcode{rotor}}
|
|
\label{module-rotor}
|
|
\bimodindex{rotor}
|
|
|
|
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}}
|
|
Return 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}{key}
|
|
Sets the rotor's key to \var{key}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{encrypt}{plaintext}
|
|
Reset the rotor object to its initial state and encrypt \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}
|
|
Encrypt \var{plaintext} without resetting the rotor object, and return a
|
|
string containing the ciphertext.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{decrypt}{ciphertext}
|
|
Reset the rotor object to its initial state and decrypt \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}
|
|
Decrypt \var{ciphertext} without resetting the rotor object, and return 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?
|
|
|