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@58: 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@58: The ``-z`` or ``--key-file`` option names the key list file. If not supplied,
bgneal@58: this defaults to ``m209keys.cfg``. Note that the other sub-commands also have
bgneal@58: this option, and they too use the same default value.
bgneal@58: 
bgneal@58: The ``-o`` or ``--overwrite`` switch must be present if the key list file
bgneal@58: already exists. It provides confirmation that the user wants to overwrite an
bgneal@58: existing file. If the key list file already exists, and this option is not
bgneal@58: supplied, this sub-command will exit with an error message and the original key
bgneal@58: list file will be unchanged.
bgneal@58: 
bgneal@58: The ``-s`` or ``--start`` option sets the starting indicator for the key list
bgneal@58: file. Key list indicators are two letters in the range ``AA`` to ``ZZ``. For
bgneal@58: example, ``keygen`` can be told to create 3 key lists, starting with indicator
bgneal@58: ``AA``.  In this case the key lists ``AA``, ``AB``, and ``AC`` would be written
bgneal@58: to the file. If this parameter is omitted, ``keygen`` picks indicators at
bgneal@58: random. Key list indicators simply name the key list, and are placed in the
bgneal@58: leading and trailing groups of encrypted messages to tell the receiver which
bgneal@58: key list was used to create the message. Both sender and receiver must have the
bgneal@58: same key list (name and contents) to communicate.
bgneal@58: 
bgneal@58: The ``-n`` or ``--number`` option specifies the number of key lists to
bgneal@58: generate. The default value 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.