Mercurial > public > m209

comparison docs/commandline.rst @ 58:902f14d7e032

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added docs for the keygen sub-command.
author Brian Neal <bgneal@gmail.com>
date Tue, 09 Jul 2013 21:34:48 -0500
parents 859dc6624ab7
children 6acd17898381
comparison
equal deleted inserted replaced
57:859dc6624ab7 58:902f14d7e032
1 Command-line Reference 1 Command-line Reference
2 ====================== 2 ======================
3
4 Overview
5 --------
6
7 The ``m209`` command-line utility peforms three functions:
8
9 * Creates key list files
10 * Encrypts text, either given on the command line or read from a file
11 * Decrypts text, either given on the command line or read from a file
12
13 These functions are implemented as sub-commands. To see the list of
14 sub-commands and options common to all sub-commands, use the ``-h`` or
15 ``--help`` option::
16
17 $ m209 --help
18 usage: m209 [-h] [-l {debug,info,warning,error,critical}]
19 {encrypt,enc,decrypt,dec,keygen,key} ...
20
21 M-209 simulator and utility program
22
23 optional arguments:
24 -h, --help show this help message and exit
25 -l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
26 set log level [default: warning]
27
28 list of commands:
29 type m209 {command} -h for help on {command}
30
31 {encrypt,enc,decrypt,dec,keygen,key}
32 encrypt (enc) encrypt text from file or command-line
33 decrypt (dec) decrypt text from file or command-line
34 keygen (key) generate key list
35
36 The ``-l`` / ``--log`` options control the verbosity of output. Currently only
37 the ``keygen`` sub-command makes use of this option.
38
39 Each sub-command has an alias for those who prefer shorter commands.
40
41 Keygen Sub-command
42 ------------------
43
44 ``keygen``, or ``key`` for short, is the sub-command that pseudo-randomly
45 creates key list files for use by the ``encrypt`` and ``decrypt`` sub-commands,
46 as well as by the ``m209`` library routines.
47
48 Help on the ``keygen`` sub-command can be obtained with the following
49 invocation::
50
51 $ m209 keygen --help
52 usage: m209 keygen [-h] [-z KEY_FILE] [-o] [-s XX] [-n NUMBER]
53
54 Generate key list file
55
56 optional arguments:
57 -h, --help show this help message and exit
58 -z KEY_FILE, --key-file KEY_FILE
59 path to key list file [default: m209keys.cfg]
60 -o, --overwrite overwrite key list file if it exists
61 -s XX, --start XX starting indicator; if omitted, random indicators are
62 used
63 -n NUMBER, --number NUMBER
64 number of key lists to generate [default: 1]
65
66 The options for ``keygen`` are described below.
67
68 The ``-z`` or ``--key-file`` option names the key list file. If not supplied,
69 this defaults to ``m209keys.cfg``. Note that the other sub-commands also have
70 this option, and they too use the same default value.
71
72 The ``-o`` or ``--overwrite`` switch must be present if the key list file
73 already exists. It provides confirmation that the user wants to overwrite an
74 existing file. If the key list file already exists, and this option is not
75 supplied, this sub-command will exit with an error message and the original key
76 list file will be unchanged.
77
78 The ``-s`` or ``--start`` option sets the starting indicator for the key list
79 file. Key list indicators are two letters in the range ``AA`` to ``ZZ``. For
80 example, ``keygen`` can be told to create 3 key lists, starting with indicator
81 ``AA``. In this case the key lists ``AA``, ``AB``, and ``AC`` would be written
82 to the file. If this parameter is omitted, ``keygen`` picks indicators at
83 random. Key list indicators simply name the key list, and are placed in the
84 leading and trailing groups of encrypted messages to tell the receiver which
85 key list was used to create the message. Both sender and receiver must have the
86 same key list (name and contents) to communicate.
87
88 The ``-n`` or ``--number`` option specifies the number of key lists to
89 generate. The default value is 1.
90
91 .. NOTE::
92
93 The algorithm the ``keygen`` sub-command uses to generate key lists is based
94 on the actual US Army procedure taken from the 1944 manual. This procedure
95 is somewhat loosely specified and a lot is left up to the soldier creating
96 the key list. The ``keygen`` algorithm is ad-hoc and uses simple heuristics
97 and random numbers to make decisions. Occasionally this algorithm may fail
98 to generate a key list that meets the final criteria defined in the manual.
99 If this happens an error message will be displayed and no key list file will
100 be created. It is suggested to simply run the command again as it is not
101 likely to happen twice in a row.