Mercurial > public > m209

annotate docs/commandline.rst @ 64:72e0bda6df40

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Split key list docs into own source file.
author Brian Neal <bgneal@gmail.com>
date Sat, 20 Jul 2013 13:26:25 -0500
parents 0a3e4bc49118
children 854c5d361011
rev   line source
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@59 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@59 68 ``-z`` or ``--key-file``
bgneal@59 69 This option names the key list file. If not supplied, this defaults to
bgneal@59 70 ``m209keys.cfg``. Note that the other sub-commands also have this option,
bgneal@59 71 and they too use the same default value.
bgneal@58 72
bgneal@59 73 ``-o`` or ``--overwrite``
bgneal@59 74 This switch must be present if the key list file already exists. It provides
bgneal@59 75 confirmation that the user wants to overwrite an existing file. If the key
bgneal@59 76 list file already exists, and this option is not supplied, this sub-command
bgneal@59 77 will exit with an error message and the original key list file will be
bgneal@59 78 unchanged.
bgneal@58 79
bgneal@59 80 ``-s`` or ``--start``
bgneal@59 81 This option sets the starting indicator for the key list file. Key list
bgneal@59 82 indicators are two letters in the range ``AA`` to ``ZZ``. For example,
bgneal@59 83 ``keygen`` can be told to create 3 key lists, starting with indicator
bgneal@59 84 ``AA``. In this case the key lists ``AA``, ``AB``, and ``AC`` would be
bgneal@59 85 written to the file. If this parameter is omitted, ``keygen`` picks
bgneal@59 86 indicators at random. Key list indicators simply name the key list, and are
bgneal@59 87 placed in the leading and trailing groups of encrypted messages to tell the
bgneal@59 88 receiver which key list was used to create the message. Both sender and
bgneal@59 89 receiver must have the same key list (name and contents) to communicate.
bgneal@58 90
bgneal@59 91 ``-n`` or ``--number``
bgneal@59 92 This option specifies the number of key lists to generate. The default value
bgneal@59 93 is 1.
bgneal@58 94
bgneal@58 95 .. NOTE::
bgneal@58 96
bgneal@58 97 The algorithm the ``keygen`` sub-command uses to generate key lists is based
bgneal@58 98 on the actual US Army procedure taken from the 1944 manual. This procedure
bgneal@58 99 is somewhat loosely specified and a lot is left up to the soldier creating
bgneal@58 100 the key list. The ``keygen`` algorithm is ad-hoc and uses simple heuristics
bgneal@58 101 and random numbers to make decisions. Occasionally this algorithm may fail
bgneal@58 102 to generate a key list that meets the final criteria defined in the manual.
bgneal@58 103 If this happens an error message will be displayed and no key list file will
bgneal@58 104 be created. It is suggested to simply run the command again as it is not
bgneal@58 105 likely to happen twice in a row.
bgneal@59 106
bgneal@59 107 Keygen examples
bgneal@59 108 +++++++++++++++
bgneal@59 109
bgneal@59 110 To generate 30 key lists in the default key list file (``m209keys.cfg``) with
bgneal@59 111 random indicators, and overwriting the key list file if it exists::
bgneal@59 112
bgneal@59 113 $ m209 keygen -o -n 30
bgneal@59 114 $ m209 key --overwrite --number=30
bgneal@59 115
bgneal@59 116 To generate 5 key lists that sequentially start with the indicator ``BN`` in
bgneal@59 117 the key list file ``m209/keys/november/keys.cfg``::
bgneal@59 118
bgneal@59 119 $ m209 keygen -z m209/keys/november/keys.cfg -s BN -n 5
bgneal@59 120
bgneal@59 121
bgneal@59 122 Encrypt sub-command
bgneal@59 123 -------------------
bgneal@59 124
bgneal@59 125 ``encrypt``, or ``enc``, is the sub-command used to encrypt text. To get help
bgneal@59 126 on the ``encrypt`` command, type the following::
bgneal@59 127
bgneal@59 128 $ m209 encrypt -h
bgneal@59 129 usage: m209 encrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT] [-k XX] [-e ABCDEF]
bgneal@59 130 [-s S]
bgneal@59 131
bgneal@59 132 Encrypt text from a file or command-line
bgneal@59 133
bgneal@59 134 optional arguments:
bgneal@59 135 -h, --help show this help message and exit
bgneal@59 136 -z KEY_FILE, --key-file KEY_FILE
bgneal@59 137 path to key list file [default: m209keys.cfg]
bgneal@59 138 -f FILE, --file FILE path to plaintext file or - for stdin
bgneal@59 139 -t TEXT, --text TEXT text string to encrypt
bgneal@59 140 -k XX, --key-list-ind XX
bgneal@59 141 2-letter key list indicator; if omitted a random one
bgneal@59 142 is used
bgneal@59 143 -e ABCDEF, --ext-ind ABCDEF
bgneal@59 144 6-letter external message indicator; if omitted a
bgneal@59 145 random one is used
bgneal@59 146 -s S, --sys-ind S 1-letter system indicator; if omitted a random one is
bgneal@59 147 used
bgneal@59 148
bgneal@59 149 Either the -f/--file or -t/--text arguments must be supplied
bgneal@59 150
bgneal@59 151 The options to the ``encrypt`` command are described below.
bgneal@59 152
bgneal@59 153 ``-z`` or ``--key-file``
bgneal@59 154 This option names the key list file. If not given, the default of
bgneal@59 155 ``m209keys.cfg`` is used.
bgneal@59 156
bgneal@59 157 ``-t`` or ``--file``
bgneal@59 158 This option specifies the file that contains the text to encrypt. If the
bgneal@59 159 filename is given as ``-`` then input is read directly from ``stdin``. Note
bgneal@59 160 that either this option or the ``-t`` option must be specified, but not
bgneal@59 161 both.
bgneal@59 162
bgneal@59 163 ``-t`` or ``--text``
bgneal@59 164 This option specifies the text to encrypt on the command-line. Depending
bgneal@59 165 upon your system, you'll probably have to quote or escape your text. Note
bgneal@59 166 that you must either specify this option or the ``-f`` option, but not both.
bgneal@59 167
bgneal@59 168 ``-k`` or ``--key-list-ind``
bgneal@59 169 This option specifies the two-letter key list indicator to use. Valid values
bgneal@59 170 range from ``AA`` to ``ZZ``. The key list with this indicator must be in the
bgneal@59 171 key list file given by the ``-z`` option. If this option is omitted, a key
bgneal@59 172 list from the key list file is chosen at random.
bgneal@59 173
bgneal@59 174 ``-e`` or ``--ext-ind``
bgneal@59 175 This option specifies the six-letter external message indicator, which is an
bgneal@59 176 encryption parameter as explained in the 1944 manual (see the references).
bgneal@59 177 Each letter must exist on the key wheels from left to right. If this option
bgneal@59 178 is omitted, an external message indicator is chosen at random.
bgneal@59 179
bgneal@59 180 ``-s`` or ``--sys-ind``
bgneal@59 181 This option specifies the one-letter system indicator, which is an
bgneal@59 182 encryption parameter as explained in the 1944 manual (see the references).
bgneal@59 183 This must be a letter from ``A`` to ``Z``. If not given, one is chosen at
bgneal@59 184 random.
bgneal@59 185
bgneal@59 186 .. NOTE::
bgneal@59 187
bgneal@59 188 An actual M-209 can only accept the letters ``A-Z``. When using an actual
bgneal@59 189 M-209, space characters must be input as the letter ``Z``. Numbers must
bgneal@59 190 typically be spelled out as words or some other agreed-upon convention.
bgneal@59 191 Likewise with punctuation. To make encryption more convenient, the ``m209``
bgneal@59 192 program will accept spaces and automatically convert them to the letter
bgneal@59 193 ``Z``. Lowercase letters will automatically be converted to uppercase. All
bgneal@60 194 other characters will be silently dropped from the input. This applies to
bgneal@60 195 both text read on the command-line with the ``-t`` option and text read from
bgneal@60 196 files (``-f``).
bgneal@59 197
bgneal@59 198 Encrypt examples
bgneal@59 199 ++++++++++++++++
bgneal@59 200
bgneal@59 201 To encrypt a simple string on the command-line using the default key file and
bgneal@59 202 random encryption parameters::
bgneal@59 203
bgneal@59 204 $ m209 encrypt -t "Rendezvous at zero seven thirty"
bgneal@60 205 BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY
bgneal@59 206
bgneal@59 207 To save the encrypted text to a file::
bgneal@59 208
bgneal@59 209 $ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt
bgneal@59 210
bgneal@59 211 To read the contents of a file and encrypt it, saving it to a new file::
bgneal@59 212
bgneal@59 213 $ m209 enc -f message.txt > secret.txt
bgneal@59 214
bgneal@59 215 To explicitly specify encryption parameters, and read text from ``stdin``::
bgneal@59 216
bgneal@59 217 $ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A
bgneal@59 218
bgneal@60 219
bgneal@60 220 Decrypt sub-command
bgneal@60 221 -------------------
bgneal@60 222
bgneal@60 223 ``decrypt``, or ``dec``, is the sub-command used to decrypt text. To get help
bgneal@60 224 on the ``decrypt`` command, type the following::
bgneal@60 225
bgneal@60 226 $ m209 decrypt --help
bgneal@60 227 usage: m209 decrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT]
bgneal@60 228
bgneal@60 229 Decyrpt text from a file or command-line
bgneal@60 230
bgneal@60 231 optional arguments:
bgneal@60 232 -h, --help show this help message and exit
bgneal@60 233 -z KEY_FILE, --key-file KEY_FILE
bgneal@60 234 path to key list file [default: m209keys.cfg]
bgneal@60 235 -f FILE, --file FILE path to ciphertext file or - for stdin
bgneal@60 236 -t TEXT, --text TEXT text string to decrypt
bgneal@60 237
bgneal@60 238 Either the -f/--file or -t/--text arguments must be supplied
bgneal@60 239
bgneal@60 240 The options to the ``decrypt`` command are described below.
bgneal@60 241
bgneal@60 242 ``-z`` or ``--key-file``
bgneal@60 243 This option names the key list file. If not given, the default of
bgneal@60 244 ``m209keys.cfg`` is used.
bgneal@60 245
bgneal@60 246 ``-t`` or ``--file``
bgneal@60 247 This option specifies the file that contains the text to decrypt. If the
bgneal@60 248 filename is given as ``-`` then input is read directly from ``stdin``. Note
bgneal@60 249 that either this option or the ``-t`` option must be specified, but not
bgneal@60 250 both.
bgneal@60 251
bgneal@60 252 ``-t`` or ``--text``
bgneal@60 253 This option specifies the text to decrypt on the command-line. Depending
bgneal@60 254 upon your system, you'll probably have to quote or escape your text. Note
bgneal@60 255 that you must either specify this option or the ``-f`` option, but not both.
bgneal@60 256
bgneal@60 257 .. NOTE::
bgneal@60 258
bgneal@60 259 The first and last 2 groups of an encrypted message contain the information
bgneal@60 260 needed to decrypt the message: the system indicator, the external message
bgneal@60 261 indicator, and the key list indicator. If the key list file given to the
bgneal@60 262 decrypt command does not contain the key list used to encrypt the message,
bgneal@60 263 then the message cannot be decrypted and an error message will be displayed.
bgneal@60 264
bgneal@60 265 Decrypt examples
bgneal@60 266 ++++++++++++++++
bgneal@60 267
bgneal@60 268 To decrypt a simple string on the command-line using the default key file::
bgneal@60 269
bgneal@60 270 $ m209 decrypt -t "BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY"
bgneal@60 271 RENDE VOUS AT ERO SEVEN THIRTYXSJQ
bgneal@60 272
bgneal@60 273 To save the decrypted text to a file::
bgneal@60 274
bgneal@60 275 $ m209 decrypt -t "BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY" > msg.txt
bgneal@60 276
bgneal@60 277 To read the contents of a file and decrypt it, saving it to a new file::
bgneal@60 278
bgneal@60 279 $ m209 dec -f secret.txt > msg.txt
bgneal@60 280
bgneal@60 281 To decrypt from ``stdin``::
bgneal@60 282
bgneal@60 283 $ cat secret.txt | m209 dec -f -
bgneal@60 284 RENDE VOUS AT ERO SEVEN THIRTYXSJQ
bgneal@60 285
bgneal@60 286
bgneal@60 287 .. NOTE::
bgneal@60 288
bgneal@60 289 In this example, the last group of the encrypted message only has one
bgneal@60 290 letter. It was padded out to five letters with ``X``'s by the encryption
bgneal@60 291 process, and thus four "garbage" letters appear at the end in the decrypted
bgneal@60 292 output.
bgneal@60 293
bgneal@60 294 Note also that the ``Z`` in ``RENDEZVOUS`` and ``ZERO`` were converted to
bgneal@60 295 spaces by the decrypt process.
bgneal@60 296
bgneal@60 297 In both of these cases the operator would have to "fix up" the message
bgneal@60 298 before passing it up the chain of command.