bgneal@24: ====== bgneal@24: Purple bgneal@24: ====== bgneal@24: bgneal@24: A historically accurate PURPLE simulator written in Python 3 bgneal@24: ------------------------------------------------------------ bgneal@24: bgneal@24: :Author: Brian Neal bgneal@24: :Version: 0.1 bgneal@24: :Date: February 17, 2013 bgneal@24: :Home Page: https://bitbucket.org/bgneal/purple/ bgneal@24: :License: MIT License (see LICENSE.txt) bgneal@24: :Documentation: This file bgneal@24: :Support: https://bitbucket.org/bgneal/purple/issues bgneal@24: bgneal@24: ``Purple`` is a Python library and command-line utility for simulating the `PURPLE bgneal@24: Machine`_, a cipher machine used by the Japanese Foreign Office before and bgneal@24: during the Second World War. PURPLE was the code name given to machine by U.S. bgneal@24: cryptanalysts. The Japanese called the machine 97-shiki ōbun inji-ki (System 97 bgneal@24: Printing Machine for European Characters), and Angōki B-kata (Type B Cipher bgneal@24: Machine). The machine was used for secure diplomatic communications and was an bgneal@24: electromechanical stepping-switch device. bgneal@24: bgneal@24: This project is a Python 3 library and command-line utility for encrypting and bgneal@24: decrypting text by simulating the operation of an actual PURPLE machine. bgneal@24: bgneal@24: bgneal@24: Requirements bgneal@24: ############ bgneal@24: bgneal@24: ``Purple`` was written in Python_ 3, specifically 3.3.2, and has no other external bgneal@24: dependencies. bgneal@24: bgneal@24: bgneal@24: Installation bgneal@24: ############ bgneal@24: bgneal@24: ``Purple`` is available on the `Python Package Index`_ (PyPI). There are bgneal@24: a number of ways to install to ``Purple``, detailed below. The author bgneal@24: recommends you install into a virtualenv_. Setting up a virtualenv is not hard, bgneal@24: but describing it is out of scope for this document. Please see the virtualenv_ bgneal@24: documentation for more information. bgneal@24: bgneal@24: You can install it using pip_:: bgneal@24: bgneal@24: $ pip install purple # install bgneal@24: $ pip install --upgrade purple # upgrade bgneal@24: bgneal@24: You can also visit the the `Purple Bitbucket page`_ and download an archive bgneal@24: file of the latest code. Alternatively, if you use Mercurial_, you can clone bgneal@24: the repository with the following command:: bgneal@24: bgneal@24: $ hg clone https://bitbucket.org/bgneal/purple bgneal@24: bgneal@24: If you did not use pip_ (you downloaded or cloned the code yourself), you can bgneal@24: install with:: bgneal@24: bgneal@24: $ cd where-you-extracted-purple bgneal@24: $ python setup.py install bgneal@24: bgneal@24: To run the unit tests:: bgneal@24: bgneal@24: $ cd where-you-extracted-purple bgneal@24: $ python -m unittest discover bgneal@24: bgneal@24: bgneal@24: Command-line Usage bgneal@24: ################## bgneal@24: bgneal@24: To get help on the command-line ``Purple`` utility, execute the ``purple`` bgneal@24: command with the ``--help`` option:: bgneal@24: bgneal@24: $ purple --help bgneal@24: usage: purple [-h] [-e] [-d] [-f] [-s SWITCHES] [-a ALPHABET] [-t TEXT] bgneal@24: [-i FILE] [-g N] [-w N] bgneal@24: bgneal@24: PURPLE cipher machine simulator bgneal@24: bgneal@24: optional arguments: bgneal@24: -h, --help show this help message and exit bgneal@24: -e, --encrypt perform an encrypt operation bgneal@24: -d, --decrypt perform a decrypt operation bgneal@24: -f, --filter filter plaintext and provide useful substitutions bgneal@24: -s SWITCHES, --switches SWITCHES bgneal@24: switch settings, e.g. 9-1,24,6-23 bgneal@24: -a ALPHABET, --alphabet ALPHABET bgneal@24: plugboard wiring string, 26-letters; e.g. bgneal@24: AEIOUYBCDFGHJKLMNPQRSTVWXZ bgneal@24: -t TEXT, --text TEXT input text to encrypt/decrypt bgneal@24: -i FILE, --input FILE bgneal@24: file to read input text from, - for stdin bgneal@24: -g N, --group N if non-zero, group output in N-letter groups [default: bgneal@24: 5] bgneal@24: -w N, --width N wrap output text to N letters; a value of 0 means do bgneal@24: not wrap [default: 70] bgneal@24: bgneal@24: Supply either -e or -d, but not both, to perform either an encrypt or decrypt. bgneal@24: If the -s option is not supplied, the value of the environment variable bgneal@24: PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of bgneal@24: the environment variable PURPLE97_ALPHABET will be used. Input text is bgneal@24: supplied either by the -t or by the -f options, but not both. bgneal@24: bgneal@24: (TODO: Text goes here explaining the switches and alphabet settings) bgneal@24: bgneal@24: If you are going to be working with the same initial switch settings and bgneal@24: plugboard alphabet it may be more convenient to specify them as environment bgneal@24: variables instead of repeatedly using the command-line arguments ``-s`` and bgneal@24: ``-a``. The examples below assume these statements have been executed:: bgneal@24: bgneal@24: $ export PURPLE97_SWITCHES=9-1,24,6-23 bgneal@24: $ export PURPLE97_ALPHABET=NOKTYUXEQLHBRMPDICJASVWGZF bgneal@24: bgneal@24: The ``purple`` command operates in two modes, either encrypt (specified with bgneal@24: ``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can bgneal@24: be specified on the command-line with the ``-t`` or ``--text`` option, or bgneal@24: a read from a file (``-i`` or ``--input``). bgneal@24: bgneal@24: When encrypting text, the ``purple`` machine only accepts the letters A-Z, but bgneal@24: also allows for "garble" letters to be indicated by using the ``-`` (dash) bgneal@24: character. This means all punctuation and spaces must be either be omitted or bgneal@24: input via some other convention. The ``-f`` or ``--filter`` flag, when present, bgneal@24: relaxes these restrictions a bit. When this flag is on, all lowercase letters bgneal@24: will be converted to uppercase, digits will be converted to words (e.g. bgneal@24: 5 becomes FIVE), and all other characters will be ignored. bgneal@24: bgneal@24: A simple encrypt example using the ``-f`` flag is given below:: bgneal@24: bgneal@24: $ purple -e -t "The PURPLE machine is now online" -f bgneal@24: OGIVT SIAAH MWMHT VIBYY JUOJF UE bgneal@24: bgneal@24: By default ``purple`` prints the output in 5-letter groups. This can be bgneal@24: disabled or customized with the ``--group`` and ``--width`` options. bgneal@24: bgneal@24: To decrypt this message:: bgneal@24: bgneal@24: $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" bgneal@24: THEPU RPLEM ACHIN EISNO WONLI NE bgneal@24: bgneal@24: Note that spaces are ignored on input. Again the output is produced in 5-letter bgneal@24: groups and wrapped at 70 letters per line. Here is the output again with bgneal@24: grouping disabled:: bgneal@24: bgneal@24: $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0 bgneal@24: THEPURPLEMACHINEISNOWONLINE bgneal@24: bgneal@24: Of course you can use file redirection to capture output in a file:: bgneal@24: bgneal@24: $ purple -e -t "The PURPLE machine is now online" -f > secret.txt bgneal@24: $ purple -d -i secret.txt bgneal@24: THEPU RPLEM ACHIN EISNO WONLI NE bgneal@24: bgneal@24: bgneal@24: Library Usage bgneal@24: ############# bgneal@24: bgneal@24: bgneal@24: Support bgneal@24: ####### bgneal@24: bgneal@24: bgneal@24: References bgneal@24: ########## bgneal@24: bgneal@24: bgneal@24: .. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine) bgneal@24: .. _Python: http://www.python.org bgneal@24: .. _Python Package Index: http://pypi.python.org/pypi/m209/ bgneal@24: .. _virtualenv: http://www.virtualenv.org/ bgneal@24: .. _pip: http://www.pip-installer.org bgneal@24: .. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/ bgneal@24: .. _Mercurial: http://mercurial.selenic.com/