Mercurial > public > m209

comparison docs/commandline.rst @ 59:6acd17898381

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added docs for the encrypt command. Added examples.
author Brian Neal <bgneal@gmail.com>
date Wed, 10 Jul 2013 21:33:03 -0500
parents 902f14d7e032
children 0a3e4bc49118
comparison
equal deleted inserted replaced
58:902f14d7e032 59:6acd17898381
36 The ``-l`` / ``--log`` options control the verbosity of output. Currently only 36 The ``-l`` / ``--log`` options control the verbosity of output. Currently only
37 the ``keygen`` sub-command makes use of this option. 37 the ``keygen`` sub-command makes use of this option.
38 38
39 Each sub-command has an alias for those who prefer shorter commands. 39 Each sub-command has an alias for those who prefer shorter commands.
40 40
41 Keygen Sub-command 41 Keygen sub-command
42 ------------------ 42 ------------------
43 43
44 ``keygen``, or ``key`` for short, is the sub-command that pseudo-randomly 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, 45 creates key list files for use by the ``encrypt`` and ``decrypt`` sub-commands,
46 as well as by the ``m209`` library routines. 46 as well as by the ``m209`` library routines.
63 -n NUMBER, --number NUMBER 63 -n NUMBER, --number NUMBER
64 number of key lists to generate [default: 1] 64 number of key lists to generate [default: 1]
65 65
66 The options for ``keygen`` are described below. 66 The options for ``keygen`` are described below.
67 67
68 The ``-z`` or ``--key-file`` option names the key list file. If not supplied, 68 ``-z`` or ``--key-file``
69 this defaults to ``m209keys.cfg``. Note that the other sub-commands also have 69 This option names the key list file. If not supplied, this defaults to
70 this option, and they too use the same default value. 70 ``m209keys.cfg``. Note that the other sub-commands also have this option,
71 71 and they too use the same default value.
72 The ``-o`` or ``--overwrite`` switch must be present if the key list file 72
73 already exists. It provides confirmation that the user wants to overwrite an 73 ``-o`` or ``--overwrite``
74 existing file. If the key list file already exists, and this option is not 74 This switch must be present if the key list file already exists. It provides
75 supplied, this sub-command will exit with an error message and the original key 75 confirmation that the user wants to overwrite an existing file. If the key
76 list file will be unchanged. 76 list file already exists, and this option is not supplied, this sub-command
77 77 will exit with an error message and the original key list file will be
78 The ``-s`` or ``--start`` option sets the starting indicator for the key list 78 unchanged.
79 file. Key list indicators are two letters in the range ``AA`` to ``ZZ``. For 79
80 example, ``keygen`` can be told to create 3 key lists, starting with indicator 80 ``-s`` or ``--start``
81 ``AA``. In this case the key lists ``AA``, ``AB``, and ``AC`` would be written 81 This option sets the starting indicator for the key list file. Key list
82 to the file. If this parameter is omitted, ``keygen`` picks indicators at 82 indicators are two letters in the range ``AA`` to ``ZZ``. For example,
83 random. Key list indicators simply name the key list, and are placed in the 83 ``keygen`` can be told to create 3 key lists, starting with indicator
84 leading and trailing groups of encrypted messages to tell the receiver which 84 ``AA``. In this case the key lists ``AA``, ``AB``, and ``AC`` would be
85 key list was used to create the message. Both sender and receiver must have the 85 written to the file. If this parameter is omitted, ``keygen`` picks
86 same key list (name and contents) to communicate. 86 indicators at random. Key list indicators simply name the key list, and are
87 87 placed in the leading and trailing groups of encrypted messages to tell the
88 The ``-n`` or ``--number`` option specifies the number of key lists to 88 receiver which key list was used to create the message. Both sender and
89 generate. The default value is 1. 89 receiver must have the same key list (name and contents) to communicate.
90
91 ``-n`` or ``--number``
92 This option specifies the number of key lists to generate. The default value
93 is 1.
90 94
91 .. NOTE:: 95 .. NOTE::
92 96
93 The algorithm the ``keygen`` sub-command uses to generate key lists is based 97 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 98 on the actual US Army procedure taken from the 1944 manual. This procedure
97 and random numbers to make decisions. Occasionally this algorithm may fail 101 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. 102 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 103 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 104 be created. It is suggested to simply run the command again as it is not
101 likely to happen twice in a row. 105 likely to happen twice in a row.
106
107 Keygen examples
108 +++++++++++++++
109
110 To generate 30 key lists in the default key list file (``m209keys.cfg``) with
111 random indicators, and overwriting the key list file if it exists::
112
113 $ m209 keygen -o -n 30
114 $ m209 key --overwrite --number=30
115
116 To generate 5 key lists that sequentially start with the indicator ``BN`` in
117 the key list file ``m209/keys/november/keys.cfg``::
118
119 $ m209 keygen -z m209/keys/november/keys.cfg -s BN -n 5
120
121
122 Encrypt sub-command
123 -------------------
124
125 ``encrypt``, or ``enc``, is the sub-command used to encrypt text. To get help
126 on the ``encrypt`` command, type the following::
127
128 $ m209 encrypt -h
129 usage: m209 encrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT] [-k XX] [-e ABCDEF]
130 [-s S]
131
132 Encrypt text from a file or command-line
133
134 optional arguments:
135 -h, --help show this help message and exit
136 -z KEY_FILE, --key-file KEY_FILE
137 path to key list file [default: m209keys.cfg]
138 -f FILE, --file FILE path to plaintext file or - for stdin
139 -t TEXT, --text TEXT text string to encrypt
140 -k XX, --key-list-ind XX
141 2-letter key list indicator; if omitted a random one
142 is used
143 -e ABCDEF, --ext-ind ABCDEF
144 6-letter external message indicator; if omitted a
145 random one is used
146 -s S, --sys-ind S 1-letter system indicator; if omitted a random one is
147 used
148
149 Either the -f/--file or -t/--text arguments must be supplied
150
151 The options to the ``encrypt`` command are described below.
152
153 ``-z`` or ``--key-file``
154 This option names the key list file. If not given, the default of
155 ``m209keys.cfg`` is used.
156
157 ``-t`` or ``--file``
158 This option specifies the file that contains the text to encrypt. If the
159 filename is given as ``-`` then input is read directly from ``stdin``. Note
160 that either this option or the ``-t`` option must be specified, but not
161 both.
162
163 ``-t`` or ``--text``
164 This option specifies the text to encrypt on the command-line. Depending
165 upon your system, you'll probably have to quote or escape your text. Note
166 that you must either specify this option or the ``-f`` option, but not both.
167
168 ``-k`` or ``--key-list-ind``
169 This option specifies the two-letter key list indicator to use. Valid values
170 range from ``AA`` to ``ZZ``. The key list with this indicator must be in the
171 key list file given by the ``-z`` option. If this option is omitted, a key
172 list from the key list file is chosen at random.
173
174 ``-e`` or ``--ext-ind``
175 This option specifies the six-letter external message indicator, which is an
176 encryption parameter as explained in the 1944 manual (see the references).
177 Each letter must exist on the key wheels from left to right. If this option
178 is omitted, an external message indicator is chosen at random.
179
180 ``-s`` or ``--sys-ind``
181 This option specifies the one-letter system indicator, which is an
182 encryption parameter as explained in the 1944 manual (see the references).
183 This must be a letter from ``A`` to ``Z``. If not given, one is chosen at
184 random.
185
186 .. NOTE::
187
188 An actual M-209 can only accept the letters ``A-Z``. When using an actual
189 M-209, space characters must be input as the letter ``Z``. Numbers must
190 typically be spelled out as words or some other agreed-upon convention.
191 Likewise with punctuation. To make encryption more convenient, the ``m209``
192 program will accept spaces and automatically convert them to the letter
193 ``Z``. Lowercase letters will automatically be converted to uppercase. All
194 other characters will produce an error. This applies to both text read on
195 the command-line with the ``-t`` option and text read from files (``-f``).
196
197 Encrypt examples
198 ++++++++++++++++
199
200 To encrypt a simple string on the command-line using the default key file and
201 random encryption parameters::
202
203 $ m209 encrypt -t "Rendezvous at zero seven thirty"
204
205 To save the encrypted text to a file::
206
207 $ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt
208
209 To read the contents of a file and encrypt it, saving it to a new file::
210
211 $ m209 enc -f message.txt > secret.txt
212
213 To explicitly specify encryption parameters, and read text from ``stdin``::
214
215 $ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A
216