Mercurial > public > m209
changeset 59:6acd17898381
Added docs for the encrypt command. Added examples.
| author | Brian Neal <bgneal@gmail.com> |
|---|---|
| date | Wed, 10 Jul 2013 21:33:03 -0500 |
| parents | 902f14d7e032 |
| children | 0a3e4bc49118 |
| files | docs/commandline.rst docs/index.rst |
| diffstat | 2 files changed, 136 insertions(+), 21 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/commandline.rst Tue Jul 09 21:34:48 2013 -0500 +++ b/docs/commandline.rst Wed Jul 10 21:33:03 2013 -0500 @@ -38,7 +38,7 @@ Each sub-command has an alias for those who prefer shorter commands. -Keygen Sub-command +Keygen sub-command ------------------ ``keygen``, or ``key`` for short, is the sub-command that pseudo-randomly @@ -65,28 +65,32 @@ The options for ``keygen`` are described below. -The ``-z`` or ``--key-file`` option names the key list file. If not supplied, -this defaults to ``m209keys.cfg``. Note that the other sub-commands also have -this option, and they too use the same default value. +``-z`` or ``--key-file`` + This option names the key list file. If not supplied, this defaults to + ``m209keys.cfg``. Note that the other sub-commands also have this option, + and they too use the same default value. -The ``-o`` or ``--overwrite`` switch must be present if the key list file -already exists. It provides confirmation that the user wants to overwrite an -existing file. If the key list file already exists, and this option is not -supplied, this sub-command will exit with an error message and the original key -list file will be unchanged. +``-o`` or ``--overwrite`` + This switch must be present if the key list file already exists. It provides + confirmation that the user wants to overwrite an existing file. If the key + list file already exists, and this option is not supplied, this sub-command + will exit with an error message and the original key list file will be + unchanged. -The ``-s`` or ``--start`` option sets the starting indicator for the key list -file. Key list indicators are two letters in the range ``AA`` to ``ZZ``. For -example, ``keygen`` can be told to create 3 key lists, starting with indicator -``AA``. In this case the key lists ``AA``, ``AB``, and ``AC`` would be written -to the file. If this parameter is omitted, ``keygen`` picks indicators at -random. Key list indicators simply name the key list, and are placed in the -leading and trailing groups of encrypted messages to tell the receiver which -key list was used to create the message. Both sender and receiver must have the -same key list (name and contents) to communicate. +``-s`` or ``--start`` + This option sets the starting indicator for the key list file. Key list + indicators are two letters in the range ``AA`` to ``ZZ``. For example, + ``keygen`` can be told to create 3 key lists, starting with indicator + ``AA``. In this case the key lists ``AA``, ``AB``, and ``AC`` would be + written to the file. If this parameter is omitted, ``keygen`` picks + indicators at random. Key list indicators simply name the key list, and are + placed in the leading and trailing groups of encrypted messages to tell the + receiver which key list was used to create the message. Both sender and + receiver must have the same key list (name and contents) to communicate. -The ``-n`` or ``--number`` option specifies the number of key lists to -generate. The default value is 1. +``-n`` or ``--number`` + This option specifies the number of key lists to generate. The default value + is 1. .. NOTE:: @@ -99,3 +103,114 @@ If this happens an error message will be displayed and no key list file will be created. It is suggested to simply run the command again as it is not likely to happen twice in a row. + +Keygen examples ++++++++++++++++ + +To generate 30 key lists in the default key list file (``m209keys.cfg``) with +random indicators, and overwriting the key list file if it exists:: + + $ m209 keygen -o -n 30 + $ m209 key --overwrite --number=30 + +To generate 5 key lists that sequentially start with the indicator ``BN`` in +the key list file ``m209/keys/november/keys.cfg``:: + + $ m209 keygen -z m209/keys/november/keys.cfg -s BN -n 5 + + +Encrypt sub-command +------------------- + +``encrypt``, or ``enc``, is the sub-command used to encrypt text. To get help +on the ``encrypt`` command, type the following:: + + $ m209 encrypt -h + usage: m209 encrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT] [-k XX] [-e ABCDEF] + [-s S] + + Encrypt text from a file or command-line + + optional arguments: + -h, --help show this help message and exit + -z KEY_FILE, --key-file KEY_FILE + path to key list file [default: m209keys.cfg] + -f FILE, --file FILE path to plaintext file or - for stdin + -t TEXT, --text TEXT text string to encrypt + -k XX, --key-list-ind XX + 2-letter key list indicator; if omitted a random one + is used + -e ABCDEF, --ext-ind ABCDEF + 6-letter external message indicator; if omitted a + random one is used + -s S, --sys-ind S 1-letter system indicator; if omitted a random one is + used + + Either the -f/--file or -t/--text arguments must be supplied + +The options to the ``encrypt`` command are described below. + +``-z`` or ``--key-file`` + This option names the key list file. If not given, the default of + ``m209keys.cfg`` is used. + +``-t`` 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 + both. + +``-t`` or ``--text`` + This option specifies the text to encrypt on the command-line. Depending + upon your system, you'll probably have to quote or escape your text. Note + that you must either specify this option or the ``-f`` option, but not both. + +``-k`` or ``--key-list-ind`` + This option specifies the two-letter key list indicator to use. Valid values + range from ``AA`` to ``ZZ``. The key list with this indicator must be in the + key list file given by the ``-z`` option. If this option is omitted, a key + list from the key list file is chosen at random. + +``-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. + +``-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. + +.. NOTE:: + + An actual M-209 can only accept the letters ``A-Z``. When using an actual + M-209, space characters must be input as the letter ``Z``. Numbers must + typically be spelled out as words or some other agreed-upon convention. + Likewise with punctuation. To make encryption more convenient, the ``m209`` + program will accept spaces and automatically convert them to the letter + ``Z``. Lowercase letters will automatically be converted to uppercase. All + other characters will produce an error. This applies to both text read on + the command-line with the ``-t`` option and text read from files (``-f``). + +Encrypt examples +++++++++++++++++ + +To encrypt a simple string on the command-line using the default key file and +random encryption parameters:: + + $ m209 encrypt -t "Rendezvous at zero seven thirty" + +To save the encrypted text to a file:: + + $ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt + +To read the contents of a file and encrypt it, saving it to a new file:: + + $ m209 enc -f message.txt > secret.txt + +To explicitly specify encryption parameters, and read text from ``stdin``:: + + $ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A +
--- a/docs/index.rst Tue Jul 09 21:34:48 2013 -0500 +++ b/docs/index.rst Wed Jul 10 21:33:03 2013 -0500 @@ -90,7 +90,7 @@ #. `M-209 at Wikipedia <http://en.wikipedia.org/wiki/M-209>`_ #. `Mark J. Blair's Converter M-209-B <http://www.nf6x.net/2009/02/converter-m-209-b/>`_ #. `1942 M-209 Manual <http://maritime.org/tech/csp1500inst.htm>`_ -#. `1944 M-209 Manual scan <http://www.ilord.com/m209manual.html>`_ +#. `1944 M-209 Manual <http://www.ilord.com/m209manual.html>`_ #. `Official M-209 Training Film <http://www.youtube.com/playlist?list=PLCPgncK_sTnEny2-uoTV-1_GC72zo-vKq>`_ - This is a 4 video YouTube playlist of an actual 1940's era US War Department training film. Demonstrates the M-209 and operational procedures. Very interesting! #. `Transcript of Training Film <http://www.ilord.com/m209-training.html>`_ - Transcript of the above film.