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