factorial: Fix usage message to fit in with conventions.

[u/mdw/catacomb] / catsign.1

.\" -*-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 [ \-adtC ]
.RB [ \-k
.IR tag ]
.RB [ \-f
.IR format ]
.RB [ \-o
.IR output ]
.RI [ file ]
.br
.B verify
.RB [ \-aquvC ]
.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 [ \-auABDET ]
.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 [ \-f
.IR format ]
.RB [ \-b
.IR boundary ]
.RB [ \-o
.IR output ]
.RI [ file ]
.br
.B decode
.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.
.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
.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
.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
.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 "\-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 "\-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 "\-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>