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 is Bernstein, Duif, Lange, Schwabe, and Yang's EdDSA algorithm,
267 using Hamburg's Ed448-Goldilocks elliptic curve,
268 as specified in RFC8032.
269 More specifically, this is HashEd448
272 algorithm \(en by default
284 This uses a symmetric message-authentication algorithm rather than a
285 digital signature. The precise message-authentication scheme used is
288 attribute on the key, which defaults to
290 if unspecified. Use the
298 As well as the signature algorithm itself, a hash function is used.
299 This is taken from the
301 attribute on the key, or, failing that, from the
305 or, if that is absent, determined by the signature algorithm as follows.
313 the default hash function is
320 the default hash function is
324 the default hash function is
328 the default hash function is
333 for a list of supported hash functions.
335 Two encodings for the ciphertext are supported.
338 The raw format, which has the benefit of being smaller, but needs to be
339 attached to mail messages and generally handled with care.
342 PEM-encapsulated Base-64 encoded text. This format can be included
343 directly in email and picked out again automatically; but there is a
344 4-to-3 data expansion as a result.
345 .SH "SIGNATURE FORMATS"
346 There are two basic signature formats understood by
349 Embedded signatures include (embed) the message they sign; hence they're
350 complete in and of themselves. The
352 program extracts the message during signature verification.
354 Detached signatures are separate from the messages they sign, and both
355 the original file and the signature are required for a successful
358 Another important distinction is whether the message data is considered
359 to be plain text or raw binary data.
361 When dealing with plain text,
363 allows a limited quantity of leeway in the messages it processes. It
364 ignores trailing whitespace on a line, including stray carriage-returns,
365 which may appear if Windows boxes have had their way with the data. It
366 also appends a final newline if there wasn't one before. In embedded
367 signatures, the text is left unencoded, so that the message is readable.
369 Binary files are preserved completely, and no variation whatever is
376 command can convert between detached and embedded signatures; it cannot
377 convert between binary and text mode signatures. (The data actually
378 signed includes a flag saying whether the message is textual. The
379 rationale here is that what looks like an ASCII space before a newline
380 may be devastatingly significant in a binary data file, and if a message
381 is signed as raw binary then no changes whatever should be allowed.)
382 .SH "COMMAND REFERENCE"
386 command behaves exactly as the
388 option. With no arguments, it shows an overview of
390 options; with arguments, it describes the named subcommands.
394 command prints various lists of tokens understood by
396 With no arguments, it prints all of the lists; with arguments, it prints
397 just the named lists, in order. The recognized lists can be enumerated
402 command. The lists are as follows.
405 The lists which can be enumerated by the
410 The signature algorithms which can be used in a signing key's
415 The hash functions which can be used in a key's
420 The encodings which can be applied to encrypted messages; see
426 command signs a message and writes out an appropriately-encoded
427 signature. By default, it reads a message from standard input and
428 writes the signature to standard output. If a filename argument is
429 given, this file is read instead.
431 The following options are recognized.
434 Produce ASCII-armoured output. This is equivalent to specifying
441 Read and sign the input as binary data. The default is to treat the
445 Produce a detached signature. The default is to produce a signature
446 with embedded message.
448 .BI "\-f, \-\-format " format
449 Produce output encoded according to
452 .BI "\-k, \-\-key " tag
453 Use the signing key named
455 in the current keyring; the default key is
458 .BI "\-o, \-\-ouptut " file
461 rather than to standard output.
463 .BI "\-p, \-\-progress"
464 Write a progress meter to standard error while processing large files.
467 Read and sign the input as text. This is the default.
469 .B "\-C, \-\-nocheck"
470 Don't check the private key for validity. This makes signing go much
471 faster, but at the risk of using a duff key, and potentially leaking
472 information about the private key.
476 command checks a signature's validity, producing as output information
477 about the signature and the signed message.
479 The first non-option argument is the name of the file containing the
480 signature data; this may be omitted or
482 to indicate that the signature be read from standard input. The second
483 non-option argument, if any, is the name of the file to read the message
484 from, if the signature is detached. An error is reported if a message
485 file is specified but the signature contains an embedded message
486 already; if the signature is detached but no filename is given, then the
487 message is expected on stdin (immediately after the signature, if any).
490 Read ASCII-armoured input. This is equivalent to specifying
497 Buffer the message until the signature is verified. This is forced on
498 if output is to stdout, but is always available as an option.
500 .BI "\-f, \-\-format " format
501 Read input encoded according to
504 .B "\-v, \-\-verbose"
505 Produce more verbose messages. See below for the messages produced
506 during decryption. The default verbosity level is 1. (Currently this
507 is the most verbose setting. This might not be the case always.)
509 .BI "\-p, \-\-progress"
510 Write a progress meter to standard error while processing large files.
513 Produce fewer messages.
515 .BI "\-k, \-\-key " tag
518 uses the signature header to work out which key to use to verify a
519 signature. Using this option causes verification to fail unless the
520 signature header specifies the key named
523 .BI "\-t, \-\-freshtime " time
524 Only accept signatures claiming to have been made more recently than
530 (the default) then any timestamp in the past is acceptable.
533 Show the datestamp in the signature in UTC rather than (your) local
538 .BI "\-o, \-\-output " file
539 Write the verified message to
541 The file is written in text or binary
542 mode as appropriate. The default is to write the message to standard
543 output unless verifying a detached signature, in which case nothing is
546 .B "\-C, \-\-nocheck"
547 Don't check the public key for validity. This makes verification go
548 much faster, but at the risk of using a duff key, and potentially
549 accepting false signatures.
551 Output is written to standard output in a machine-readable format.
552 Major problems cause the program to write a diagnostic to standard error
553 and exit nonzero as usual. The quantity of output varies depending on
554 the verbosity level and whether the message is also being written to
555 standard output. Output lines begin with a keyword:
558 An error prevented verification. The program will exit nonzero.
562 encountered a situation which may or may not invalidate the
566 Verification was successful. This is only produced if the message is
567 being sent somewhere other than standard output.
570 The message follows, starting just after the next newline character or
571 sequence. This is only produced if the message is being written to
575 Any other information.
577 The information written at the various verbosity levels is as follows.
579 No output. Watch the exit status.
586 option is set (which happens automatically if writing to standard
591 checked for authenticity until it has all been written. Even with
593 output can fail midway for many reasons, and the resulting message may
594 therefore be truncated. Don't rely on the output being complete until
602 command analyses a signature without verifying it, and prints
603 interesting information about it. This might be useful for diagnostic
604 purposes. No keys are needed for this operation, though you get more
605 useful information if you have them.
607 If a non-option argument is given, and it is not
609 then it is taken to name the file containing the signature to parse;
610 otherwise a signature is read from standard input.
612 The following options are recognized.
615 Read ASCII-armoured input. This is equivalent to specifying
621 .BI "\-f, \-\-format " format
622 Read input encoded according to
625 .BI "\-p, \-\-progress"
626 Write a progress meter to standard error while processing large files.
629 Show the datestamp in the signature in UTC rather than (your) local
634 A description of the signature block is produced on standard output; it
635 is mostly machine-readable. The first word on each line explains what
636 kind of output it is.
639 The signature data is invalid and cannot be parsed.
642 Something is wrong with the data, but isn't fatal.
645 An environmental problem means that the information isn't as helpful as
646 it might be. For example, the keyring file can't be opened, so we don't
647 know whether the verification key is there.
649 .BI "INFO flags " flags
650 Describes the flags set in the signature header. The
652 are a list of flags, one per word, preceded by a
654 if the flag is clear.
656 .BI "INFO expected-flags " flags
657 If the PEM boundary string didn't match the actual signature data then
658 this line is output, listing the expected flags and their settings.
659 Problems with boundary mismatches can be resolved using the
663 .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz
664 Signature was (allegedly!) made at the given time and date. If the
666 option was given, this will be in UTC.
669 Signature was (allegedly!) made using the key
671 which is present in the current keyring.
673 .BI "INFO unknown-key " keyid
674 Signature was (allegedly!) made using the key with id
676 which is not in the current keyring (or the keyring wasn't found).
680 command translates signatures between the various supported formats.
681 This is a (slightly) more complex operation than re-encoding, though it
682 does not require any cryptographic operations.
684 The first non-option argument is the name of the file containing the
685 signature data; this may be omitted or
687 to indicate that the signature be read from standard input. The second
688 non-option argument, if any, is the name of the file to read the message
689 from, if the signature is detached. An error is reported if a message
690 file is specified but the signature contains an embedded message
691 already; if the signature is detached but no filename is given, then the
692 message is expected on stdin (immediately after the signature, if any).
694 The options follow a rough convention: options describing the input
695 format are lower-case and options specifying the output format are
696 upper-case. The following options are recognized.
698 .BI "\-a, \-\-armour-in"
699 Read ASCII-armoured input. This is equivalent to specifying
705 .BI "\-p, \-\-progress"
706 Write a progress meter to standard error while processing large files.
708 .BI "\-A, \-\-armour-out"
709 Produce ASCII-armoured output. This is equivalent to specifying
716 Produce a detached signature. This may be used to detach a signature
717 from an embedded message.
720 Produce a signature with embedded message. This may be used to
721 reattach a message to its detached signature.
723 .BI "\-f, \-\-format-in " format
724 Read input encoded according to
727 .BI "\-F, \-\-format-out " format
728 Produce output encoded according to
731 .BI "\-m, \-\-message " file
738 then write the message to standard output. Don't send the message and
739 signature to the same place because it doesn't work.
741 .BI "\-o, \-\-output " file
742 Write the signature to
748 option is given, a signature is written to standard output.
752 command encodes an input file according to one of the encodings
755 The input is read from the
757 given on the command line, or from standard input if none is specified.
758 Options provided are:
760 .BI "\-f, \-\-format " format
765 for a list of encoding formats.
767 .BI "\-b, \-\-boundary " label
768 Set the PEM boundary string to
770 i.e., assuming we're encoding in PEM format, the output will have
771 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
773 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
774 at the bottom. The default
779 .BI "\-p, \-\-progress"
780 Write a progress meter to standard error while processing large files.
782 .BI "\-o, \-\-output " file
785 instead of to standard output.
789 command decodes an input file encoded according to one of the encodings
792 The input is read from the
794 given on the command line, or from standard input if none is specified.
795 Options provided are:
797 .BI "\-f, \-\-format " format
802 for a list of encoding formats.
804 .BI "\-b, \-\-boundary " label
805 Set the PEM boundary string to
807 i.e., assuming we're encoding in PEM format, start processing input
809 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
811 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
812 lines. Without this option,
814 will start reading at the first plausible boundary string, and continue
815 processing until it reaches the matching end boundary.
817 .BI "\-p, \-\-progress"
818 Write a progress meter to standard error while processing large files.
820 .BI "\-o, \-\-output " file
823 instead of to standard output.
825 The trailing-whitespace deletion doesn't work for more than 32K of
826 whitespace. I don't think this is a big problem, really.
830 command does something unhelpful if message and signature are sent to
839 Mark Wooding, <mdw@distorted.org.uk>
~mdw / catacomb / blob