Mercurial > public > purple

annotate README.txt @ 24:adddc0d7038a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Started working on a README.txt.
author Brian Neal <bgneal@gmail.com>
date Mon, 17 Feb 2014 20:28:57 -0600
parents
children
rev   line source
bgneal@24 1 ======
bgneal@24 2 Purple
bgneal@24 3 ======
bgneal@24 4
bgneal@24 5 A historically accurate PURPLE simulator written in Python 3
bgneal@24 6 ------------------------------------------------------------
bgneal@24 7
bgneal@24 8 :Author: Brian Neal <bgneal@gmail.com>
bgneal@24 9 :Version: 0.1
bgneal@24 10 :Date: February 17, 2013
bgneal@24 11 :Home Page: https://bitbucket.org/bgneal/purple/
bgneal@24 12 :License: MIT License (see LICENSE.txt)
bgneal@24 13 :Documentation: This file
bgneal@24 14 :Support: https://bitbucket.org/bgneal/purple/issues
bgneal@24 15
bgneal@24 16 ``Purple`` is a Python library and command-line utility for simulating the `PURPLE
bgneal@24 17 Machine`_, a cipher machine used by the Japanese Foreign Office before and
bgneal@24 18 during the Second World War. PURPLE was the code name given to machine by U.S.
bgneal@24 19 cryptanalysts. The Japanese called the machine 97-shiki ōbun inji-ki (System 97
bgneal@24 20 Printing Machine for European Characters), and Angōki B-kata (Type B Cipher
bgneal@24 21 Machine). The machine was used for secure diplomatic communications and was an
bgneal@24 22 electromechanical stepping-switch device.
bgneal@24 23
bgneal@24 24 This project is a Python 3 library and command-line utility for encrypting and
bgneal@24 25 decrypting text by simulating the operation of an actual PURPLE machine.
bgneal@24 26
bgneal@24 27
bgneal@24 28 Requirements
bgneal@24 29 ############
bgneal@24 30
bgneal@24 31 ``Purple`` was written in Python_ 3, specifically 3.3.2, and has no other external
bgneal@24 32 dependencies.
bgneal@24 33
bgneal@24 34
bgneal@24 35 Installation
bgneal@24 36 ############
bgneal@24 37
bgneal@24 38 ``Purple`` is available on the `Python Package Index`_ (PyPI). There are
bgneal@24 39 a number of ways to install to ``Purple``, detailed below. The author
bgneal@24 40 recommends you install into a virtualenv_. Setting up a virtualenv is not hard,
bgneal@24 41 but describing it is out of scope for this document. Please see the virtualenv_
bgneal@24 42 documentation for more information.
bgneal@24 43
bgneal@24 44 You can install it using pip_::
bgneal@24 45
bgneal@24 46 $ pip install purple # install
bgneal@24 47 $ pip install --upgrade purple # upgrade
bgneal@24 48
bgneal@24 49 You can also visit the the `Purple Bitbucket page`_ and download an archive
bgneal@24 50 file of the latest code. Alternatively, if you use Mercurial_, you can clone
bgneal@24 51 the repository with the following command::
bgneal@24 52
bgneal@24 53 $ hg clone https://bitbucket.org/bgneal/purple
bgneal@24 54
bgneal@24 55 If you did not use pip_ (you downloaded or cloned the code yourself), you can
bgneal@24 56 install with::
bgneal@24 57
bgneal@24 58 $ cd where-you-extracted-purple
bgneal@24 59 $ python setup.py install
bgneal@24 60
bgneal@24 61 To run the unit tests::
bgneal@24 62
bgneal@24 63 $ cd where-you-extracted-purple
bgneal@24 64 $ python -m unittest discover
bgneal@24 65
bgneal@24 66
bgneal@24 67 Command-line Usage
bgneal@24 68 ##################
bgneal@24 69
bgneal@24 70 To get help on the command-line ``Purple`` utility, execute the ``purple``
bgneal@24 71 command with the ``--help`` option::
bgneal@24 72
bgneal@24 73 $ purple --help
bgneal@24 74 usage: purple [-h] [-e] [-d] [-f] [-s SWITCHES] [-a ALPHABET] [-t TEXT]
bgneal@24 75 [-i FILE] [-g N] [-w N]
bgneal@24 76
bgneal@24 77 PURPLE cipher machine simulator
bgneal@24 78
bgneal@24 79 optional arguments:
bgneal@24 80 -h, --help show this help message and exit
bgneal@24 81 -e, --encrypt perform an encrypt operation
bgneal@24 82 -d, --decrypt perform a decrypt operation
bgneal@24 83 -f, --filter filter plaintext and provide useful substitutions
bgneal@24 84 -s SWITCHES, --switches SWITCHES
bgneal@24 85 switch settings, e.g. 9-1,24,6-23
bgneal@24 86 -a ALPHABET, --alphabet ALPHABET
bgneal@24 87 plugboard wiring string, 26-letters; e.g.
bgneal@24 88 AEIOUYBCDFGHJKLMNPQRSTVWXZ
bgneal@24 89 -t TEXT, --text TEXT input text to encrypt/decrypt
bgneal@24 90 -i FILE, --input FILE
bgneal@24 91 file to read input text from, - for stdin
bgneal@24 92 -g N, --group N if non-zero, group output in N-letter groups [default:
bgneal@24 93 5]
bgneal@24 94 -w N, --width N wrap output text to N letters; a value of 0 means do
bgneal@24 95 not wrap [default: 70]
bgneal@24 96
bgneal@24 97 Supply either -e or -d, but not both, to perform either an encrypt or decrypt.
bgneal@24 98 If the -s option is not supplied, the value of the environment variable
bgneal@24 99 PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of
bgneal@24 100 the environment variable PURPLE97_ALPHABET will be used. Input text is
bgneal@24 101 supplied either by the -t or by the -f options, but not both.
bgneal@24 102
bgneal@24 103 (TODO: Text goes here explaining the switches and alphabet settings)
bgneal@24 104
bgneal@24 105 If you are going to be working with the same initial switch settings and
bgneal@24 106 plugboard alphabet it may be more convenient to specify them as environment
bgneal@24 107 variables instead of repeatedly using the command-line arguments ``-s`` and
bgneal@24 108 ``-a``. The examples below assume these statements have been executed::
bgneal@24 109
bgneal@24 110 $ export PURPLE97_SWITCHES=9-1,24,6-23
bgneal@24 111 $ export PURPLE97_ALPHABET=NOKTYUXEQLHBRMPDICJASVWGZF
bgneal@24 112
bgneal@24 113 The ``purple`` command operates in two modes, either encrypt (specified with
bgneal@24 114 ``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can
bgneal@24 115 be specified on the command-line with the ``-t`` or ``--text`` option, or
bgneal@24 116 a read from a file (``-i`` or ``--input``).
bgneal@24 117
bgneal@24 118 When encrypting text, the ``purple`` machine only accepts the letters A-Z, but
bgneal@24 119 also allows for "garble" letters to be indicated by using the ``-`` (dash)
bgneal@24 120 character. This means all punctuation and spaces must be either be omitted or
bgneal@24 121 input via some other convention. The ``-f`` or ``--filter`` flag, when present,
bgneal@24 122 relaxes these restrictions a bit. When this flag is on, all lowercase letters
bgneal@24 123 will be converted to uppercase, digits will be converted to words (e.g.
bgneal@24 124 5 becomes FIVE), and all other characters will be ignored.
bgneal@24 125
bgneal@24 126 A simple encrypt example using the ``-f`` flag is given below::
bgneal@24 127
bgneal@24 128 $ purple -e -t "The PURPLE machine is now online" -f
bgneal@24 129 OGIVT SIAAH MWMHT VIBYY JUOJF UE
bgneal@24 130
bgneal@24 131 By default ``purple`` prints the output in 5-letter groups. This can be
bgneal@24 132 disabled or customized with the ``--group`` and ``--width`` options.
bgneal@24 133
bgneal@24 134 To decrypt this message::
bgneal@24 135
bgneal@24 136 $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE"
bgneal@24 137 THEPU RPLEM ACHIN EISNO WONLI NE
bgneal@24 138
bgneal@24 139 Note that spaces are ignored on input. Again the output is produced in 5-letter
bgneal@24 140 groups and wrapped at 70 letters per line. Here is the output again with
bgneal@24 141 grouping disabled::
bgneal@24 142
bgneal@24 143 $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0
bgneal@24 144 THEPURPLEMACHINEISNOWONLINE
bgneal@24 145
bgneal@24 146 Of course you can use file redirection to capture output in a file::
bgneal@24 147
bgneal@24 148 $ purple -e -t "The PURPLE machine is now online" -f > secret.txt
bgneal@24 149 $ purple -d -i secret.txt
bgneal@24 150 THEPU RPLEM ACHIN EISNO WONLI NE
bgneal@24 151
bgneal@24 152
bgneal@24 153 Library Usage
bgneal@24 154 #############
bgneal@24 155
bgneal@24 156
bgneal@24 157 Support
bgneal@24 158 #######
bgneal@24 159
bgneal@24 160
bgneal@24 161 References
bgneal@24 162 ##########
bgneal@24 163
bgneal@24 164
bgneal@24 165 .. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine)
bgneal@24 166 .. _Python: http://www.python.org
bgneal@24 167 .. _Python Package Index: http://pypi.python.org/pypi/m209/
bgneal@24 168 .. _virtualenv: http://www.virtualenv.org/
bgneal@24 169 .. _pip: http://www.pip-installer.org
bgneal@24 170 .. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/
bgneal@24 171 .. _Mercurial: http://mercurial.selenic.com/