Mercurial > public > m209

comparison docs/index.rst @ 56:21627ec5b1ad

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Restucture docs a bit. Create a separate tutorials document.
author Brian Neal <bgneal@gmail.com>
date Sat, 06 Jul 2013 16:27:47 -0500
parents 9341896b93f0
children 859dc6624ab7
comparison
equal deleted inserted replaced
55:9341896b93f0 56:21627ec5b1ad
28 and documentation. ``m209`` is a library for building applications for 28 and documentation. ``m209`` is a library for building applications for
29 encrypting and decrypting M-209 messages. ``m209`` also ships with a simple 29 encrypting and decrypting M-209 messages. ``m209`` also ships with a simple
30 command-line application that can encrypt & decrypt messages for scripting and 30 command-line application that can encrypt & decrypt messages for scripting and
31 experimentation. 31 experimentation.
32 32
33 Command-line Tutorial 33 Documentation
34 --------------------- 34 -------------
35 35
36 In order for two parties to exchange M-209 messages, each must set up their 36 Contents:
37 device in exactly the same manner. This was accomplished by publishing key
38 lists in code books which were distributed to end users. A code book instructed
39 users on what key list to use on any given day in a given month. Each key list
40 detailed the numerous wheel pin and lug settings that needed to be made for
41 a given day. Because there are so many settings, the ``m209`` utility allows
42 users to store key lists in a key file for convenience. So let us first create
43 a key file that hold 30 key lists::
44 37
45 $ m209 keygen -n 30 38 .. toctree::
46 39 tutorial
47 This command randomly creates 30 key lists and stores them in a file called 40 :maxdepth: 2
48 ``m209keys.cfg`` by default. We did not specify a starting key list indicator, so
49 30 random ones were chosen. The first 13 lines of our new key file are
50 displayed below::
51
52 $ head -n 13 m209keys.cfg
53 [AB]
54 lugs = 0-4*4 0-5*6 1-0*10 2-0*2 3-0 3-5*2 3-6 4-5
55 wheel1 = BDFGIKRSTUWX
56 wheel2 = BCEJKLORSUX
57 wheel3 = CFHJKLMQSTU
58 wheel4 = ABCDHIJMOPRTU
59 wheel5 = BCEFINPS
60 wheel6 = ACDEHJN
61 check = GZWUU SFYQN NFAKK FXSEN FAFMF B
62
63 [AK]
64 lugs = 0-4*2 0-5*9 0-6 1-0*3 1-2 1-5 1-6*2 3-0*8
65 wheel1 = ABDEFHIJMQSUXZ
66
67 .. NOTE::
68 If you are following along at home, you'll probably get different
69 output than what is shown here. This is because the key lists are generated
70 at random, and it is very unlikely that your key list matches mine!
71
72 Here we can see that the first key list in our file has the indicator ``AB``
73 (shown in square brackets), and we can see the settings for the lugs and six
74 wheels. The notation is explained later. Also included is a so-called check
75 string. Because there are so many settings, it is quite error-prone to set up
76 an M-209. This check string allows the operator to verify their work. After
77 configuring the M-209 with the given settings, the operator can set the six key
78 wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message
79 that appears on the paper tape matches the check string, the operator knows the
80 machine is set up correctly for the day.
81
82 After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key
83 lists.
84
85 Now that we have created a key file, we can encrypt our first message. The
86 ``m209`` utility has many options to let you have fine control over the various
87 encryption parameters. These are explained in detail later. If you omit these
88 parameters they are simply chosen at random. Here is the simplest example of
89 encryping a message::
90
91 $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP"
92 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
93
94 What just happened here? Since we did not specify a key file, the default
95 ``m209keys.cfg`` was used. Since we did not specify a key list indicator, one
96 was chosen randomly from the key file. Other encryption parameters, explained
97 later, were also randomly chosen. Next, the message given on the command-line
98 was encrypted using the standard US Army procedure described in the references.
99 This resulted in the encrypted message, which is displayed in 5-letter groups.
100 Notice that the first and last 2 groups are identical. These are special
101 indicators that tell the receiver how to decrypt the message. In particular
102 note that the last 2 letters in the second and last groups are ``MB``. This is
103 the key list indicator and tells the receiver what key list was used. The
104 remaining groups in the middle make up the encrypted message.
105
106 Astute M-209 enthusiasts will note that our message included spaces. Actual
107 M-209 units only allow the input of the letters ``A`` through ``Z``. Whenever
108 a space was needed, the operator inserted the letter ``Z``. The ``m209``
109 utility automatically performs this substitution for convenience.
110
111 Let's suppose our message was then sent to our recipient, either by courier,
112 Morse code over radio, or in the modern age, email or even Twitter. In order
113 for our receiver to decrypt our message they must also have the identical key
114 list named ``MB``. We will assume for now that our key file, ``m209keys.cfg``
115 was sent to our receiver earlier in some secure manner. The receiver then
116 issues this command::
117
118 $ m209 decrypt -t "IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB"
119 THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP
120
121 Here again, since no key file was explicitly specified, the file
122 ``m209keys.cfg`` was used. The file was searched for the key list ``MB``. Then
123 the standard Army procedure was followed, making use of the indicator groups to
124 decrypt the message, which is displayed as output.
125
126 But wait, what happened to our Pizza? Why are the ``Z``'s missing? This is how
127 an actual M-209 operates. Recall that an operator must substitute a letter
128 ``Z`` whenever a space is needed. The M-209 helpfully replaces the letter ``Z``
129 in the decrypt output with a space as an aid to the operator. As a side effect,
130 legitimate uses of the letter ``Z`` are blanked out. But usually it is clear
131 from context what has happened, and the operator has to put them back into the
132 message before passing it up the chain of command.
133
134 It may also happen that the original message did not fit perfectly into an even
135 number of 5-letter groups. In that case the encrypted message would be padded
136 with ``X`` characters according to procedure. Upon decrypt, these ``X``
137 characters would appear as garbage characters on the end of the message. The
138 receiving operator would simply ignore these letters. Note that our message did
139 not exhibit this behavior.
140
141 This is all you need to know to start creating your own M-209 messages! For
142 more details, consult the command-line ``m209`` documentation.
143
144 Library Tutorial
145 ----------------
146
147 Here is one way to perform the encrypt and decrypt operations from the
148 command-line tutorial, above. In order to produce the same output, we explicity
149 specify the encryption parameters: the key list, the external message
150 indicator, and the system indicator. These parameters are explained in the
151 reference documentation.
152
153 .. literalinclude:: ../examples/encrypt.py
154
155 This program outputs::
156
157 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
158
159 A decrypt is just a bit more complicated. After constructing a ``StdProcedure``
160 object, you hand it the encrypted message to analyze. The procedure object
161 examines the groups in the message and extracts all the indicators. These are
162 returned as a ``DecryptParams`` named tuple which indicates, amongst other
163 things, what key list is required. It is then up to you to obtain this key list
164 somehow. Here we use the ``read_key_list()`` function to do so. After
165 installing the key list into the procedure object, you can finally call
166 ``decrypt()``:
167
168 .. literalinclude:: ../examples/decrypt.py
169
170 This program prints::
171
172 THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP
173 41
174 42
175 Requirements 43 Requirements
176 ------------ 44 ------------
177 45
178 ``m209`` is written in Python_, specifically Python 3.3. It has no other 46 ``m209`` is written in Python_, specifically Python 3.3. It has no other
179 requirements or dependencies. 47 requirements or dependencies.
180
181 48
182 Installation 49 Installation
183 ------------ 50 ------------
184 51
185 ``m209`` is available on the `Python Package Index`_ (PyPI). You can install it 52 ``m209`` is available on the `Python Package Index`_ (PyPI). You can install it
196 63
197 If you did not use pip, you can install with this command:: 64 If you did not use pip, you can install with this command::
198 65
199 $ python setup.py install 66 $ python setup.py install
200 67
201
202 Support & Source 68 Support & Source
203 ---------------- 69 ----------------
204 70
205 All support takes place at the `m209 Bitbucket page`_. Please enter any 71 All support takes place at the `m209 Bitbucket page`_. Please enter any
206 feature requests or bugs into the `issue tracker`_. 72 feature requests or bugs into the `issue tracker`_.
207
208 Next Steps
209 ----------
210
211 Contents:
212
213 .. toctree::
214 :maxdepth: 2
215
216
217 73
218 Indices and tables 74 Indices and tables
219 ================== 75 ==================
220 76
221 * :ref:`genindex` 77 * :ref:`genindex`