bgneal@57: Command-line Reference
bgneal@57: ======================
bgneal@58: 
bgneal@58: Overview
bgneal@58: --------
bgneal@58: 
bgneal@58: The ``m209`` command-line utility peforms three functions:
bgneal@58: 
bgneal@58: * Creates key list files
bgneal@58: * Encrypts text, either given on the command line or read from a file
bgneal@58: * Decrypts text, either given on the command line or read from a file
bgneal@58:  
bgneal@58: These functions are implemented as sub-commands. To see the list of
bgneal@58: sub-commands and options common to all sub-commands, use the ``-h`` or
bgneal@58: ``--help`` option::
bgneal@58: 
bgneal@58:    $ m209 --help
bgneal@58:    usage: m209 [-h] [-l {debug,info,warning,error,critical}]
bgneal@58:                {encrypt,enc,decrypt,dec,keygen,key} ...
bgneal@58: 
bgneal@58:    M-209 simulator and utility program
bgneal@58: 
bgneal@58:    optional arguments:
bgneal@58:      -h, --help            show this help message and exit
bgneal@58:      -l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
bgneal@58:                            set log level [default: warning]
bgneal@58: 
bgneal@58:    list of commands:
bgneal@58:      type m209 {command} -h for help on {command}
bgneal@58: 
bgneal@58:      {encrypt,enc,decrypt,dec,keygen,key}
bgneal@58:        encrypt (enc)       encrypt text from file or command-line
bgneal@58:        decrypt (dec)       decrypt text from file or command-line
bgneal@58:        keygen (key)        generate key list
bgneal@58: 
bgneal@58: The ``-l`` / ``--log`` options control the verbosity of output. Currently only
bgneal@58: the ``keygen`` sub-command makes use of this option.
bgneal@58: 
bgneal@58: Each sub-command has an alias for those who prefer shorter commands.
bgneal@58: 
bgneal@59: Keygen sub-command
bgneal@58: ------------------
bgneal@58: 
bgneal@58: ``keygen``, or ``key`` for short, is the sub-command that pseudo-randomly
bgneal@58: creates key list files for use by the ``encrypt`` and ``decrypt`` sub-commands,
bgneal@58: as well as by the ``m209`` library routines. 
bgneal@58: 
bgneal@58: Help on the ``keygen`` sub-command can be obtained with the following
bgneal@58: invocation::
bgneal@58: 
bgneal@58:    $ m209 keygen --help
bgneal@58:    usage: m209 keygen [-h] [-z KEY_FILE] [-o] [-s XX] [-n NUMBER]
bgneal@58: 
bgneal@58:    Generate key list file
bgneal@58: 
bgneal@58:    optional arguments:
bgneal@58:      -h, --help            show this help message and exit
bgneal@58:      -z KEY_FILE, --key-file KEY_FILE
bgneal@58:                            path to key list file [default: m209keys.cfg]
bgneal@58:      -o, --overwrite       overwrite key list file if it exists
bgneal@58:      -s XX, --start XX     starting indicator; if omitted, random indicators are
bgneal@58:                            used
bgneal@58:      -n NUMBER, --number NUMBER
bgneal@58:                            number of key lists to generate [default: 1]
bgneal@58: 
bgneal@58: The options for ``keygen`` are described below.
bgneal@58: 
bgneal@59: ``-z`` or ``--key-file``
bgneal@59:    This option names the key list file. If not supplied, this defaults to
bgneal@59:    ``m209keys.cfg``. Note that the other sub-commands also have this option,
bgneal@59:    and they too use the same default value.
bgneal@58: 
bgneal@59: ``-o`` or ``--overwrite``
bgneal@59:    This switch must be present if the key list file already exists. It provides
bgneal@59:    confirmation that the user wants to overwrite an existing file. If the key
bgneal@59:    list file already exists, and this option is not supplied, this sub-command
bgneal@59:    will exit with an error message and the original key list file will be
bgneal@59:    unchanged.
bgneal@58: 
bgneal@59: ``-s`` or ``--start``
bgneal@59:    This option sets the starting indicator for the key list file. Key list
bgneal@59:    indicators are two letters in the range ``AA`` to ``ZZ``. For example,
bgneal@59:    ``keygen`` can be told to create 3 key lists, starting with indicator
bgneal@59:    ``AA``.  In this case the key lists ``AA``, ``AB``, and ``AC`` would be
bgneal@59:    written to the file. If this parameter is omitted, ``keygen`` picks
bgneal@59:    indicators at random. Key list indicators simply name the key list, and are
bgneal@59:    placed in the leading and trailing groups of encrypted messages to tell the
bgneal@59:    receiver which key list was used to create the message. Both sender and
bgneal@59:    receiver must have the same key list (name and contents) to communicate.
bgneal@58: 
bgneal@59: ``-n`` or ``--number``
bgneal@59:    This option specifies the number of key lists to generate. The default value
bgneal@59:    is 1.
bgneal@58: 
bgneal@58: .. NOTE:: 
bgneal@58: 
bgneal@58:    The algorithm the ``keygen`` sub-command uses to generate key lists is based
bgneal@58:    on the actual US Army procedure taken from the 1944 manual. This procedure
bgneal@58:    is somewhat loosely specified and a lot is left up to the soldier creating
bgneal@58:    the key list. The ``keygen`` algorithm is ad-hoc and uses simple heuristics
bgneal@58:    and random numbers to make decisions.  Occasionally this algorithm may fail
bgneal@58:    to generate a key list that meets the final criteria defined in the manual.
bgneal@58:    If this happens an error message will be displayed and no key list file will
bgneal@58:    be created. It is suggested to simply run the command again as it is not
bgneal@58:    likely to happen twice in a row.
bgneal@59: 
bgneal@59: Keygen examples
bgneal@59: +++++++++++++++
bgneal@59: 
bgneal@59: To generate 30 key lists in the default key list file (``m209keys.cfg``) with
bgneal@59: random indicators, and overwriting the key list file if it exists::
bgneal@59: 
bgneal@59:    $ m209 keygen -o -n 30
bgneal@59:    $ m209 key --overwrite --number=30
bgneal@59: 
bgneal@59: To generate 5 key lists that sequentially start with the indicator ``BN`` in
bgneal@59: the key list file ``m209/keys/november/keys.cfg``::
bgneal@59: 
bgneal@59:    $ m209 keygen -z m209/keys/november/keys.cfg -s BN -n 5
bgneal@59: 
bgneal@59: 
bgneal@59: Encrypt sub-command
bgneal@59: -------------------
bgneal@59: 
bgneal@59: ``encrypt``, or ``enc``, is the sub-command used to encrypt text. To get help
bgneal@59: on the ``encrypt`` command, type the following::
bgneal@59: 
bgneal@59:    $ m209 encrypt -h
bgneal@59:    usage: m209 encrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT] [-k XX] [-e ABCDEF]
bgneal@59:                        [-s S]
bgneal@59: 
bgneal@59:    Encrypt text from a file or command-line
bgneal@59: 
bgneal@59:    optional arguments:
bgneal@59:      -h, --help            show this help message and exit
bgneal@59:      -z KEY_FILE, --key-file KEY_FILE
bgneal@59:                            path to key list file [default: m209keys.cfg]
bgneal@59:      -f FILE, --file FILE  path to plaintext file or - for stdin
bgneal@59:      -t TEXT, --text TEXT  text string to encrypt
bgneal@59:      -k XX, --key-list-ind XX
bgneal@59:                            2-letter key list indicator; if omitted a random one
bgneal@59:                            is used
bgneal@59:      -e ABCDEF, --ext-ind ABCDEF
bgneal@59:                            6-letter external message indicator; if omitted a
bgneal@59:                            random one is used
bgneal@59:      -s S, --sys-ind S     1-letter system indicator; if omitted a random one is
bgneal@59:                            used
bgneal@59: 
bgneal@59:    Either the -f/--file or -t/--text arguments must be supplied
bgneal@59: 
bgneal@59: The options to the ``encrypt`` command are described below.
bgneal@59: 
bgneal@59: ``-z`` or ``--key-file``
bgneal@59:    This option names the key list file. If not given, the default of
bgneal@59:    ``m209keys.cfg`` is used.
bgneal@59: 
bgneal@59: ``-t`` or ``--file``
bgneal@59:    This option specifies the file that contains the text to encrypt. If the
bgneal@59:    filename is given as ``-`` then input is read directly from ``stdin``. Note
bgneal@59:    that either this option or the ``-t`` option must be specified, but not
bgneal@59:    both.
bgneal@59: 
bgneal@59: ``-t`` or ``--text``
bgneal@59:    This option specifies the text to encrypt on the command-line. Depending
bgneal@59:    upon your system, you'll probably have to quote or escape your text. Note
bgneal@59:    that you must either specify this option or the ``-f`` option, but not both.
bgneal@59: 
bgneal@59: ``-k`` or ``--key-list-ind``
bgneal@59:    This option specifies the two-letter key list indicator to use. Valid values
bgneal@59:    range from ``AA`` to ``ZZ``. The key list with this indicator must be in the
bgneal@59:    key list file given by the ``-z`` option. If this option is omitted, a key
bgneal@59:    list from the key list file is chosen at random.
bgneal@59: 
bgneal@59: ``-e`` or ``--ext-ind``
bgneal@59:    This option specifies the six-letter external message indicator, which is an
bgneal@59:    encryption parameter as explained in the 1944 manual (see the references).
bgneal@59:    Each letter must exist on the key wheels from left to right. If this option
bgneal@59:    is omitted, an external message indicator is chosen at random.
bgneal@59: 
bgneal@59: ``-s`` or ``--sys-ind``
bgneal@59:    This option specifies the one-letter system indicator, which is an
bgneal@59:    encryption parameter as explained in the 1944 manual (see the references).
bgneal@59:    This must be a letter from ``A`` to ``Z``. If not given, one is chosen at
bgneal@59:    random.
bgneal@59: 
bgneal@59: .. NOTE:: 
bgneal@59: 
bgneal@59:    An actual M-209 can only accept the letters ``A-Z``. When using an actual
bgneal@59:    M-209, space characters must be input as the letter ``Z``. Numbers must
bgneal@59:    typically be spelled out as words or some other agreed-upon convention.
bgneal@59:    Likewise with punctuation. To make encryption more convenient, the ``m209``
bgneal@59:    program will accept spaces and automatically convert them to the letter
bgneal@59:    ``Z``. Lowercase letters will automatically be converted to uppercase. All
bgneal@59:    other characters will produce an error. This applies to both text read on
bgneal@59:    the command-line with the ``-t`` option and text read from files (``-f``).
bgneal@59: 
bgneal@59: Encrypt examples
bgneal@59: ++++++++++++++++
bgneal@59: 
bgneal@59: To encrypt a simple string on the command-line using the default key file and
bgneal@59: random encryption parameters::
bgneal@59: 
bgneal@59:    $ m209 encrypt -t "Rendezvous at zero seven thirty"
bgneal@59: 
bgneal@59: To save the encrypted text to a file::
bgneal@59: 
bgneal@59:    $ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt
bgneal@59: 
bgneal@59: To read the contents of a file and encrypt it, saving it to a new file::
bgneal@59: 
bgneal@59:    $ m209 enc -f message.txt > secret.txt
bgneal@59: 
bgneal@59: To explicitly specify encryption parameters, and read text from ``stdin``::
bgneal@59: 
bgneal@59:    $ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A 
bgneal@59: