X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/progs/catsign.1

diff --git a/progs/catsign.1 b/progs/catsign.1
new file mode 100644
index 0000000..190c631
--- /dev/null
+++ b/progs/catsign.1
@@ -0,0 +1,789 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.ie t \{\
+.  if \n(.g \{\
+.    fam P
+.  \}
+.\}
+.de hP
+.IP
+.ft B
+\h'-\w'\\$1\ 'u'\\$1\ \c
+.ft P
+..
+.ie t .ds o \(bu
+.el .ds o o
+.TH catsign 1 "17 March 2005" "Straylight/Edgeware" "Catacomb cryptographic library"
+.SH NAME
+catsign \- sign and verify messages
+.SH SYNOPSIS
+.B catsign
+.RB [ \-k
+.IR keyring ]
+.I command
+.PP
+where
+.I command
+is one of:
+.PP
+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br
+.B sign
+.RB [ \-adptC ]
+.RB [ \-k
+.IR tag ]
+.RB [ \-f
+.IR format ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.br
+.B verify
+.RB [ \-apquvC ]
+.RB [ \-k
+.IR tag ]
+.RB [ \-f
+.IR format ]
+.RB [ \-t
+.IR time ]
+.br
+
+.RB [ \-o
+.IR output ]
+.RI [ file
+.RI [ message ]]
+.br
+.B info
+.RB [ \-a ]
+.RB [ \-f
+.IR format ]
+.RI [ file ]
+.br
+.B format
+.RB [ \-apuABDET ]
+.RB [ \-f
+.IR format ]
+.RB [ \-F
+.IR format ]
+.br
+
+.RB [ \-m
+.IR file ]
+.RB [ \-o
+.IR output ]
+.RI [ file
+.RI [ message ]]
+.br
+.B encode
+.RB [ \-p ]
+.RB [ \-f
+.IR format ]
+.RB [ \-b
+.IR boundary ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.br
+.B decode
+.RB [ \-p ]
+.RB [ \-f
+.IR format ]
+.RB [ \-b
+.IR boundary ]
+.RB [ \-o
+.IR output ]
+.RI [ file ]
+.SH "DESCRIPTION"
+The
+.B catsign
+command signs and verifies messages.  It also works as a simple PEM
+encoder and decoder.  It provides a number of subcommands, by which the
+various operations may be carried out.
+.SS "Global options"
+Before the command name,
+.I "global options"
+may be given.  The following global options are supported:
+.TP
+.BR "\-h, \-\-help " [ \fIcommand ...]
+Writes a brief summary of
+.BR catsign 's
+various options to standard output, and returns a successful exit
+status.  With command names, gives help on those commands.
+.TP
+.B "\-v, \-\-version"
+Writes the program's version number to standard output, and returns a
+successful exit status.
+.TP
+.B "\-u, \-\-usage"
+Writes a very terse command line summary to standard output, and returns
+a successful exit status.
+.TP
+.BI "\-k, \-\-keyring " file
+Names the keyring file which
+.B key
+is to process.  The default keyring, used if this option doesn't specify
+one, is the file named
+.B keyring
+in the current directory.  See
+.BR key (1)
+and
+.BR keyring (5)
+for more details about keyring files.
+.SH "KEY SETUP"
+Algorithms to be used with a particular key are described by attributes
+on the key, or its type.  The
+.B catsign
+command deals with signing keys.  (Note that
+.B catsign
+uses signing keys in the same way as
+.BR catcrypt (1).)
+.PP
+A
+.I sigalgspec
+has the form
+.IR sig \c
+.RB [ / \c
+.IR hash ].
+If a
+.B sig
+attribute is present on the key, then it must have this form; otherwise,
+the key's type must have the form
+.BI ccsig- \c
+.IR sigalgspec .
+Algorithm selections are taken from appropriately-named attributes, or,
+failing that, from the
+.IR sigalgspec .
+.PP
+The signature algorithm is chosen according to the setting of
+.I sig
+as follows.  Run
+.B catsign show sig
+for a list of supported signature algorithms.
+.TP
+.B rsapkcs1
+This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
+RFC3447; the difference is that the hash is left bare rather than being
+wrapped in a DER-encoded
+.B DigestInfo
+structure.  This doesn't affect security since the key can only be used
+with the one hash function anyway, and dropping the DER wrapping permits
+rapid adoption of new hash functions.  Regardless, use of this algorithm
+is not recommended, since the padding method has been shown vulnerable
+to attack.  Use the
+.B rsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B rsapss
+This is the RSASSA-PSS algorithm described in RFC3447.  It is the
+preferred RSA-based signature scheme.  Use the
+.B rsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B dsa
+This is the DSA algorithm described in FIPS180-1 and FIPS180-2.  Use the
+.B dsa
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B ecdsa
+This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2.  Use
+the
+.B ec
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B kcdsa
+This is the revised KCDSA (Korean Certificate-based Digital Signature
+Algorithm) described in
+.I The Revised Version of KCDSA
+.RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
+Use the
+.B dh
+algorithm of the
+.B key add
+command with the
+.B \-LS
+options (see
+.BR key (1))
+to generate the key.
+.TP
+.B eckcdsa
+This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
+Use the
+.B ec
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.TP
+.B mac
+This uses a symmetric message-authentication algorithm rather than a
+digital signature.  The precise message-authentication scheme used is
+determined by the
+.B mac
+attribute on the key, which defaults to
+.IB hash -hmac
+if unspecified.  Use the
+.B binary
+algorithm of the
+.B key add
+command (see
+.BR key (1))
+to generate the key.
+.PP
+As well as the signature algorithm itself, a hash function is used.
+This is taken from the
+.B hash
+attribute on the key, or, failing that, from the
+.I hash
+specified in the
+.IR sigalgspec ,
+or, if that is absent, determined by the signature algorithm as follows.
+.hP \*o
+For
+.BR rsapkcs1 ,
+.BR rsapss ,
+.BR dsa ,
+and
+.BR ecdsa ,
+the default hash function is
+.BR sha .
+.hP \*o
+For
+.BR kcdsa
+and
+.BR eckcdsa ,
+the default hash function is
+.BR has160 .
+.PP
+Run
+.B catsign show hash
+for a list of supported hash functions.
+.SH "ENCODINGS"
+Two encodings for the ciphertext are supported.
+.TP
+.B binary
+The raw format, which has the benefit of being smaller, but needs to be
+attached to mail messages and generally handled with care.
+.TP
+.B pem
+PEM-encapsulated Base-64 encoded text.  This format can be included
+directly in email and picked out again automatically; but there is a
+4-to-3 data expansion as a result.
+.SH "SIGNATURE FORMATS"
+There are two basic signature formats understood by
+.BR catsign .
+.hP \*o
+Embedded signatures include (embed) the message they sign; hence they're
+complete in and of themselves.  The
+.B catsign
+program extracts the message during signature verification.
+.hP \*o
+Detached signatures are separate from the messages they sign, and both
+the original file and the signature are required for a successful
+verification.
+.PP
+Another important distinction is whether the message data is considered
+to be plain text or raw binary data.
+.hP \*o
+When dealing with plain text,
+.B catsign
+allows a limited quantity of leeway in the messages it processes.  It
+ignores trailing whitespace on a line, including stray carriage-returns,
+which may appear if Windows boxes have had their way with the data.  It
+also appends a final newline if there wasn't one before.  In embedded
+signatures, the text is left unencoded, so that the message is readable.
+.hP \*o
+Binary files are preserved completely, and no variation whatever is
+permitted.
+.PP
+The
+.VS
+catsign format
+.VE
+command can convert between detached and embedded signatures; it cannot
+convert between binary and text mode signatures.  (The data actually
+signed includes a flag saying whether the message is textual.  The
+rationale here is that what looks like an ASCII space before a newline
+may be devastatingly significant in a binary data file, and if a message
+is signed as raw binary then no changes whatever should be allowed.)
+.SH "COMMAND REFERENCE"
+.SS help
+The
+.B help
+command behaves exactly as the
+.B \-\-help
+option.  With no arguments, it shows an overview of
+.BR catsign 's
+options; with arguments, it describes the named subcommands.
+.SS show
+The
+.B show
+command prints various lists of tokens understood by
+.BR catsign .
+With no arguments, it prints all of the lists; with arguments, it prints
+just the named lists, in order.  The recognized lists can be enumerated
+using the
+.VS
+catsign show list
+.VE
+command.  The lists are as follows.
+.TP
+.B list
+The lists which can be enumerated by the
+.B show
+command.
+.TP
+.B sig
+The signature algorithms which can be used in a signing key's
+.B sig
+attribute.
+.TP
+.B hash
+The hash functions which can be used in a key's
+.B hash
+attribute.
+.TP
+.B enc
+The encodings which can be applied to encrypted messages; see
+.B ENCODINGS
+above.
+.SS sign
+The
+.B sign
+command signs a message and writes out an appropriately-encoded
+signature.  By default, it reads a message from standard input and
+writes the signature to standard output.  If a filename argument is
+given, this file is read instead.
+.PP
+The following options are recognized.
+.TP
+.B "\-a, \-\-armour"
+Produce ASCII-armoured output.  This is equivalent to specifying
+.BR "\-f pem" .
+The variant spelling
+.B "\-\-armor"
+is also accepted.
+.TP
+.B "\-b, \-\-binary"
+Read and sign the input as binary data.  The default is to treat the
+input as text.
+.TP
+.B "\-d, \-\-detach"
+Produce a detached signature.  The default is to produce a signature
+with embedded message.
+.TP
+.BI "\-f, \-\-format " format
+Produce output encoded according to
+.IR format .
+.TP
+.BI "\-k, \-\-key " tag
+Use the signing key named
+.I tag
+in the current keyring; the default key is
+.BR ccsig .
+.TP
+.BI "\-o, \-\-ouptut " file
+Write output to
+.I file
+rather than to standard output.
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.B "\-t, \-\-text"
+Read and sign the input as text.  This is the default.
+.TP
+.B "\-C, \-\-nocheck"
+Don't check the private key for validity.  This makes signing go much
+faster, but at the risk of using a duff key, and potentially leaking
+information about the private key.
+.SS verify
+The
+.B verify
+command checks a signature's validity, producing as output information
+about the signature and the signed message.
+.PP
+The first non-option argument is the name of the file containing the
+signature data; this may be omitted or
+.RB ` \- '
+to indicate that the signature be read from standard input.  The second
+non-option argument, if any, is the name of the file to read the message
+from, if the signature is detached.  An error is reported if a message
+file is specified but the signature contains an embedded message
+already; if the signature is detached but no filename is given, then the
+message is expected on stdin (immediately after the signature, if any).
+.TP
+.B "\-a, \-\-armour"
+Read ASCII-armoured input.  This is equivalent to specifying
+.BR "\-f pem" .
+The variant spelling
+.B "\-\-armor"
+is also accepted.
+.TP
+.B "\-b, \-\-buffer"
+Buffer the message until the signature is verified.  This is forced on
+if output is to stdout, but is always available as an option.
+.TP
+.BI "\-f, \-\-format " format
+Read input encoded according to
+.IR format .
+.TP
+.B "\-v, \-\-verbose"
+Produce more verbose messages.  See below for the messages produced
+during decryption.  The default verbosity level is 1.  (Currently this
+is the most verbose setting.  This might not be the case always.)
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.B "\-q, \-\-quiet"
+Produce fewer messages.
+.TP
+.BI "\-k, \-\-key " tag
+Usually
+.B catsign
+uses the signature header to work out which key to use to verify a
+signature.  Using this option causes verification to fail unless the
+signature header specifies the key named
+.IR tag .
+.TP
+.BI "\-t, \-\-freshtime " time
+Only accept signatures claiming to have been made more recently than
+.IR time .
+If
+.I time
+is
+.B always
+(the default) then any timestamp in the past is acceptable.
+.TP
+.B "\-u, \-\-utc"
+Show the datestamp in the signature in UTC rather than (your) local
+time.  The synonym
+.B \-\-gmt
+is also accepted.
+.TP
+.BI "\-o, \-\-output " file
+Write the verified message to
+.IR file .
+The file is written in text or binary
+mode as appropriate.  The default is to write the message to standard
+output unless verifying a detached signature, in which case nothing is
+written.
+.TP
+.B "\-C, \-\-nocheck"
+Don't check the public key for validity.  This makes verification go
+much faster, but at the risk of using a duff key, and potentially
+accepting false signatures.
+.PP
+Output is written to standard output in a machine-readable format.
+Major problems cause the program to write a diagnostic to standard error
+and exit nonzero as usual.  The quantity of output varies depending on
+the verbosity level and whether the message is also being written to
+standard output.  Output lines begin with a keyword:
+.TP
+.BI "FAIL " reason
+An error prevented verification.  The program will exit nonzero.
+.TP
+.BI "WARN " reason
+.B catsign
+encountered a situation which may or may not invalidate the
+verification.
+.TP
+.BI "OK " message
+Verification was successful.  This is only produced if the message is
+being sent somewhere other than standard output.
+.TP
+.B "DATA"
+The message follows, starting just after the next newline character or
+sequence.  This is only produced if the message is being written to
+standard output.
+.TP
+.BI "INFO " note
+Any other information.
+.PP
+The information written at the various verbosity levels is as follows.
+.hP 0.
+No output.  Watch the exit status.
+.hP 1.
+All messages.
+.PP
+.B Warning!
+All output written has been checked for authenticity.  However, output
+can fail madway through for many reasons, and the resulting message may
+therefore be truncated.  Don't rely on the output being complete until
+.B OK
+is printed or
+.B catsign verify
+exits successfully.
+.SS info
+The
+.B info
+command analyses a signature without verifying it, and prints
+interesting information about it.  This might be useful for diagnostic
+purposes.  No keys are needed for this operation, though you get more
+useful information if you have them.
+.PP
+If a non-option argument is given, and it is not
+.RB ` \- ',
+then it is taken to name the file containing the signature to parse;
+otherwise a signature is read from standard input.
+.PP
+The following options are recognized.
+.TP
+.B "\-a, \-\-armour"
+Read ASCII-armoured input.  This is equivalent to specifying
+.BR "\-f pem" .
+The variant spelling
+.B "\-\-armor"
+is also accepted.
+.TP
+.BI "\-f, \-\-format " format
+Read input encoded according to
+.IR format .
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.B "\-u, \-\-utc"
+Show the datestamp in the signature in UTC rather than (your) local
+time.  The synonym
+.B \-\-gmt
+is also accepted.
+.PP
+A description of the signature block is produced on standard output; it
+is mostly machine-readable.  The first word on each line explains what
+kind of output it is.
+.TP
+.BI "BAD " message
+The signature data is invalid and cannot be parsed.
+.TP
+.BI "WARN " message
+Something is wrong with the data, but isn't fatal.
+.TP
+.BI "NOTE " message
+An environmental problem means that the information isn't as helpful as
+it might be.  For example, the keyring file can't be opened, so we don't
+know whether the verification key is there.
+.TP
+.BI "INFO flags " flags
+Describes the flags set in the signature header.  The
+.I flags
+are a list of flags, one per word, preceded by a
+.RB ` ! '
+if the flag is clear.
+.TP
+.BI "INFO expected-flags " flags
+If the PEM boundary string didn't match the actual signature data then
+this line is output, listing the expected flags and their settings.
+Problems with boundary mismatches can be resolved using the
+.B format
+command.
+.TP
+.BI "INFO date " yyyy "\-" mm "\-" dd " " hh ":" mm ":" ss " " tz
+Signature was (allegedly!) made at the given time and date.  If the
+.B \-u
+option was given, this will be in UTC.
+.TP
+.BI "INFO key " tag
+Signature was (allegedly!) made using the key
+.IR tag ,
+which is present in the current keyring.
+.TP
+.BI "INFO unknown-key " keyid
+Signature was (allegedly!) made using the key with id
+.IR keyid
+which is not in the current keyring (or the keyring wasn't found).
+.SS format
+The
+.B format
+command translates signatures between the various supported formats.
+This is a (slightly) more complex operation than re-encoding, though it
+does not require any cryptographic operations.
+.PP
+The first non-option argument is the name of the file containing the
+signature data; this may be omitted or
+.RB ` \- '
+to indicate that the signature be read from standard input.  The second
+non-option argument, if any, is the name of the file to read the message
+from, if the signature is detached.  An error is reported if a message
+file is specified but the signature contains an embedded message
+already; if the signature is detached but no filename is given, then the
+message is expected on stdin (immediately after the signature, if any).
+.PP
+The options follow a rough convention: options describing the input
+format are lower-case and options specifying the output format are
+upper-case.  The following options are recognized.
+.TP
+.BI "\-a, \-\-armour-in"
+Read ASCII-armoured input.  This is equivalent to specifying
+.BR "\-f pem" .
+The variant spelling
+.B "\-\-armor"
+is also accepted.
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.BI "\-A, \-\-armour-out"
+Produce ASCII-armoured output.  This is equivalent to specifying
+.BR "\-F pem" .
+The variant spelling
+.B "\-\-armor-out"
+is also accepted.
+.TP
+.B "\-D, \-\-detach"
+Produce a detached signature.  This may be used to detach a signature
+from an embedded message.
+.TP
+.B "\-E, \-\-embed"
+Produce a signature with embedded message.  This may be used to
+reattach a message to its detached signature.
+.TP
+.BI "\-f, \-\-format-in " format
+Read input encoded according to
+.IR format .
+.TP
+.BI "\-F, \-\-format-out " format
+Produce output encoded according to
+.IR format .
+.TP
+.BI "\-m, \-\-message " file
+Write the message to
+.IR file .
+If
+.I file
+is
+.RB ` \- '
+then write the message to standard output.  Don't send the message and
+signature to the same place because it doesn't work.
+.TP
+.BI "\-o, \-\-output " file
+Write the signature to
+.IR file .
+If no
+.B \-m
+or
+.B \-o
+option is given, a signature is written to standard output.
+.SS "encode"
+The
+.B encode
+command encodes an input file according to one of the encodings
+described above in
+.BR ENCODINGS .
+The input is read from the
+.I file
+given on the command line, or from standard input if none is specified.
+Options provided are:
+.TP
+.BI "\-f, \-\-format " format
+Produce output in
+.IR format .
+Run
+.B catsign show enc
+for a list of encoding formats.
+.TP
+.BI "\-b, \-\-boundary " label
+Set the PEM boundary string to
+.IR label ;
+i.e., assuming we're encoding in PEM format, the output will have
+.BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
+at the top and
+.BI "\-\-\-\-\-END " label "\-\-\-\-\-"
+at the bottom.  The default
+.I label
+is
+.BR MESSAGE .
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.BI "\-o, \-\-output " file
+Write output to
+.I file
+instead of to standard output.
+.SS "decode"
+The
+.B decode
+command decodes an input file encoded according to one of the encodings
+described above in
+.BR ENCODINGS .
+The input is read from the
+.I file
+given on the command line, or from standard input if none is specified.
+Options provided are:
+.TP
+.BI "\-f, \-\-format " format
+Decode input in
+.IR format .
+Run
+.B catsign show enc
+for a list of encoding formats.
+.TP
+.BI "\-b, \-\-boundary " label
+Set the PEM boundary string to
+.IR label ;
+i.e., assuming we're encoding in PEM format, start processing input
+between
+.BI "\-\-\-\-\-BEGIN " label "\-\-\-\-\-"
+and
+.BI "\-\-\-\-\-END " label "\-\-\-\-\-"
+lines.  Without this option,
+.B catsign
+will start reading at the first plausible boundary string, and continue
+processing until it reaches the matching end boundary.
+.TP
+.BI "\-p, \-\-progress"
+Write a progress meter to standard error while processing large files.
+.TP
+.BI "\-o, \-\-output " file
+Write output to
+.I file
+instead of to standard output.
+.SH "BUGS"
+The trailing-whitespace deletion doesn't work for more than 32K of
+whitespace.  I don't think this is a big problem, really.
+.PP
+The
+.B format
+command does something unhelpful if message and signature are sent to
+the same file.
+.SH "SEE ALSO"
+.BR key (1),
+.BR catcrypt (1),
+.BR dsig (1),
+.BR hashsum (1),
+.BR keyring (5).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>