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
307 for a list of supported hash functions.
309 Two encodings for the ciphertext are supported.
312 The raw format, which has the benefit of being smaller, but needs to be
313 attached to mail messages and generally handled with care.
316 PEM-encapsulated Base-64 encoded text. This format can be included
317 directly in email and picked out again automatically; but there is a
318 4-to-3 data expansion as a result.
319 .SH "SIGNATURE FORMATS"
320 There are two basic signature formats understood by
323 Embedded signatures include (embed) the message they sign; hence they're
324 complete in and of themselves. The
326 program extracts the message during signature verification.
328 Detached signatures are separate from the messages they sign, and both
329 the original file and the signature are required for a successful
332 Another important distinction is whether the message data is considered
333 to be plain text or raw binary data.
335 When dealing with plain text,
337 allows a limited quantity of leeway in the messages it processes. It
338 ignores trailing whitespace on a line, including stray carriage-returns,
339 which may appear if Windows boxes have had their way with the data. It
340 also appends a final newline if there wasn't one before. In embedded
341 signatures, the text is left unencoded, so that the message is readable.
343 Binary files are preserved completely, and no variation whatever is
350 command can convert between detached and embedded signatures; it cannot
351 convert between binary and text mode signatures. (The data actually
352 signed includes a flag saying whether the message is textual. The
353 rationale here is that what looks like an ASCII space before a newline
354 may be devastatingly significant in a binary data file, and if a message
355 is signed as raw binary then no changes whatever should be allowed.)
356 .SH "COMMAND REFERENCE"
360 command behaves exactly as the
362 option. With no arguments, it shows an overview of
364 options; with arguments, it describes the named subcommands.
368 command prints various lists of tokens understood by
370 With no arguments, it prints all of the lists; with arguments, it prints
371 just the named lists, in order. The recognized lists can be enumerated
376 command. The lists are as follows.
379 The lists which can be enumerated by the
384 The signature algorithms which can be used in a signing key's
389 The hash functions which can be used in a key's
394 The encodings which can be applied to encrypted messages; see
400 command signs a message and writes out an appropriately-encoded
401 signature. By default, it reads a message from standard input and
402 writes the signature to standard output. If a filename argument is
403 given, this file is read instead.
405 The following options are recognized.
408 Produce ASCII-armoured output. This is equivalent to specifying
415 Read and sign the input as binary data. The default is to treat the
419 Produce a detached signature. The default is to produce a signature
420 with embedded message.
422 .BI "\-f, \-\-format " format
423 Produce output encoded according to
426 .BI "\-k, \-\-key " tag
427 Use the signing key named
429 in the current keyring; the default key is
432 .BI "\-o, \-\-ouptut " file
435 rather than to standard output.
437 .BI "\-p, \-\-progress"
438 Write a progress meter to standard error while processing large files.
441 Read and sign the input as text. This is the default.
443 .B "\-C, \-\-nocheck"
444 Don't check the private key for validity. This makes signing go much
445 faster, but at the risk of using a duff key, and potentially leaking
446 information about the private key.
450 command checks a signature's validity, producing as output information
451 about the signature and the signed message.
453 The first non-option argument is the name of the file containing the
454 signature data; this may be omitted or
456 to indicate that the signature be read from standard input. The second
457 non-option argument, if any, is the name of the file to read the message
458 from, if the signature is detached. An error is reported if a message
459 file is specified but the signature contains an embedded message
460 already; if the signature is detached but no filename is given, then the
461 message is expected on stdin (immediately after the signature, if any).
464 Read ASCII-armoured input. This is equivalent to specifying
471 Buffer the message until the signature is verified. This is forced on
472 if output is to stdout, but is always available as an option.
474 .BI "\-f, \-\-format " format
475 Read input encoded according to
478 .B "\-v, \-\-verbose"
479 Produce more verbose messages. See below for the messages produced
480 during decryption. The default verbosity level is 1. (Currently this
481 is the most verbose setting. This might not be the case always.)
483 .BI "\-p, \-\-progress"
484 Write a progress meter to standard error while processing large files.
487 Produce fewer messages.
489 .BI "\-k, \-\-key " tag
492 uses the signature header to work out which key to use to verify a
493 signature. Using this option causes verification to fail unless the
494 signature header specifies the key named
497 .BI "\-t, \-\-freshtime " time
498 Only accept signatures claiming to have been made more recently than
504 (the default) then any timestamp in the past is acceptable.
507 Show the datestamp in the signature in UTC rather than (your) local
512 .BI "\-o, \-\-output " file
513 Write the verified message to
515 The file is written in text or binary
516 mode as appropriate. The default is to write the message to standard
517 output unless verifying a detached signature, in which case nothing is
520 .B "\-C, \-\-nocheck"
521 Don't check the public key for validity. This makes verification go
522 much faster, but at the risk of using a duff key, and potentially
523 accepting false signatures.
525 Output is written to standard output in a machine-readable format.
526 Major problems cause the program to write a diagnostic to standard error
527 and exit nonzero as usual. The quantity of output varies depending on
528 the verbosity level and whether the message is also being written to
529 standard output. Output lines begin with a keyword:
532 An error prevented verification. The program will exit nonzero.
536 encountered a situation which may or may not invalidate the
540 Verification was successful. This is only produced if the message is
541 being sent somewhere other than standard output.
544 The message follows, starting just after the next newline character or
545 sequence. This is only produced if the message is being written to
549 Any other information.
551 The information written at the various verbosity levels is as follows.
553 No output. Watch the exit status.
560 option is set (which happens automatically if writing to standard
565 checked for authenticity until it has all been written. Even with
567 output can fail midway for many reasons, and the resulting message may
568 therefore be truncated. Don't rely on the output being complete until
576 command analyses a signature without verifying it, and prints
577 interesting information about it. This might be useful for diagnostic
578 purposes. No keys are needed for this operation, though you get more
579 useful information if you have them.
581 If a non-option argument is given, and it is not
583 then it is taken to name the file containing the signature to parse;
584 otherwise a signature is read from standard input.
586 The following options are recognized.
589 Read ASCII-armoured input. This is equivalent to specifying
595 .BI "\-f, \-\-format " format
596 Read input encoded according to
599 .BI "\-p, \-\-progress"
600 Write a progress meter to standard error while processing large files.
603 Show the datestamp in the signature in UTC rather than (your) local
608 A description of the signature block is produced on standard output; it
609 is mostly machine-readable. The first word on each line explains what
610 kind of output it is.
613 The signature data is invalid and cannot be parsed.
616 Something is wrong with the data, but isn't fatal.
619 An environmental problem means that the information isn't as helpful as
620 it might be. For example, the keyring file can't be opened, so we don't
621 know whether the verification key is there.
623 .BI "INFO flags " flags
624 Describes the flags set in the signature header. The
626 are a list of flags, one per word, preceded by a
628 if the flag is clear.
630 .BI "INFO expected-flags " flags
631 If the PEM boundary string didn't match the actual signature data then
632 this line is output, listing the expected flags and their settings.
633 Problems with boundary mismatches can be resolved using the
637 .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz
638 Signature was (allegedly!) made at the given time and date. If the
640 option was given, this will be in UTC.
643 Signature was (allegedly!) made using the key
645 which is present in the current keyring.
647 .BI "INFO unknown-key " keyid
648 Signature was (allegedly!) made using the key with id
650 which is not in the current keyring (or the keyring wasn't found).
654 command translates signatures between the various supported formats.
655 This is a (slightly) more complex operation than re-encoding, though it
656 does not require any cryptographic operations.
658 The first non-option argument is the name of the file containing the
659 signature data; this may be omitted or
661 to indicate that the signature be read from standard input. The second
662 non-option argument, if any, is the name of the file to read the message
663 from, if the signature is detached. An error is reported if a message
664 file is specified but the signature contains an embedded message
665 already; if the signature is detached but no filename is given, then the
666 message is expected on stdin (immediately after the signature, if any).
668 The options follow a rough convention: options describing the input
669 format are lower-case and options specifying the output format are
670 upper-case. The following options are recognized.
672 .BI "\-a, \-\-armour-in"
673 Read ASCII-armoured input. This is equivalent to specifying
679 .BI "\-p, \-\-progress"
680 Write a progress meter to standard error while processing large files.
682 .BI "\-A, \-\-armour-out"
683 Produce ASCII-armoured output. This is equivalent to specifying
690 Produce a detached signature. This may be used to detach a signature
691 from an embedded message.
694 Produce a signature with embedded message. This may be used to
695 reattach a message to its detached signature.
697 .BI "\-f, \-\-format-in " format
698 Read input encoded according to
701 .BI "\-F, \-\-format-out " format
702 Produce output encoded according to
705 .BI "\-m, \-\-message " file
712 then write the message to standard output. Don't send the message and
713 signature to the same place because it doesn't work.
715 .BI "\-o, \-\-output " file
716 Write the signature to
722 option is given, a signature is written to standard output.
726 command encodes an input file according to one of the encodings
729 The input is read from the
731 given on the command line, or from standard input if none is specified.
732 Options provided are:
734 .BI "\-f, \-\-format " format
739 for a list of encoding formats.
741 .BI "\-b, \-\-boundary " label
742 Set the PEM boundary string to
744 i.e., assuming we're encoding in PEM format, the output will have
745 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
747 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
748 at the bottom. The default
753 .BI "\-p, \-\-progress"
754 Write a progress meter to standard error while processing large files.
756 .BI "\-o, \-\-output " file
759 instead of to standard output.
763 command decodes an input file encoded according to one of the encodings
766 The input is read from the
768 given on the command line, or from standard input if none is specified.
769 Options provided are:
771 .BI "\-f, \-\-format " format
776 for a list of encoding formats.
778 .BI "\-b, \-\-boundary " label
779 Set the PEM boundary string to
781 i.e., assuming we're encoding in PEM format, start processing input
783 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
785 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
786 lines. Without this option,
788 will start reading at the first plausible boundary string, and continue
789 processing until it reaches the matching end boundary.
791 .BI "\-p, \-\-progress"
792 Write a progress meter to standard error while processing large files.
794 .BI "\-o, \-\-output " file
797 instead of to standard output.
799 The trailing-whitespace deletion doesn't work for more than 32K of
800 whitespace. I don't think this is a big problem, really.
804 command does something unhelpful if message and signature are sent to
813 Mark Wooding, <mdw@distorted.org.uk>
~mdw / catacomb / blob