Mercurial > public > m209
changeset 71:854c5d361011
Documentation cleanup.
author | Brian Neal <bgneal@gmail.com> |
---|---|
date | Tue, 23 Jul 2013 20:18:05 -0500 (2013-07-24) |
parents | 753974fc7619 |
children | 8028e409d728 |
files | docs/commandline.rst docs/exceptions.rst docs/index.rst docs/keylist.rst docs/procedure.rst docs/tutorial.rst m209/main.py |
diffstat | 7 files changed, 64 insertions(+), 56 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/commandline.rst Sun Jul 21 14:30:12 2013 -0500 +++ b/docs/commandline.rst Tue Jul 23 20:18:05 2013 -0500 @@ -4,7 +4,7 @@ Overview -------- -The ``m209`` command-line utility peforms three functions: +The ``m209`` command-line utility performs three functions: * Creates key list files * Encrypts text, either given on the command line or read from a file @@ -154,7 +154,7 @@ This option names the key list file. If not given, the default of ``m209keys.cfg`` is used. -``-t`` or ``--file`` +``-f`` or ``--file`` This option specifies the file that contains the text to encrypt. If the filename is given as ``-`` then input is read directly from ``stdin``. Note that either this option or the ``-t`` option must be specified, but not @@ -173,15 +173,16 @@ ``-e`` or ``--ext-ind`` This option specifies the six-letter external message indicator, which is an - encryption parameter as explained in the 1944 manual (see the references). - Each letter must exist on the key wheels from left to right. If this option - is omitted, an external message indicator is chosen at random. + encryption parameter as explained in the 1944 manual (see + :ref:`references-label` [5] & [7]). Each letter must exist on the key wheels + from left to right. If this option is omitted, an external message indicator + is chosen at random. ``-s`` or ``--sys-ind`` This option specifies the one-letter system indicator, which is an - encryption parameter as explained in the 1944 manual (see the references). - This must be a letter from ``A`` to ``Z``. If not given, one is chosen at - random. + encryption parameter as explained in the 1944 manual (see + :ref:`references-label` [5] & [7]). This must be a letter from ``A`` to ``Z``. + If not given, one is chosen at random. .. NOTE:: @@ -226,7 +227,7 @@ $ m209 decrypt --help usage: m209 decrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT] - Decyrpt text from a file or command-line + Decrypt text from a file or command-line optional arguments: -h, --help show this help message and exit
--- a/docs/exceptions.rst Sun Jul 21 14:30:12 2013 -0500 +++ b/docs/exceptions.rst Tue Jul 23 20:18:05 2013 -0500 @@ -11,13 +11,13 @@ .. class:: m209.drum.DrumError() - Inherits from :class:`~m209.M209Error`. This is an internal exception, used - to report drum related errors. + Inherits from :class:`~m209.M209Error`. This exception is used to report + drum related errors. .. class:: m209.key_wheel.KeyWheelError() - Inherits from :class:`~m209.M209Error`. This is an internal exception, used - to report key wheel related errors. + Inherits from :class:`~m209.M209Error`. This exception is used to report key + wheel related errors. .. class:: m209.keylist.generate.KeyListGenError()
--- a/docs/index.rst Sun Jul 21 14:30:12 2013 -0500 +++ b/docs/index.rst Tue Jul 23 20:18:05 2013 -0500 @@ -52,8 +52,10 @@ Requirements ------------ -``m209`` is written in Python_, specifically Python 3.3. It has no other -requirements or dependencies. +``m209`` is written in Python_ 3, specifically Python 3.3. At this time it will +not run on Python 2.x. + +``m209`` has no other requirements or dependencies. Installation ------------ @@ -65,8 +67,8 @@ $ pip install m209 # install $ pip install --upgrade m209 # upgrade -You may also download a tarball or .zip file of the latest code by visiting the -`m209 Bitbucket page`_. Alternatively if you use Mercurial_, you can clone the +You may also download an archive file of the latest code by visiting the `m209 +Bitbucket page`_. Alternatively if you use Mercurial_, you can clone the repository with the following command:: $ hg clone https://bitbucket.org/bgneal/m209 @@ -121,7 +123,6 @@ ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search`
--- a/docs/keylist.rst Sun Jul 21 14:30:12 2013 -0500 +++ b/docs/keylist.rst Tue Jul 23 20:18:05 2013 -0500 @@ -32,9 +32,9 @@ m & n are both non-zero, they cannot be equal. If a string has less than 27 pairs, it is assumed all remaining bars have both -lugs in the neutral (0) positions. +lugs in the neutral positions, i.e. ``0-0``. -Order of the pairs within the string does not matter. +The order of the pairs within the string does not matter. To reduce typing and to aid in readability, an alternate shortcut notation is supported:: @@ -112,6 +112,8 @@ ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects. +.. _key-list-file-format-label: + Key list file format ~~~~~~~~~~~~~~~~~~~~ @@ -144,9 +146,10 @@ ~~~~~~~~~~~~~~~~~~~~ The ``m209`` library contains a function to pseudo-randomly generate a key list -that is based on the procedure described in the 1944 M-209 manual. +that is based on the procedure described in the 1944 M-209 manual +(see :ref:`references-label` [4]). -.. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS]) +.. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None[, max_lug_attempts=MAX_LUG_ATTEMPTS[, max_pin_attempts=MAX_PIN_ATTEMPTS]]]) The only required parameter is ``indicator``, the two-letter indicator for the key list.
--- a/docs/procedure.rst Sun Jul 21 14:30:12 2013 -0500 +++ b/docs/procedure.rst Tue Jul 23 20:18:05 2013 -0500 @@ -4,7 +4,7 @@ The ``StdProcedure`` class encapsulates the encrypting and decrypting procedures outlined in :ref:`references-label`. In particular, see references [5] and [7]. This class takes care of the high level details of -inserted various message indicators into an encrypted message, and stripping +inserting various message indicators into an encrypted message, and stripping them off during decrypt. These message indicators tell the recipient what key list and initial key wheel settings to use when configuring their M-209 for decrypt.
--- a/docs/tutorial.rst Sun Jul 21 14:30:12 2013 -0500 +++ b/docs/tutorial.rst Tue Jul 23 20:18:05 2013 -0500 @@ -11,7 +11,7 @@ detailed the numerous wheel pin and lug settings that needed to be made for a given day. Because there are so many settings, the ``m209`` utility allows users to store key lists in a key file for convenience. So let us first create -a key file that hold 30 key lists:: +a key file that holds 30 key lists:: $ m209 keygen -n 30 @@ -38,17 +38,18 @@ .. NOTE:: If you are following along at home, you'll probably get different output than what is shown here. This is because the key lists are generated - at random, and it is very unlikely that your key list matches mine! + at random, and it is very unlikely that your key list will match mine! Here we can see that the first key list in our file has the indicator ``AB`` (shown in square brackets), and we can see the settings for the lugs and six -wheels. The notation is explained later. Also included is a so-called check -string. Because there are so many settings, it is quite error-prone to set up -an M-209. This check string allows the operator to verify their work. After -configuring the M-209 with the given settings, the operator can set the six key -wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message -that appears on the paper tape matches the check string, the operator knows the -machine is set up correctly for the day. +wheels. This notation is explained later (see :ref:`key-list-file-format-label`). +Also included is a so-called check string. Because there are so many settings, +it is quite error-prone to set up an M-209. This check string allows the +operator to verify their work. After configuring the M-209 with the given +settings, the operator can set the six key wheels to ``AAAAAA``, then encipher +the letter ``A`` 26 times. If the message that appears on the paper tape +matches the check string, the operator knows the machine is set up correctly +for the day. After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key lists. @@ -57,7 +58,7 @@ ``m209`` utility has many options to let you have fine control over the various encryption parameters. These are explained in detail later. If you omit these parameters they are simply chosen at random. Here is the simplest example of -encryping a message:: +encrypting a message:: $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP" IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB @@ -66,13 +67,14 @@ ``m209keys.cfg`` was used. Since we did not specify a key list indicator, one was chosen randomly from the key file. Other encryption parameters, explained later, were also randomly chosen. Next, the message given on the command-line -was encrypted using the standard US Army procedure described in the references. -This resulted in the encrypted message, which is displayed in 5-letter groups. -Notice that the first and last 2 groups are identical. These are special -indicators that tell the receiver how to decrypt the message. In particular -note that the last 2 letters in the second and last groups are ``MB``. This is -the key list indicator and tells the receiver what key list was used. The -remaining groups in the middle make up the encrypted message. +was encrypted using the standard US Army procedure described in +:ref:`references-label` (see [5] and [7]). This resulted in the encrypted +message, which is displayed in 5-letter groups. Notice that the first and last +2 groups are identical. These are special indicators that tell the receiver how +to decrypt the message. In particular note that the last 2 letters in the +second and last groups are ``MB``. This is the key list indicator and tells +the receiver what key list was used. The remaining groups in the middle make +up the encrypted message. Astute M-209 enthusiasts will note that our message included spaces. Actual M-209 units only allow the input of the letters ``A`` through ``Z``. Whenever @@ -98,9 +100,9 @@ an actual M-209 operates. Recall that an operator must substitute a letter ``Z`` whenever a space is needed. The M-209 helpfully replaces the letter ``Z`` in the decrypt output with a space as an aid to the operator. As a side effect, -legitimate uses of the letter ``Z`` are blanked out. But usually it is clear -from context what has happened, and the operator has to put them back into the -message before passing it up the chain of command. +legitimate uses of the letter ``Z`` are blanked out. Usually it is clear from +context what has happened, and the operator has to put the ``Z``'s back into +the message before passing it up the chain of command. It may also happen that the original message did not fit perfectly into an even number of 5-letter groups. In that case the encrypted message would be padded @@ -110,16 +112,16 @@ not exhibit this behavior. This is all you need to know to start creating your own M-209 messages! For -more details, consult the command-line ``m209`` documentation. +more details, consult the :doc:`commandline`. Library Tutorial ---------------- Here is one way to perform the encrypt and decrypt operations from the -command-line tutorial, above. In order to produce the same output, we explicity +command-line tutorial, above. In order to produce the same output, we explicitly specify the encryption parameters: the key list, the external message -indicator, and the system indicator. These parameters are explained in the -reference documentation. +indicator, and the system indicator. These parameters are explained in +:ref:`references-label` [5] & [7]. .. literalinclude:: ../examples/encrypt.py @@ -127,14 +129,15 @@ IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB -A decrypt is just a bit more complicated. After constructing a ``StdProcedure`` -object, you hand it the encrypted message to analyze. The procedure object -examines the groups in the message and extracts all the indicators. These are -returned as a ``DecryptParams`` named tuple which indicates, amongst other -things, what key list is required. It is then up to you to obtain this key list -somehow. Here we use the ``read_key_list()`` function to do so. After -installing the key list into the procedure object, you can finally call -``decrypt()``: +A decrypt is just a bit more complicated. After constructing +a :class:`~m209.procedure.StdProcedure` object, you hand it the encrypted +message to analyze. The procedure object examines the groups in the message and +extracts all the indicators. These are returned as a ``DecryptParams`` named +tuple which indicates, amongst other things, what key list is required. It is +then up to you to obtain this key list somehow. Here we use the +:func:`~m209.keylist.config.read_key_list` function to do so. After installing +the key list into the procedure object with :meth:`~.StdProcedure.set_key_list`, +you can finally call :meth:`~.StdProcedure.decrypt`: .. literalinclude:: ../examples/decrypt.py
--- a/m209/main.py Sun Jul 21 14:30:12 2013 -0500 +++ b/m209/main.py Tue Jul 23 20:18:05 2013 -0500 @@ -242,7 +242,7 @@ # create the sub-parser for decrypt dec_parser = subparsers.add_parser('decrypt', aliases=['dec'], - description='Decyrpt text from a file or command-line', + description='Decrypt text from a file or command-line', help='decrypt text from file or command-line', epilog='Either the -f/--file or -t/--text arguments must be supplied') dec_parser.add_argument('-z', '--key-file', default=DEFAULT_KEY_LIST,