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
114 command signs and verifies messages. It also works as a simple PEM
115 encoder and decoder. It provides a number of subcommands, by which the
116 various operations may be carried out.
118 Before the command name,
120 may be given. The following global options are supported:
122 .BR "\-h, \-\-help " [ \fIcommand ...]
123 Writes a brief summary of
125 various options to standard output, and returns a successful exit
126 status. With command names, gives help on those commands.
128 .B "\-v, \-\-version"
129 Writes the program's version number to standard output, and returns a
130 successful exit status.
133 Writes a very terse command line summary to standard output, and returns
134 a successful exit status.
136 .BI "\-k, \-\-keyring " file
137 Names the keyring file which
139 is to process. The default keyring, used if this option doesn't specify
140 one, is the file named
142 in the current directory. See
146 for more details about keyring files.
148 Algorithms to be used with a particular key are described by attributes
149 on the key, or its type. The
151 command deals with signing keys. (Note that
153 uses signing keys in the same way as
164 attribute is present on the key, then it must have this form; otherwise,
165 the key's type must have the form
168 Algorithm selections are taken from appropriately-named attributes, or,
169 failing that, from the
172 The signature algorithm is chosen according to the setting of
176 for a list of supported signature algorithms.
179 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
180 RFC3447; the difference is that the hash is left bare rather than being
181 wrapped in a DER-encoded
183 structure. This doesn't affect security since the key can only be used
184 with the one hash function anyway, and dropping the DER wrapping permits
185 rapid adoption of new hash functions. Regardless, use of this algorithm
186 is not recommended, since the padding method has been shown vulnerable
196 This is the RSASSA-PSS algorithm described in RFC3447. It is the
197 preferred RSA-based signature scheme. Use the
206 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
215 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
225 This is the revised KCDSA (Korean Certificate-based Digital Signature
226 Algorithm) described in
227 .I The Revised Version of KCDSA
228 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
240 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
250 This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm.
251 More specifically, this is HashEd25519
254 algorithm \(en by default
266 This uses a symmetric message-authentication algorithm rather than a
267 digital signature. The precise message-authentication scheme used is
270 attribute on the key, which defaults to
272 if unspecified. Use the
280 As well as the signature algorithm itself, a hash function is used.
281 This is taken from the
283 attribute on the key, or, failing that, from the
287 or, if that is absent, determined by the signature algorithm as follows.
295 the default hash function is
302 the default hash function is
306 the default hash function is
311 for a list of supported hash functions.
313 Two encodings for the ciphertext are supported.
316 The raw format, which has the benefit of being smaller, but needs to be
317 attached to mail messages and generally handled with care.
320 PEM-encapsulated Base-64 encoded text. This format can be included
321 directly in email and picked out again automatically; but there is a
322 4-to-3 data expansion as a result.
323 .SH "SIGNATURE FORMATS"
324 There are two basic signature formats understood by
327 Embedded signatures include (embed) the message they sign; hence they're
328 complete in and of themselves. The
330 program extracts the message during signature verification.
332 Detached signatures are separate from the messages they sign, and both
333 the original file and the signature are required for a successful
336 Another important distinction is whether the message data is considered
337 to be plain text or raw binary data.
339 When dealing with plain text,
341 allows a limited quantity of leeway in the messages it processes. It
342 ignores trailing whitespace on a line, including stray carriage-returns,
343 which may appear if Windows boxes have had their way with the data. It
344 also appends a final newline if there wasn't one before. In embedded
345 signatures, the text is left unencoded, so that the message is readable.
347 Binary files are preserved completely, and no variation whatever is
354 command can convert between detached and embedded signatures; it cannot
355 convert between binary and text mode signatures. (The data actually
356 signed includes a flag saying whether the message is textual. The
357 rationale here is that what looks like an ASCII space before a newline
358 may be devastatingly significant in a binary data file, and if a message
359 is signed as raw binary then no changes whatever should be allowed.)
360 .SH "COMMAND REFERENCE"
364 command behaves exactly as the
366 option. With no arguments, it shows an overview of
368 options; with arguments, it describes the named subcommands.
372 command prints various lists of tokens understood by
374 With no arguments, it prints all of the lists; with arguments, it prints
375 just the named lists, in order. The recognized lists can be enumerated
380 command. The lists are as follows.
383 The lists which can be enumerated by the
388 The signature algorithms which can be used in a signing key's
393 The hash functions which can be used in a key's
398 The encodings which can be applied to encrypted messages; see
404 command signs a message and writes out an appropriately-encoded
405 signature. By default, it reads a message from standard input and
406 writes the signature to standard output. If a filename argument is
407 given, this file is read instead.
409 The following options are recognized.
412 Produce ASCII-armoured output. This is equivalent to specifying
419 Read and sign the input as binary data. The default is to treat the
423 Produce a detached signature. The default is to produce a signature
424 with embedded message.
426 .BI "\-f, \-\-format " format
427 Produce output encoded according to
430 .BI "\-k, \-\-key " tag
431 Use the signing key named
433 in the current keyring; the default key is
436 .BI "\-o, \-\-ouptut " file
439 rather than to standard output.
441 .BI "\-p, \-\-progress"
442 Write a progress meter to standard error while processing large files.
445 Read and sign the input as text. This is the default.
447 .B "\-C, \-\-nocheck"
448 Don't check the private key for validity. This makes signing go much
449 faster, but at the risk of using a duff key, and potentially leaking
450 information about the private key.
454 command checks a signature's validity, producing as output information
455 about the signature and the signed message.
457 The first non-option argument is the name of the file containing the
458 signature data; this may be omitted or
460 to indicate that the signature be read from standard input. The second
461 non-option argument, if any, is the name of the file to read the message
462 from, if the signature is detached. An error is reported if a message
463 file is specified but the signature contains an embedded message
464 already; if the signature is detached but no filename is given, then the
465 message is expected on stdin (immediately after the signature, if any).
468 Read ASCII-armoured input. This is equivalent to specifying
475 Buffer the message until the signature is verified. This is forced on
476 if output is to stdout, but is always available as an option.
478 .BI "\-f, \-\-format " format
479 Read input encoded according to
482 .B "\-v, \-\-verbose"
483 Produce more verbose messages. See below for the messages produced
484 during decryption. The default verbosity level is 1. (Currently this
485 is the most verbose setting. This might not be the case always.)
487 .BI "\-p, \-\-progress"
488 Write a progress meter to standard error while processing large files.
491 Produce fewer messages.
493 .BI "\-k, \-\-key " tag
496 uses the signature header to work out which key to use to verify a
497 signature. Using this option causes verification to fail unless the
498 signature header specifies the key named
501 .BI "\-t, \-\-freshtime " time
502 Only accept signatures claiming to have been made more recently than
508 (the default) then any timestamp in the past is acceptable.
511 Show the datestamp in the signature in UTC rather than (your) local
516 .BI "\-o, \-\-output " file
517 Write the verified message to
519 The file is written in text or binary
520 mode as appropriate. The default is to write the message to standard
521 output unless verifying a detached signature, in which case nothing is
524 .B "\-C, \-\-nocheck"
525 Don't check the public key for validity. This makes verification go
526 much faster, but at the risk of using a duff key, and potentially
527 accepting false signatures.
529 Output is written to standard output in a machine-readable format.
530 Major problems cause the program to write a diagnostic to standard error
531 and exit nonzero as usual. The quantity of output varies depending on
532 the verbosity level and whether the message is also being written to
533 standard output. Output lines begin with a keyword:
536 An error prevented verification. The program will exit nonzero.
540 encountered a situation which may or may not invalidate the
544 Verification was successful. This is only produced if the message is
545 being sent somewhere other than standard output.
548 The message follows, starting just after the next newline character or
549 sequence. This is only produced if the message is being written to
553 Any other information.
555 The information written at the various verbosity levels is as follows.
557 No output. Watch the exit status.
564 option is set (which happens automatically if writing to standard
569 checked for authenticity until it has all been written. Even with
571 output can fail midway for many reasons, and the resulting message may
572 therefore be truncated. Don't rely on the output being complete until
580 command analyses a signature without verifying it, and prints
581 interesting information about it. This might be useful for diagnostic
582 purposes. No keys are needed for this operation, though you get more
583 useful information if you have them.
585 If a non-option argument is given, and it is not
587 then it is taken to name the file containing the signature to parse;
588 otherwise a signature is read from standard input.
590 The following options are recognized.
593 Read ASCII-armoured input. This is equivalent to specifying
599 .BI "\-f, \-\-format " format
600 Read input encoded according to
603 .BI "\-p, \-\-progress"
604 Write a progress meter to standard error while processing large files.
607 Show the datestamp in the signature in UTC rather than (your) local
612 A description of the signature block is produced on standard output; it
613 is mostly machine-readable. The first word on each line explains what
614 kind of output it is.
617 The signature data is invalid and cannot be parsed.
620 Something is wrong with the data, but isn't fatal.
623 An environmental problem means that the information isn't as helpful as
624 it might be. For example, the keyring file can't be opened, so we don't
625 know whether the verification key is there.
627 .BI "INFO flags " flags
628 Describes the flags set in the signature header. The
630 are a list of flags, one per word, preceded by a
632 if the flag is clear.
634 .BI "INFO expected-flags " flags
635 If the PEM boundary string didn't match the actual signature data then
636 this line is output, listing the expected flags and their settings.
637 Problems with boundary mismatches can be resolved using the
641 .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz
642 Signature was (allegedly!) made at the given time and date. If the
644 option was given, this will be in UTC.
647 Signature was (allegedly!) made using the key
649 which is present in the current keyring.
651 .BI "INFO unknown-key " keyid
652 Signature was (allegedly!) made using the key with id
654 which is not in the current keyring (or the keyring wasn't found).
658 command translates signatures between the various supported formats.
659 This is a (slightly) more complex operation than re-encoding, though it
660 does not require any cryptographic operations.
662 The first non-option argument is the name of the file containing the
663 signature data; this may be omitted or
665 to indicate that the signature be read from standard input. The second
666 non-option argument, if any, is the name of the file to read the message
667 from, if the signature is detached. An error is reported if a message
668 file is specified but the signature contains an embedded message
669 already; if the signature is detached but no filename is given, then the
670 message is expected on stdin (immediately after the signature, if any).
672 The options follow a rough convention: options describing the input
673 format are lower-case and options specifying the output format are
674 upper-case. The following options are recognized.
676 .BI "\-a, \-\-armour-in"
677 Read ASCII-armoured input. This is equivalent to specifying
683 .BI "\-p, \-\-progress"
684 Write a progress meter to standard error while processing large files.
686 .BI "\-A, \-\-armour-out"
687 Produce ASCII-armoured output. This is equivalent to specifying
694 Produce a detached signature. This may be used to detach a signature
695 from an embedded message.
698 Produce a signature with embedded message. This may be used to
699 reattach a message to its detached signature.
701 .BI "\-f, \-\-format-in " format
702 Read input encoded according to
705 .BI "\-F, \-\-format-out " format
706 Produce output encoded according to
709 .BI "\-m, \-\-message " file
716 then write the message to standard output. Don't send the message and
717 signature to the same place because it doesn't work.
719 .BI "\-o, \-\-output " file
720 Write the signature to
726 option is given, a signature is written to standard output.
730 command encodes an input file according to one of the encodings
733 The input is read from the
735 given on the command line, or from standard input if none is specified.
736 Options provided are:
738 .BI "\-f, \-\-format " format
743 for a list of encoding formats.
745 .BI "\-b, \-\-boundary " label
746 Set the PEM boundary string to
748 i.e., assuming we're encoding in PEM format, the output will have
749 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
751 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
752 at the bottom. The default
757 .BI "\-p, \-\-progress"
758 Write a progress meter to standard error while processing large files.
760 .BI "\-o, \-\-output " file
763 instead of to standard output.
767 command decodes an input file encoded according to one of the encodings
770 The input is read from the
772 given on the command line, or from standard input if none is specified.
773 Options provided are:
775 .BI "\-f, \-\-format " format
780 for a list of encoding formats.
782 .BI "\-b, \-\-boundary " label
783 Set the PEM boundary string to
785 i.e., assuming we're encoding in PEM format, start processing input
787 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
789 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
790 lines. Without this option,
792 will start reading at the first plausible boundary string, and continue
793 processing until it reaches the matching end boundary.
795 .BI "\-p, \-\-progress"
796 Write a progress meter to standard error while processing large files.
798 .BI "\-o, \-\-output " file
801 instead of to standard output.
803 The trailing-whitespace deletion doesn't work for more than 32K of
804 whitespace. I don't think this is a big problem, really.
808 command does something unhelpful if message and signature are sent to
817 Mark Wooding, <mdw@distorted.org.uk>
~mdw / catacomb / blob