Mercurial > public > purple

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