Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/librotor.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents f47bc5554418
children f42bca3d7be2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
1 \section{Built-in Module \sectcode{rotor}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \bimodindex{rotor}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
4 This module implements a rotor-based encryption algorithm, contributed by
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
5 Lance Ellinghouse. The design is derived from the Enigma device, a machine
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
6 used during World War II to encipher messages. A rotor is simply a
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
7 permutation. For example, if the character `A' is the origin of the rotor,
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
8 then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
9 To encrypt, we choose several different rotors, and set the origins of the
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
10 rotors to known positions; their initial position is the ciphering key. To
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
11 encipher a character, we permute the original character by the first rotor,
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
12 and then apply the second rotor's permutation to the result. We continue
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
13 until we've applied all the rotors; the resulting character is our
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
14 ciphertext. We then change the origin of the final rotor by one position,
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
15 from `A' to `B'; if the final rotor has made a complete revolution, then we
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
16 rotate the next-to-last rotor by one position, and apply the same procedure
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
17 recursively. In other words, after enciphering one character, we advance
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
18 the rotors in the same fashion as a car's odometer. Decoding works in the
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
19 same way, except we reverse the permutations and apply them in the opposite
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
20 order.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
21 \index{Ellinghouse, Lance}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
22 \indexii{Enigma}{cipher}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
23
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
24 The available functions in this module are:
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
25
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
26 \renewcommand{\indexsubitem}{(in module rotor)}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
27 \begin{funcdesc}{newrotor}{key\optional{\, numrotors}}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
28 Return a rotor object. \var{key} is a string containing the encryption key
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
29 for the object; it can contain arbitrary binary data. The key will be used
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
30 to randomly generate the rotor permutations and their initial positions.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
31 \var{numrotors} is the number of rotor permutations in the returned object;
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
32 if it is omitted, a default value of 6 will be used.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
33 \end{funcdesc}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
34
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
35 Rotor objects have the following methods:
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
36
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
37 \renewcommand{\indexsubitem}{(rotor method)}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
38 \begin{funcdesc}{setkey}{}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
39 Reset the rotor to its initial state.
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
40 \end{funcdesc}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
41
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
42 \begin{funcdesc}{encrypt}{plaintext}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
43 Reset the rotor object to its initial state and encrypt \var{plaintext},
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
44 returning a string containing the ciphertext. The ciphertext is always the
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
45 same length as the original plaintext.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
46 \end{funcdesc}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
47
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
48 \begin{funcdesc}{encryptmore}{plaintext}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
49 Encrypt \var{plaintext} without resetting the rotor object, and return a
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
50 string containing the ciphertext.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
51 \end{funcdesc}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
52
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
53 \begin{funcdesc}{decrypt}{ciphertext}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
54 Reset the rotor object to its initial state and decrypt \var{ciphertext},
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
55 returning a string containing the ciphertext. The plaintext string will
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
56 always be the same length as the ciphertext.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
57 \end{funcdesc}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
58
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
59 \begin{funcdesc}{decryptmore}{ciphertext}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
60 Decrypt \var{ciphertext} without resetting the rotor object, and return a
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
61 string containing the ciphertext.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
62 \end{funcdesc}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
63
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
64 An example usage:
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
65 \bcode\begin{verbatim}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
66 >>> import rotor
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
67 >>> rt = rotor.newrotor('key', 12)
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
68 >>> rt.encrypt('bar')
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
69 '\2534\363'
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
70 >>> rt.encryptmore('bar')
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
71 '\357\375$'
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
72 >>> rt.encrypt('bar')
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
73 '\2534\363'
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
74 >>> rt.decrypt('\2534\363')
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
75 'bar'
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
76 >>> rt.decryptmore('\357\375$')
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
77 'bar'
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
78 >>> rt.decrypt('\357\375$')
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
79 'l(\315'
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
80 >>> del rt
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
81 \end{verbatim}\ecode
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
82
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
83 The module's code is not an exact simulation of the original Enigma device;
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
84 it implements the rotor encryption scheme differently from the original. The
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
85 most important difference is that in the original Enigma, there were only 5
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
86 or 6 different rotors in existence, and they were applied twice to each
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
87 character; the cipher key was the order in which they were placed in the
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
88 machine. The Python rotor module uses the supplied key to initialize a
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
89 random number generator; the rotor permutations and their initial positions
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
90 are then randomly generated. The original device only enciphered the
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
91 letters of the alphabet, while this module can handle any 8-bit binary data;
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
92 it also produces binary output. This module can also operate with an
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
93 arbitrary number of rotors.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
94
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
95 The original Enigma cipher was broken in 1944. % XXX: Is this right?
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
96 The version implemented here is probably a good deal more difficult to crack
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
97 (especially if you use many rotors), but it won't be impossible for
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
98 a truly skilful and determined attacker to break the cipher. So if you want
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
99 to keep the NSA out of your files, this rotor cipher may well be unsafe, but
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
100 for discouraging casual snooping through your files, it will probably be
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
101 just fine, and may be somewhat safer than using the Unix \file{crypt}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
102 command.
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
103 \index{National Security Agency}\index{crypt(1)}
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
104 % XXX How were Unix commands represented in the docs?
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
105