# HG changeset patch # User Brian Neal # Date 1392773154 21600 # Node ID 3a53d309bbb7296bca2be824dd571de97d5e320a # Parent 39d0121a018d53323b097e013f9e14f728f109db Finished the README. diff -r 39d0121a018d -r 3a53d309bbb7 README.rst --- a/README.rst Mon Feb 17 20:34:53 2014 -0600 +++ b/README.rst Tue Feb 18 19:25:54 2014 -0600 @@ -13,17 +13,21 @@ :Documentation: This file :Support: https://bitbucket.org/bgneal/purple/issues -``Purple`` is a Python library and command-line utility for simulating the `PURPLE -Machine`_, a cipher machine used by the Japanese Foreign Office before and -during the Second World War. PURPLE was the code name given to machine by U.S. -cryptanalysts. The Japanese called the machine 97-shiki ōbun inji-ki (System 97 -Printing Machine for European Characters), and Angōki B-kata (Type B Cipher -Machine). The machine was used for secure diplomatic communications and was an -electromechanical stepping-switch device. +``Purple`` is a Python library and command-line utility for simulating the +`PURPLE Machine`_, a cipher machine used by the Japanese Foreign Office before +and during the Second World War. PURPLE was the code name given to the machine +by U.S. cryptanalysts. The Japanese called the machine *97-shiki ōbun inji-ki* +(System 97 Printing Machine for European Characters), and *Angōki B-kata* (Type +B Cipher Machine). The machine was used for secure diplomatic communications +and was implemented as an electromechanical stepping-switch device. This project is a Python 3 library and command-line utility for encrypting and decrypting text by simulating the operation of an actual PURPLE machine. +If you are brand new to the ``Purple`` cipher machine, please skip down to the +references section and familiarize yourself with the device. This will help you +understand the terminology used in the documentation, below. + Requirements ############ @@ -64,6 +68,46 @@ $ python -m unittest discover +Initial Settings Syntax +####################### + +In order to exchange messages, each message recipient must use the same initial +machine settings. For the ``Purple`` machine, these settings are the initial +switch positions for the "sixes" and three "twenties" stepping switches, the +switch motion order (which twenties switch is the fast switch, which is the +middle switch, and which is the slow switch), and finally the plugboard +alphabet mapping. + +The ``Purple`` simulation uses the following syntax in both its command-line +application and library code. + +For the switches, we borrow the notation used by U.S. cryptanalysts, for +example:: + + 9-1,24,6-23 + +Here the first number before leading dash, 9, indicates the starting position +of the sixes switch. The next three numbers are the starting positions for the +three twenties switches numbered 1, 2, and 3. Each switch position is a number +from 1 through 25, inclusive. Finally, after the last dash are two digits which +indicate the switch stepping motion. The first number, in this case 2, +indicates that the twenties switch #2 is the fast switch. The second number, 3, +indicates twenties switch #3 is the middle switch. Thus the slow switch, which +is never listed, is in this case twenties switch #1. When using this syntax, do +not insert space characters. + +The plugboard alphabet setting describes how the input typewriters are wired to +the plugboard. We represent this setting as a string of the 26 uppercase +alphabet letters where the first six letters are the wiring to the sixes +switch, and the remaining 20 are wired to the first stage of the twenties +switches. For example:: + + AEIOUYBCDFGHJKLMNPQRSTVWXZ + +For the alphabet setting to be valid, do not insert spaces, and ensure all 26 +letters are used exactly once. + + Command-line Usage ################## @@ -100,20 +144,30 @@ the environment variable PURPLE97_ALPHABET will be used. Input text is supplied either by the -t or by the -f options, but not both. -(TODO: Text goes here explaining the switches and alphabet settings) +The ``purple`` command operates in two modes, either encrypt (specified with +``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can +be specified on the command-line with the ``-t`` or ``--text`` option, or +a read from a file (``-i`` or ``--input``). + +The ``-s`` (or ``--switches``) and ``-a`` (or ``--alphabet``) settings +determine the initial machine settings. They use the syntax described above in +the Initial Settings Syntax section. If you are going to be working with the same initial switch settings and -plugboard alphabet it may be more convenient to specify them as environment -variables instead of repeatedly using the command-line arguments ``-s`` and -``-a``. The examples below assume these statements have been executed:: +plugboard alphabet over many command invocations it may be more convenient to +specify them as environment variables instead of repeatedly using the +command-line arguments. The examples below assume these statements have been +executed:: $ export PURPLE97_SWITCHES=9-1,24,6-23 $ export PURPLE97_ALPHABET=NOKTYUXEQLHBRMPDICJASVWGZF -The ``purple`` command operates in two modes, either encrypt (specified with -``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can -be specified on the command-line with the ``-t`` or ``--text`` option, or -a read from a file (``-i`` or ``--input``). +If you do not specify initial settings, the ``purple`` machine will attempt to +read them from these two environment variables. Failing that, ``purple`` will +use the following initial settings: + +* default switch settings: 1-1,1,1-12 +* default alphabet: AEIOUYBCDFGHJKLMNPQRSTVWXZ When encrypting text, the ``purple`` machine only accepts the letters A-Z, but also allows for "garble" letters to be indicated by using the ``-`` (dash) @@ -125,7 +179,7 @@ A simple encrypt example using the ``-f`` flag is given below:: - $ purple -e -t "The PURPLE machine is now online" -f + $ purple --encrypt -t "The PURPLE machine is now online" -f OGIVT SIAAH MWMHT VIBYY JUOJF UE By default ``purple`` prints the output in 5-letter groups. This can be @@ -133,7 +187,7 @@ To decrypt this message:: - $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" + $ purple --decrypt -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" THEPU RPLEM ACHIN EISNO WONLI NE Note that spaces are ignored on input. Again the output is produced in 5-letter @@ -143,7 +197,7 @@ $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0 THEPURPLEMACHINEISNOWONLINE -Of course you can use file redirection to capture output in a file:: +You can use file redirection to capture output in a file:: $ purple -e -t "The PURPLE machine is now online" -f > secret.txt $ purple -d -i secret.txt @@ -153,19 +207,90 @@ Library Usage ############# +To use ``Purple`` from within Python code you must first construct +a ``Purple97`` object, which represents a single PURPLE cipher machine. The +constructor is given below:: + + class Purple97(switches_pos=None, fast_switch=1, middle_switch=2, + alphabet=None) + +The ``switches_pos`` argument, when not ``None``, must be a 4-tuple or list of +4 integers that describe the initial switch positions. Element 0 is the sixes +initial position, and the remaining elements are the initial positions of the +three twenties switches. These values must be in the range 0-24, inclusive. +If ``None`` then switch positions of all zeroes is assumed. + +The ``fast_switch`` argument indicates which twenties switch (numbered 1-3) is +the fast switch. Likewise, ``middle_switch`` indicates which switch is the +middle switch. The slow switch is inferred. It is an error to give the +``fast_switch`` and ``middle_switch`` arguments the same value. + +The ``alphabet`` argument is the plugboard alphabet mapping. It is expected to +be a 26-letter uppercase string. If ``None``, a mapping of +``AEIOUYBCDFGHJKLMNPQRSTVWXZ`` is assumed. + +For convenience, another constructor is provided that allows you to specify +initial settings in the syntax described above:: + + classmethod Purple97.from_key_sheet(switches, alphabet=None) + +Here ``switches`` is a string in the syntax described above, e.g. +``'9-1,24,6-23'``. + +The ``alphabet`` argument is as described in the first constructor. + +Once constructed, you can use the ``Purple97`` object to perform encrypt and +decrypt operations. For example:: + + from purple.machine import Purple97 + + purple = Purple97.from_key_sheet( + switches='9-1,24,6-23', + alphabet='NOKTYUXEQLHBRMPDICJASVWGZF') + + ciphertext = purple.encrypt('THEPURPLEMACHINEISONLINE') + + purple = Purple97([8, 0, 23, 5], fast_switch=2, middle_switch=3, + alphabet='NOKTYUXEQLHBRMPDICJASVWGZF') + + plaintext = purple.decrypt(ciphertext) + +For more information, please review the docstrings in the code. + Support ####### +To report a bug or suggest a feature, please use the issue tracker at the +`Purple Bitbucket page`_. + References ########## +#. *PURPLE Revealed: Simulation and Computer-aided Cryptanalysis of Angooki + Taipu B*, by Wes Freeman, Geoff Sullivan, and Frode Weierud. This paper + was published in Cryptologia, Volume 27, Issue 1, January, 2003, pp. 1-43. +#. Frode Weierud's CryptoCellar page: `The PURPLE Machine`_ +#. Wikipedia Article: `PURPLE Machine`_ + +The paper in reference 1 is also available here: +http://cryptocellar.web.cern.ch/cryptocellar/pubs/PurpleRevealed.pdf + +This simulator would not have been possible without Frode Weierud's +CryptoCellar page and the detailed explanations and analysis found in reference +1. The author is also deeply grateful for email discussions with Frode Weierud +and Geoff Sullivan who provided me with plaintext, advice, and encouragement. + +The ``Purple`` simulator's operation was checked against the simulator found in +reference 2. + .. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine) .. _Python: http://www.python.org -.. _Python Package Index: http://pypi.python.org/pypi/m209/ +.. _Python Package Index: http://pypi.python.org/pypi/purple/ .. _virtualenv: http://www.virtualenv.org/ .. _pip: http://www.pip-installer.org .. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/ .. _Mercurial: http://mercurial.selenic.com/ +.. _The PURPLE Machine: http://cryptocellar.web.cern.ch/cryptocellar/simula/purple/