Package: purple
Author:Brian Neal <bgneal@gmail.com>Version:0.1Date:February 17, 2013Home Page:https://bitbucket.org/bgneal/purple/License:MIT License (see LICENSE.txt)Documentation:This fileSupport:https://bitbucket.org/bgneal/purple/issuesPurpleis a Python library and command-line utility for simulating thePURPLE 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 machine97-shiki ōbun inji-ki(System 97 Printing Machine for European Characters), andAngō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 thePurplecipher 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.RequirementsPurplewas written inPython3, specifically 3.3.2, and has no other external
dependencies.InstallationPurpleis available on thePython Package Index(PyPI). There are
a number of ways to install toPurple, detailed below. The author
recommends you install into avirtualenv. Setting up a virtualenv is not hard,
but describing it is out of scope for this document. Please see thevirtualenvdocumentation for more information.You can install it usingpip:$ pip install purple                # install
$ pip install --upgrade purple      # upgradeYou can also visit the thePurple Bitbucket pageand download an archive
file of the latest code. Alternatively, if you useMercurial, you can clone
the repository with the following command:$ hg clone https://bitbucket.org/bgneal/purpleIf you did not usepip(you downloaded or cloned the code yourself), you can
install with:$ cd where-you-extracted-purple
$ python setup.py installTo run the unit tests:$ cd where-you-extracted-purple
$ python -m unittest discoverInitial Settings SyntaxIn order to exchange messages, each message recipient must use the same initial
machine settings. For thePurplemachine, 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.ThePurplesimulation 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-23Here 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:AEIOUYBCDFGHJKLMNPQRSTVWXZFor the alphabet setting to be valid, do not insert spaces, and ensure all 26
letters are used exactly once.Command-line UsageTo get help on the command-linePurpleutility, execute thepurplecommand with the--helpoption:$ purple --help
usage: purple [-h] [-e] [-d] [-f] [-s SWITCHES] [-a ALPHABET] [-t TEXT]
              [-i FILE] [-g N] [-w N]

PURPLE cipher machine simulator

optional arguments:
  -h, --help            show this help message and exit
  -e, --encrypt         perform an encrypt operation
  -d, --decrypt         perform a decrypt operation
  -f, --filter          filter plaintext and provide useful substitutions
  -s SWITCHES, --switches SWITCHES
                        switch settings, e.g. 9-1,24,6-23
  -a ALPHABET, --alphabet ALPHABET
                        plugboard wiring string, 26-letters; e.g.
                        AEIOUYBCDFGHJKLMNPQRSTVWXZ
  -t TEXT, --text TEXT  input text to encrypt/decrypt
  -i FILE, --input FILE
                        file to read input text from, - for stdin
  -g N, --group N       if non-zero, group output in N-letter groups [default:
                        5]
  -w N, --width N       wrap output text to N letters; a value of 0 means do
                        not wrap [default: 70]

Supply either -e or -d, but not both, to perform either an encrypt or decrypt.
If the -s option is not supplied, the value of the environment variable
PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of
the environment variable PURPLE97_ALPHABET will be used. Input text is
supplied either by the -t or by the -f options, but not both.Thepurplecommand operates in two modes, either encrypt (specified with-eor--encrypt) or decrypt (-dor--decrypt). Input text can
be specified on the command-line with the-tor--textoption, or
a read from a file (-ior--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 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=NOKTYUXEQLHBRMPDICJASVWGZFIf you do not specify initial settings, thepurplemachine will attempt to
read them from these two environment variables. Failing that,purplewill
use the following initial settings:default switch settings: 1-1,1,1-12default alphabet: AEIOUYBCDFGHJKLMNPQRSTVWXZWhen encrypting text, thepurplemachine only accepts the letters A-Z, but
also allows for “garble” letters to be indicated by using the-(dash)
character. This means all punctuation and spaces must be either be omitted or
input via some other convention. The-for--filterflag, when present,
relaxes these restrictions a bit. When this flag is on, all lowercase letters
will be converted to uppercase, digits will be converted to words (e.g.
5 becomes FIVE), and all other characters will be ignored.A simple encrypt example using the-fflag is given below:$ purple --encrypt -t "The PURPLE machine is now online" -f
OGIVT SIAAH MWMHT VIBYY JUOJF UEBy defaultpurpleprints the output in 5-letter groups. This can be
disabled or customized with the--groupand--widthoptions.To decrypt this message:$ purple --decrypt -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE"
THEPU RPLEM ACHIN EISNO WONLI NENote that spaces are ignored on input. Again the output is produced in 5-letter
groups and wrapped at 70 letters per line. Here is the output again with
grouping disabled:$ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0
THEPURPLEMACHINEISNOWONLINEYou 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
THEPU RPLEM ACHIN EISNO WONLI NELibrary UsageTo usePurplefrom within Python code you must first construct
aPurple97object, 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)Theswitches_posargument, when notNone, 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.
IfNonethen switch positions of all zeroes is assumed.Thefast_switchargument indicates which twenties switch (numbered 1-3) is
the fast switch. Likewise,middle_switchindicates which switch is the
middle switch. The slow switch is inferred. It is an error to give thefast_switchandmiddle_switcharguments the same value.Thealphabetargument is the plugboard alphabet mapping. It is expected to
be a 26-letter uppercase string. IfNone, a mapping ofAEIOUYBCDFGHJKLMNPQRSTVWXZis 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)Hereswitchesis a string in the syntax described above, e.g.'9-1,24,6-23'.Thealphabetargument is as described in the first constructor.Once constructed, you can use thePurple97object 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.SupportTo report a bug or suggest a feature, please use the issue tracker at thePurple Bitbucket page. You can also email the author using the address at
the top of this file.ReferencesPURPLE 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 MachineWikipedia Article:PURPLE MachineThe paper in reference 1 is also available here:http://cryptocellar.web.cern.ch/cryptocellar/pubs/PurpleRevealed.pdfThis 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.ThePurplesimulator’s operation was checked against the simulator found in
reference 2.