Mercurial > public > m209

comparison docs/commandline.rst @ 60:0a3e4bc49118

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added docs for the decrypt sub-command.
author Brian Neal <bgneal@gmail.com>
date Fri, 12 Jul 2013 14:17:02 -0500
parents 6acd17898381
children 854c5d361011
comparison
equal deleted inserted replaced
59:6acd17898381 60:0a3e4bc49118
189 M-209, space characters must be input as the letter ``Z``. Numbers must 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. 190 typically be spelled out as words or some other agreed-upon convention.
191 Likewise with punctuation. To make encryption more convenient, the ``m209`` 191 Likewise with punctuation. To make encryption more convenient, the ``m209``
192 program will accept spaces and automatically convert them to the letter 192 program will accept spaces and automatically convert them to the letter
193 ``Z``. Lowercase letters will automatically be converted to uppercase. All 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 194 other characters will be silently dropped from the input. This applies to
195 the command-line with the ``-t`` option and text read from files (``-f``). 195 both text read on the command-line with the ``-t`` option and text read from
196 files (``-f``).
196 197
197 Encrypt examples 198 Encrypt examples
198 ++++++++++++++++ 199 ++++++++++++++++
199 200
200 To encrypt a simple string on the command-line using the default key file and 201 To encrypt a simple string on the command-line using the default key file and
201 random encryption parameters:: 202 random encryption parameters::
202 203
203 $ m209 encrypt -t "Rendezvous at zero seven thirty" 204 $ m209 encrypt -t "Rendezvous at zero seven thirty"
205 BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY
204 206
205 To save the encrypted text to a file:: 207 To save the encrypted text to a file::
206 208
207 $ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt 209 $ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt
208 210
212 214
213 To explicitly specify encryption parameters, and read text from ``stdin``:: 215 To explicitly specify encryption parameters, and read text from ``stdin``::
214 216
215 $ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A 217 $ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A
216 218
219
220 Decrypt sub-command
221 -------------------
222
223 ``decrypt``, or ``dec``, is the sub-command used to decrypt text. To get help
224 on the ``decrypt`` command, type the following::
225
226 $ m209 decrypt --help
227 usage: m209 decrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT]
228
229 Decyrpt text from a file or command-line
230
231 optional arguments:
232 -h, --help show this help message and exit
233 -z KEY_FILE, --key-file KEY_FILE
234 path to key list file [default: m209keys.cfg]
235 -f FILE, --file FILE path to ciphertext file or - for stdin
236 -t TEXT, --text TEXT text string to decrypt
237
238 Either the -f/--file or -t/--text arguments must be supplied
239
240 The options to the ``decrypt`` command are described below.
241
242 ``-z`` or ``--key-file``
243 This option names the key list file. If not given, the default of
244 ``m209keys.cfg`` is used.
245
246 ``-t`` or ``--file``
247 This option specifies the file that contains the text to decrypt. If the
248 filename is given as ``-`` then input is read directly from ``stdin``. Note
249 that either this option or the ``-t`` option must be specified, but not
250 both.
251
252 ``-t`` or ``--text``
253 This option specifies the text to decrypt on the command-line. Depending
254 upon your system, you'll probably have to quote or escape your text. Note
255 that you must either specify this option or the ``-f`` option, but not both.
256
257 .. NOTE::
258
259 The first and last 2 groups of an encrypted message contain the information
260 needed to decrypt the message: the system indicator, the external message
261 indicator, and the key list indicator. If the key list file given to the
262 decrypt command does not contain the key list used to encrypt the message,
263 then the message cannot be decrypted and an error message will be displayed.
264
265 Decrypt examples
266 ++++++++++++++++
267
268 To decrypt a simple string on the command-line using the default key file::
269
270 $ m209 decrypt -t "BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY"
271 RENDE VOUS AT ERO SEVEN THIRTYXSJQ
272
273 To save the decrypted text to a file::
274
275 $ m209 decrypt -t "BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY" > msg.txt
276
277 To read the contents of a file and decrypt it, saving it to a new file::
278
279 $ m209 dec -f secret.txt > msg.txt
280
281 To decrypt from ``stdin``::
282
283 $ cat secret.txt | m209 dec -f -
284 RENDE VOUS AT ERO SEVEN THIRTYXSJQ
285
286
287 .. NOTE::
288
289 In this example, the last group of the encrypted message only has one
290 letter. It was padded out to five letters with ``X``'s by the encryption
291 process, and thus four "garbage" letters appear at the end in the decrypted
292 output.
293
294 Note also that the ``Z`` in ``RENDEZVOUS`` and ``ZERO`` were converted to
295 spaces by the decrypt process.
296
297 In both of these cases the operator would have to "fix up" the message
298 before passing it up the chain of command.