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
112 command signs and verifies messages. It also works as a simple PEM
113 encoder and decoder. It provides a number of subcommands, by which the
114 various operations may be carried out.
116 Before the command name,
118 may be given. The following global options are supported:
120 .BR "\-h, \-\-help " [ \fIcommand ...]
121 Writes a brief summary of
123 various options to standard output, and returns a successful exit
124 status. With command names, gives help on those commands.
126 .B "\-v, \-\-version"
127 Writes the program's version number to standard output, and returns a
128 successful exit status.
131 Writes a very terse command line summary to standard output, and returns
132 a successful exit status.
134 .BI "\-k, \-\-keyring " file
135 Names the keyring file which
137 is to process. The default keyring, used if this option doesn't specify
138 one, is the file named
140 in the current directory. See
144 for more details about keyring files.
146 Algorithms to be used with a particular key are described by attributes
147 on the key, or its type. The
149 command deals with signing keys. (Note that
151 uses signing keys in the same way as
162 attribute is present on the key, then it must have this form; otherwise,
163 the key's type must have the form
166 Algorithm selections are taken from appropriately-named attributes, or,
167 failing that, from the
170 The signature algorithm is chosen according to the setting of
174 for a list of supported signature algorithms.
177 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
178 RFC3447; the difference is that the hash is left bare rather than being
179 wrapped in a DER-encoded
181 structure. This doesn't affect security since the key can only be used
182 with the one hash function anyway, and dropping the DER wrapping permits
183 rapid adoption of new hash functions. Regardless, use of this algorithm
184 is not recommended, since the padding method has been shown vulnerable
194 This is the RSASSA-PSS algorithm described in RFC3447. It is the
195 preferred RSA-based signature scheme. Use the
204 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
213 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
223 This is the revised KCDSA (Korean Certificate-based Digital Signature
224 Algorithm) described in
225 .I The Revised Version of KCDSA
226 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
238 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
248 This uses a symmetric message-authentication algorithm rather than a
249 digital signature. The precise message-authentication scheme used is
252 attribute on the key, which defaults to
254 if unspecified. Use the
262 As well as the signature algorithm itself, a hash function is used.
263 This is taken from the
265 attribute on the key, or, failing that, from the
269 or, if that is absent, determined by the signature algorithm as follows.
277 the default hash function is
284 the default hash function is
289 for a list of supported hash functions.
291 Two encodings for the ciphertext are supported.
294 The raw format, which has the benefit of being smaller, but needs to be
295 attached to mail messages and generally handled with care.
298 PEM-encapsulated Base-64 encoded text. This format can be included
299 directly in email and picked out again automatically; but there is a
300 4-to-3 data expansion as a result.
301 .SH "SIGNATURE FORMATS"
302 There are two basic signature formats understood by
305 Embedded signatures include (embed) the message they sign; hence they're
306 complete in and of themselves. The
308 program extracts the message during signature verification.
310 Detached signatures are separate from the messages they sign, and both
311 the original file and the signature are required for a successful
314 Another important distinction is whether the message data is considered
315 to be plain text or raw binary data.
317 When dealing with plain text,
319 allows a limited quantity of leeway in the messages it processes. It
320 ignores trailing whitespace on a line, including stray carriage-returns,
321 which may appear if Windows boxes have had their way with the data. It
322 also appends a final newline if there wasn't one before. In embedded
323 signatures, the text is left unencoded, so that the message is readable.
325 Binary files are preserved completely, and no variation whatever is
332 command can convert between detached and embedded signatures; it cannot
333 convert between binary and text mode signatures. (The data actually
334 signed includes a flag saying whether the message is textual. The
335 rationale here is that what looks like an ASCII space before a newline
336 may be devastatingly significant in a binary data file, and if a message
337 is signed as raw binary then no changes whatever should be allowed.)
338 .SH "COMMAND REFERENCE"
342 command behaves exactly as the
344 option. With no arguments, it shows an overview of
346 options; with arguments, it describes the named subcommands.
350 command prints various lists of tokens understood by
352 With no arguments, it prints all of the lists; with arguments, it prints
353 just the named lists, in order. The recognized lists can be enumerated
358 command. The lists are as follows.
361 The lists which can be enumerated by the
366 The signature algorithms which can be used in a signing key's
371 The hash functions which can be used in a key's
376 The encodings which can be applied to encrypted messages; see
382 command signs a message and writes out an appropriately-encoded
383 signature. By default, it reads a message from standard input and
384 writes the signature to standard output. If a filename argument is
385 given, this file is read instead.
387 The following options are recognized.
390 Produce ASCII-armoured output. This is equivalent to specifying
397 Read and sign the input as binary data. The default is to treat the
401 Produce a detached signature. The default is to produce a signature
402 with embedded message.
404 .BI "\-f, \-\-format " format
405 Produce output encoded according to
408 .BI "\-k, \-\-key " tag
409 Use the signing key named
411 in the current keyring; the default key is
414 .BI "\-o, \-\-ouptut " file
417 rather than to standard output.
420 Read and sign the input as text. This is the default.
422 .B "\-C, \-\-nocheck"
423 Don't check the private key for validity. This makes signing go much
424 faster, but at the risk of using a duff key, and potentially leaking
425 information about the private key.
429 command checks a signature's validity, producing as output information
430 about the signature and the signed message.
432 The first non-option argument is the name of the file containing the
433 signature data; this may be omitted or
435 to indicate that the signature be read from standard input. The second
436 non-option argument, if any, is the name of the file to read the message
437 from, if the signature is detached. An error is reported if a message
438 file is specified but the signature contains an embedded message
439 already; if the signature is detached but no filename is given, then the
440 message is expected on stdin (immediately after the signature, if any).
443 Read ASCII-armoured input. This is equivalent to specifying
450 Buffer the message until the signature is verified. This is forced on
451 if output is to stdout, but is always available as an option.
453 .BI "\-f, \-\-format " format
454 Read input encoded according to
457 .B "\-v, \-\-verbose"
458 Produce more verbose messages. See below for the messages produced
459 during decryption. The default verbosity level is 1. (Currently this
460 is the most verbose setting. This might not be the case always.)
463 Produce fewer messages.
465 .BI "\-k, \-\-key " tag
468 uses the signature header to work out which key to use to verify a
469 signature. Using this option causes verification to fail unless the
470 signature header specifies the key named
473 .BI "\-t, \-\-freshtime " time
474 Only accept signatures claiming to have been made more recently than
480 (the default) then any timestamp in the past is acceptable.
483 Show the datestamp in the signature in UTC rather than (your) local
488 .BI "\-o, \-\-output " file
489 Write the verified message to
491 The file is written in text or binary
492 mode as appropriate. The default is to write the message to standard
493 output unless verifying a detached signature, in which case nothing is
496 .B "\-C, \-\-nocheck"
497 Don't check the public key for validity. This makes verification go
498 much faster, but at the risk of using a duff key, and potentially
499 accepting false signatures.
501 Output is written to standard output in a machine-readable format.
502 Major problems cause the program to write a diagnostic to standard error
503 and exit nonzero as usual. The quantity of output varies depending on
504 the verbosity level and whether the message is also being written to
505 standard output. Output lines begin with a keyword:
508 An error prevented verification. The program will exit nonzero.
512 encountered a situation which may or may not invalidate the
516 Verification was successful. This is only produced if the message is
517 being sent somewhere other than standard output.
520 The message follows, starting just after the next newline character or
521 sequence. This is only produced if the message is being written to
525 Any other information.
527 The information written at the various verbosity levels is as follows.
529 No output. Watch the exit status.
534 All output written has been checked for authenticity. However, output
535 can fail madway through for many reasons, and the resulting message may
536 therefore be truncated. Don't rely on the output being complete until
544 command analyses a signature without verifying it, and prints
545 interesting information about it. This might be useful for diagnostic
546 purposes. No keys are needed for this operation, though you get more
547 useful information if you have them.
549 If a non-option argument is given, and it is not
551 then it is taken to name the file containing the signature to parse;
552 otherwise a signature is read from standard input.
554 The following options are recognized.
557 Read ASCII-armoured input. This is equivalent to specifying
563 .BI "\-f, \-\-format " format
564 Read input encoded according to
568 Show the datestamp in the signature in UTC rather than (your) local
573 A description of the signature block is produced on standard output; it
574 is mostly machine-readable. The first word on each line explains what
575 kind of output it is.
578 The signature data is invalid and cannot be parsed.
581 Something is wrong with the data, but isn't fatal.
584 An environmental problem means that the information isn't as helpful as
585 it might be. For example, the keyring file can't be opened, so we don't
586 know whether the verification key is there.
588 .BI "INFO flags " flags
589 Describes the flags set in the signature header. The
591 are a list of flags, one per word, preceded by a
593 if the flag is clear.
595 .BI "INFO expected-flags " flags
596 If the PEM boundary string didn't match the actual signature data then
597 this line is output, listing the expected flags and their settings.
598 Problems with boundary mismatches can be resolved using the
602 .BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz
603 Signature was (allegedly!) made at the given time and date. If the
605 option was given, this will be in UTC.
608 Signature was (allegedly!) made using the key
610 which is present in the current keyring.
612 .BI "INFO unknown-key " keyid
613 Signature was (allegedly!) made using the key with id
615 which is not in the current keyring (or the keyring wasn't found).
619 command translates signatures between the various supported formats.
620 This is a (slightly) more complex operation than re-encoding, though it
621 does not require any cryptographic operations.
623 The first non-option argument is the name of the file containing the
624 signature data; this may be omitted or
626 to indicate that the signature be read from standard input. The second
627 non-option argument, if any, is the name of the file to read the message
628 from, if the signature is detached. An error is reported if a message
629 file is specified but the signature contains an embedded message
630 already; if the signature is detached but no filename is given, then the
631 message is expected on stdin (immediately after the signature, if any).
633 The options follow a rough convention: options describing the input
634 format are lower-case and options specifying the output format are
635 upper-case. The following options are recognized.
637 .BI "\-a, \-\-armour-in"
638 Read ASCII-armoured input. This is equivalent to specifying
644 .BI "\-A, \-\-armour-out"
645 Produce ASCII-armoured output. This is equivalent to specifying
652 Produce a detached signature. This may be used to detach a signature
653 from an embedded message.
656 Produce a signature with embedded message. This may be used to
657 reattach a message to its detached signature.
659 .BI "\-f, \-\-format-in " format
660 Read input encoded according to
663 .BI "\-F, \-\-format-out " format
664 Produce output encoded according to
667 .BI "\-m, \-\-message " file
674 then write the message to standard output. Don't send the message and
675 signature to the same place because it doesn't work.
677 .BI "\-o, \-\-output " file
678 Write the signature to
684 option is given, a signature is written to standard output.
688 command encodes an input file according to one of the encodings
691 The input is read from the
693 given on the command line, or from standard input if none is specified.
694 Options provided are:
696 .BI "\-f, \-\-format " format
701 for a list of encoding formats.
703 .BI "\-b, \-\-boundary " label
704 Set the PEM boundary string to
706 i.e., assuming we're encoding in PEM format, the output will have
707 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
709 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
710 at the bottom. The default
715 .BI "\-o, \-\-output " file
718 instead of to standard output.
722 command decodes an input file encoded according to one of the encodings
725 The input is read from the
727 given on the command line, or from standard input if none is specified.
728 Options provided are:
730 .BI "\-f, \-\-format " format
735 for a list of encoding formats.
737 .BI "\-b, \-\-boundary " label
738 Set the PEM boundary string to
740 i.e., assuming we're encoding in PEM format, start processing input
742 .BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
744 .BI "\-\-\-\-\-END " label "\-\-\-\-\-"
745 lines. Without this option,
747 will start reading at the first plausible boundary string, and continue
748 processing until it reaches the matching end boundary.
750 .BI "\-o, \-\-output " file
753 instead of to standard output.
755 The trailing-whitespace deletion doesn't work for more than 32K of
756 whitespace. I don't think this is a big problem, really.
760 command does something unhelpful if message and signature are sent to
769 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob