22 \h'-\w'\\$1\ 'u'\\$1\ \c
27 .TH catsign 1 "17 March 2005" "Straylight/Edgeware" "Catacomb cryptographic library"
29 catsign \- sign and verify messages
110 command signs and verifies messages. It also works as a simple PEM
111 encoder and decoder. It provides a number of subcommands, by which the
112 various operations may be carried out.
114 Before the command name,
116 may be given. The following global options are supported:
118 .BR "\-h, \-\-help " [ \fIcommand ...]
119 Writes a brief summary of
121 various options to standard output, and returns a successful exit
122 status. With command names, gives help on those commands.
124 .B "\-v, \-\-version"
125 Writes the program's version number to standard output, and returns a
126 successful exit status.
129 Writes a very terse command line summary to standard output, and returns
130 a successful exit status.
132 .BI "\-k, \-\-keyring " file
133 Names the keyring file which
135 is to process. The default keyring, used if this option doesn't specify
136 one, is the file named
138 in the current directory. See
142 for more details about keyring files.
144 Algorithms to be used with a particular key are described by attributes
145 on the key, or its type. The
147 command deals with signing keys. (Note that
149 uses signing keys in the same way as
160 attribute is present on the key, then it must have this form; otherwise,
161 the key's type must have the form
164 Algorithm selections are taken from appropriately-named attributes, or,
165 failing that, from the
168 The signature algorithm is chosen according to the setting of
172 for a list of supported signature algorithms.
175 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
176 RFC3447; the difference is that the hash is left bare rather than being
177 wrapped in a DER-encoded
179 structure. This doesn't affect security since the key can only be used
180 with the one hash function anyway, and dropping the DER wrapping permits
181 rapid adoption of new hash functions. Regardless, use of this algorithm
182 is not recommended, since the padding method has been shown vulnerable
192 This is the RSASSA-PSS algorithm described in RFC3447. It is the
193 preferred RSA-based signature scheme. Use the
202 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
211 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
221 This is the revised KCDSA (Korean Certificate-based Digital Signature
222 Algorithm) described in
223 .I The Revised Version of KCDSA
224 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
236 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
245 As well as the signature algorithm itself, a hash function is used.
246 This is taken from the
248 attribute on the key, or, failing that, from the
252 or, if that is absent, determined by the signature algorithm as follows.
260 the default hash function is
267 the default hash function is
272 for a list of supported hash functions.
274 Two encodings for the ciphertext are supported.
277 The raw format, which has the benefit of being smaller, but needs to be
278 attached to mail messages and generally handled with care.
281 PEM-encapsulated Base-64 encoded text. This format can be included
282 directly in email and picked out again automatically; but there is a
283 4-to-3 data expansion as a result.
284 .SH "SIGNATURE FORMATS"
285 There are two basic signature formats understood by
288 Embedded signatures include (embed) the message they sign; hence they're
289 complete in and of themselves. The
291 program extracts the message during signature verification.
293 Detached signatures are separate from the messages they sign, and both
294 the original file and the signature are required for a successful
297 Another important distinction is whether the message data is considered
298 to be plain text or raw binary data.
300 When dealing with plain text,
302 allows a limited quantity of leeway in the messages it processes. It
303 ignores trailing whitespace on a line, including stray carriage-returns,
304 which may appear if Windows boxes have had their way with the data. It
305 also appends a final newline if there wasn't one before. In embedded
306 signatures, the text is left unencoded, so that the message is readable.
308 Binary files are preserved completely, and no variation whatever is
315 command can convert between detached and embedded signatures; it cannot
316 convert between binary and text mode signatures. (The data actually
317 signed includes a flag saying whether the message is textual. The
318 rationale here is that what looks like an ASCII space before a newline
319 may be devastatingly significant in a binary data file, and if a message
320 is signed as raw binary then no changes whatever should be allowed.)
321 .SH "COMMAND REFERENCE"
325 command behaves exactly as the
327 option. With no arguments, it shows an overview of
329 options; with arguments, it describes the named subcommands.
333 command prints various lists of tokens understood by
335 With no arguments, it prints all of the lists; with arguments, it prints
336 just the named lists, in order. The recognized lists can be enumerated
341 command. The lists are as follows.
344 The lists which can be enumerated by the
349 The signature algorithms which can be used in a signing key's
354 The hash functions which can be used in a key's
359 The encodings which can be applied to encrypted messages; see
365 command signs a message and writes out an appropriately-encoded
366 signature. By default, it reads a message from standard input and
367 writes the signature to standard output. If a filename argument is
368 given, this file is read instead.
370 The following options are recognized.
373 Produce ASCII-armoured output. This is equivalent to specifying
380 Read and sign the input as binary data. The default is to treat the
384 Produce a detached signature. The default is to produce a signature
385 with embedded message.
387 .BI "\-f, \-\-format " format
388 Produce output encoded according to
391 .BI "\-k, \-\-key " tag
392 Use the signing key named
394 in the current keyring; the default key is
397 .BI "\-o, \-\-ouptut " file
400 rather than to standard output.
403 Read and sign the input as text. This is the default.
407 command checks a signature's validity, producing as output information
408 about the signature and the signed message.
410 The first non-option argument is the name of the file containing the
411 signature data; this may be omitted or
413 to indicate that the signature be read from standard input. The second
414 non-option argument, if any, is the name of the file to read the message
415 from, if the signature is detached. An error is reported if a message
416 file is specified but the signature contains an embedded message
417 already; if the signature is detached but no filename is given, then the
418 message is expected on stdin (immediately after the signature, if any).
421 Read ASCII-armoured input. This is equivalent to specifying
428 Buffer the message until the signature is verified. This is forced on
429 if output is to stdout, but is always available as an option.
431 .BI "\-f, \-\-format " format
432 Read input encoded according to
435 .B "\-v, \-\-verbose"
436 Produce more verbose messages. See below for the messages produced
437 during decryption. The default verbosity level is 1. (Currently this
438 is the most verbose setting. This might not be the case always.)
441 Produce fewer messages.
443 .BI "\-k, \-\-key " tag
446 uses the signature header to work out which key to use to verify a
447 signature. Using this option causes verification to fail unless the
448 signature header specifies the key named
452 Show the datestamp in the signature in UTC rather than (your) local
457 .BI "\-o, \-\-output " file
458 Write the verified message to
460 The file is written in text or binary
461 mode as appropriate. The default is to write the message to standard
462 output unless verifying a detached signature, in which case nothing is
465 Output is written to standard output in a machine-readable format.
466 Major problems cause the program to write a diagnostic to standard error
467 and exit nonzero as usual. The quantity of output varies depending on
468 the verbosity level and whether the message is also being written to
469 standard output. Output lines begin with a keyword:
472 An error prevented verification. The program will exit nonzero.
476 encountered a situation which may or may not invalidate the
480 Verification was successful. This is only produced if the message is
481 being sent somewhere other than standard output.
484 The message follows, starting just after the next newline character or
485 sequence. This is only produced if the message is being written to
489 Any other information.
491 The information written at the various verbosity levels is as follows.
493 No output. Watch the exit status.
498 All output written has been checked for authenticity. However, output
499 can fail madway through for many reasons, and the resulting message may
500 therefore be truncated. Don't rely on the output being complete until
507 command analyses a signature without verifying it, and prints
508 interesting information about it. This might be useful for diagnostic
509 purposes. No keys are needed for this operation, though you get more
510 useful information if you have them.
512 If a non-option argument is given, and it is not
514 then it is taken to name the file containing the signature to parse;
515 otherwise a signature is read from standard input.
517 The following options are recognized.
520 Read ASCII-armoured input. This is equivalent to specifying
526 .BI "\-f, \-\-format " format
527 Read input encoded according to
531 Show the datestamp in the signature in UTC rather than (your) local
536 A description of the signature block is produced on standard output; it
537 is mostly machine-readable. The first word on each line explains what
538 kind of output it is.
541 The signature data is invalid and cannot be parsed.
544 Something is wrong with the data, but isn't fatal.
547 An environmental problem means that the information isn't as helpful as
548 it might be. For example, the keyring file can't be opened, so we don't
549 know whether the verification key is there.
551 .BI "INFO flags " flags
552 Describes the flags set in the signature header. The
554 are a list of flags, one per word, preceded by a
556 if the flag is clear.
558 .BI "INFO expected-flags " flags
559 If the PEM boundary string didn't match the actual signature data then
560 this line is output, listing the expected flags and their settings.
561 Problems with boundary mismatches can be resolved using the
565 .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz
566 Signature was (allegedly!) made at the given time and date. If the
568 option was given, this will be in UTC.
571 Signature was (allegedly!) made using the key
573 which is present in the current keyring.
575 .BI "INFO unknown-key " keyid
576 Signature was (allegedly!) made using the key with id
578 which is not in the current keyring (or the keyring wasn't found).
582 command translates signatures between the various supported formats.
583 This is a (slightly) more complex operation than re-encoding, though it
584 does not require any cryptographic operations.
586 The first non-option argument is the name of the file containing the
587 signature data; this may be omitted or
589 to indicate that the signature be read from standard input. The second
590 non-option argument, if any, is the name of the file to read the message
591 from, if the signature is detached. An error is reported if a message
592 file is specified but the signature contains an embedded message
593 already; if the signature is detached but no filename is given, then the
594 message is expected on stdin (immediately after the signature, if any).
596 The options follow a rough convention: options describing the input
597 format are lower-case and options specifying the output format are
598 upper-case. The following options are recognized.
599 .TP "\-a, \-\-armour-in"
600 Read ASCII-armoured input. This is equivalent to specifying
605 .TP "\-A, \-\-armour-out"
606 Produce ASCII-armoured output. This is equivalent to specifying
613 Produce a detached signature. This may be used to detach a signature
614 from an embedded message.
617 Produce a signature with embedded message. This may be used to
618 reattach a message to its detached signature.
620 .BI "\-f, \-\-format-in " format
621 Read input encoded according to
624 .BI "\-F, \-\-format-out " format
625 Produce output encoded according to
628 .BI "\-m, \-\-message " file
635 then write the message to standard output. Don't send the message and
636 signature to the same place because it doesn't work.
638 .BI "\-o, \-\-output " file
639 Write the signature to
645 option is given, a signature is written to standard output.
649 command encodes an input file according to one of the encodings
652 The input is read from the
654 given on the command line, or from standard input if none is specified.
655 Options provided are:
657 .BI "\-f, \-\-format " format
662 for a list of encoding formats.
664 .BI "\-b, \-\-boundary " label
665 Set the PEM boundary string to
667 i.e., assuming we're encoding in PEM format, the output will have
668 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
670 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
671 at the bottom. The default
676 .BI "\-o, \-\-output " file
679 instead of to standard output.
683 command decodes an input file encoded according to one of the encodings
686 The input is read from the
688 given on the command line, or from standard input if none is specified.
689 Options provided are:
691 .BI "\-f, \-\-format " format
696 for a list of encoding formats.
698 .BI "\-b, \-\-boundary " label
699 Set the PEM boundary string to
701 i.e., assuming we're encoding in PEM format, start processing input
703 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
705 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
706 lines. Without this option,
708 will start reading at the first plausible boundary string, and continue
709 processing until it reaches the matching end boundary.
711 .BI "\-o, \-\-output " file
714 instead of to standard output.
716 The trailing-whitespace deletion doesn't work for more than 32K of
717 whitespace. I don't think this is a big problem, really.
721 command does something unhelpful if message and signature are sent to
730 Mark Wooding, <mdw@nsict.org>
projects / u / mdw / catacomb / blob