Doc/lib/librotor.tex

   1 \section{\module{rotor} ---
   2          Enigma-like encryption and decryption}
   3
   4 \declaremodule{builtin}{rotor}
   5 \modulesynopsis{Enigma-like encryption and decryption.}
   6
   7 \deprecated{2.3}{The encryption algorithm is insecure.}
   8
   9
  10 This module implements a rotor-based encryption algorithm, contributed by
  11 Lance Ellinghouse\index{Ellinghouse, Lance}.  The design is derived
  12 from the Enigma device\indexii{Enigma}{device}, a machine
  13 used during World War II to encipher messages.  A rotor is simply a
  14 permutation.  For example, if the character `A' is the origin of the rotor,
  15 then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
  16 To encrypt, we choose several different rotors, and set the origins of the
  17 rotors to known positions; their initial position is the ciphering key.  To
  18 encipher a character, we permute the original character by the first rotor,
  19 and then apply the second rotor's permutation to the result. We continue
  20 until we've applied all the rotors; the resulting character is our
  21 ciphertext.  We then change the origin of the final rotor by one position,
  22 from `A' to `B'; if the final rotor has made a complete revolution, then we
  23 rotate the next-to-last rotor by one position, and apply the same procedure
  24 recursively.  In other words, after enciphering one character, we advance
  25 the rotors in the same fashion as a car's odometer. Decoding works in the
  26 same way, except we reverse the permutations and apply them in the opposite
  27 order.
  28 \indexii{Enigma}{cipher}
  29
  30 The available functions in this module are:
  31
  32 \begin{funcdesc}{newrotor}{key\optional{, numrotors}}
  33 Return a rotor object. \var{key} is a string containing the encryption key
  34 for the object; it can contain arbitrary binary data but not null bytes.
  35 The key will be used
  36 to randomly generate the rotor permutations and their initial positions.
  37 \var{numrotors} is the number of rotor permutations in the returned object;
  38 if it is omitted, a default value of 6 will be used.
  39 \end{funcdesc}
  40
  41 Rotor objects have the following methods:
  42
  43 \begin{methoddesc}[rotor]{setkey}{key}
  44 Sets the rotor's key to \var{key}. The key should not contain null bytes.
  45 \end{methoddesc}
  46
  47 \begin{methoddesc}[rotor]{encrypt}{plaintext}
  48 Reset the rotor object to its initial state and encrypt \var{plaintext},
  49 returning a string containing the ciphertext.  The ciphertext is always the
  50 same length as the original plaintext.
  51 \end{methoddesc}
  52
  53 \begin{methoddesc}[rotor]{encryptmore}{plaintext}
  54 Encrypt \var{plaintext} without resetting the rotor object, and return a
  55 string containing the ciphertext.
  56 \end{methoddesc}
  57
  58 \begin{methoddesc}[rotor]{decrypt}{ciphertext}
  59 Reset the rotor object to its initial state and decrypt \var{ciphertext},
  60 returning a string containing the plaintext.  The plaintext string will
  61 always be the same length as the ciphertext.
  62 \end{methoddesc}
  63
  64 \begin{methoddesc}[rotor]{decryptmore}{ciphertext}
  65 Decrypt \var{ciphertext} without resetting the rotor object, and return a
  66 string containing the plaintext.
  67 \end{methoddesc}
  68
  69 An example usage:
  70 \begin{verbatim}
  71 >>> import rotor
  72 >>> rt = rotor.newrotor('key', 12)
  73 >>> rt.encrypt('bar')
  74 '\xab4\xf3'
  75 >>> rt.encryptmore('bar')
  76 '\xef\xfd$'
  77 >>> rt.encrypt('bar')
  78 '\xab4\xf3'
  79 >>> rt.decrypt('\xab4\xf3')
  80 'bar'
  81 >>> rt.decryptmore('\xef\xfd$')
  82 'bar'
  83 >>> rt.decrypt('\xef\xfd$')
  84 'l(\xcd'
  85 >>> del rt
  86 \end{verbatim}
  87
  88 The module's code is not an exact simulation of the original Enigma
  89 device; it implements the rotor encryption scheme differently from the
  90 original. The most important difference is that in the original
  91 Enigma, there were only 5 or 6 different rotors in existence, and they
  92 were applied twice to each character; the cipher key was the order in
  93 which they were placed in the machine.  The Python \module{rotor}
  94 module uses the supplied key to initialize a random number generator;
  95 the rotor permutations and their initial positions are then randomly
  96 generated.  The original device only enciphered the letters of the
  97 alphabet, while this module can handle any 8-bit binary data; it also
  98 produces binary output.  This module can also operate with an
  99 arbitrary number of rotors.
 100
 101 The original Enigma cipher was broken in 1944. % XXX: Is this right?
 102 The version implemented here is probably a good deal more difficult to crack
 103 (especially if you use many rotors), but it won't be impossible for
 104 a truly skillful and determined attacker to break the cipher.  So if you want
 105 to keep the NSA out of your files, this rotor cipher may well be unsafe, but
 106 for discouraging casual snooping through your files, it will probably be
 107 just fine, and may be somewhat safer than using the \UNIX{} \program{crypt}
 108 command.
 109 \index{NSA}
 110 \index{National Security Agency}