Hash utilities: maintain a hash state object, not a bundle of arguments.

[u/mdw/catacomb] / dsig.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 dsig 1 "30 September 2004" "Straylight/Edgeware" "Catacomb cryptographic library"
.SH NAME
dsig \- compute and verify signatures on collections of files
.SH SYNOPSIS
.B dsig
.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 [ \-0bpqvC ]
.RB [ \-c
.IR comment ]
.RB [ \-k
.IR tag ]
.RB [ \-e
.IR expire ]
.br
\h'8n'
.RB [ \-f
.IR file ]
.RB [ \-h
.IR file ]
.RB [ \-o
.IR output ]
.br
.B verify
.RB [ \-pqvC ]
.RI [ file ]
.SH DESCRIPTION
The
.B dsig
command signs and verifies signatures on a collection of files.  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 dsig '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"
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 dsig- \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 dsig 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 dsig show hash
for a list of supported hash functions.
.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 dsig 's
options; with arguments, it describes the named subcommands.
.SS show
The
.B show
command prints various lists of tokens understood by
.BR dsig .
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
dsig 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 key's
.B sig
attribute.
.TP
.B hash
The hash functions which can be used in a key's
.B hash
attribute.
.SS sign
The
.B sign
command creates a signature for a collection of files.  The default
behaviour is to read a list of whitespace-separated file names (see
below for the precise format) from standard input and write the
an output file, containing hashes of the files and a digital signature
made by the key
.B dsig
in the current keyring, to standard output, in plain text with binary
values Base64-encoded.  It is intended to be used in conjunction with
.BR find (1).
This behaviour can be modified by specifying command-line options.
.TP
.B "\-0, \-\-null"
Read null-terminated filenames, rather than whitespace-separated names.
This is the recommended mode of operation if you have a
.BR find (1)
which understands the
.B \-print0
option.
.TP
.B "\-b, \-\-binary"
Produce output in raw binary rather than the textual output.  This isn't
a useful thing to do unless you're trying to debug
.BR dsig .
.TP
.B "\-v, \-\-verbose"
Makes
.B dsig
more verbose.  At present, this just means that it'll print the hashes
of files that it comes across in hex.  (Use
.BR hashsum (1)
if this is the output you actually wanted.)
.TP
.B "\-q, \-\-quiet"
Makes
.B dsig
less verbose.
.TP
.BI "\-c, \-\-comment " string
Writes
.I string
as a comment in the output file.  The comment's integrity is protected
by the signature.
.TP
.BI "\-p, \-\-progress"
Write a progress meter to standard error while processing large files.
.TP
.BI "\-f, \-\-file " name
Read filenames from
.I name
instead of from standard input.
.TP
.BI "\-h, \-\-hashes " name
Rather than hashing files, read precomputed hashes from the file
.IR name ,
which should be in the format produced by
.BR hashsum (1).
.TP
.BI "\-o, \-\-output " name
Write output to
.I name
instead of to standard output.
.TP
.BI "\-k, \-\-key " tag
Use the key named
.I tag
rather than the default
.BR dsig .
.TP
.BI "\-e, \-\-expire " date
Set the signature to expire at
.IR date .
The default is to expire 28 days from creation.  Use
.B forever
to make the signature not expire.
.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.
.PP
The whitespace-separated format for filenames allows quoting and
escaping of strange characters.  The backslash
.RB ` \e '
can be used to escape whitespace, quotes, or other special characters
(including itself), and to represent special characters using the
standard C escape sequences
.RB ` \ea ',
.RB ` \eb ',
.RB ` \ef ',
.RB ` \en ',
.RB ` \et ',
and
.RB ` \eb '.
A filename can be quoted in
.BR ` ... ',
.BR ' ... '
or
.BR """" ... """".
Whitespace within quotes is part of the filename.  The quotes must be at
the beginning and end of the name.
.SS verify
The
.B verify
command will verify signatures made by the
.B sign
command.  With no arguments, it expects to read a text-format signature
file from standard input; with an argument, it examines the file it
names to see whether it's text or binary.
.PP
Command-line options provided are:
.TP
.B "\-v, \-\-verbose"
Produce more informational output.  The default verbosity level is 1.
.TP
.B "\-q, \-\-quiet"
Produce less information output.
.TP
.BI "\-p, \-\-progress"
Write a progress meter to standard error while processing large files.
.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.
Formatting errors cause the program to write a diagnostic to standard
error and exit nonzero as usual.  Lines begin with a keyword:
.TP
.BI "FAIL " reason
An error prevented verification.
.TP
.BI "BAD " reason
The signature is bad: some file had the wrong hash or the signature is
invalid.
.TP
.BI "WARN " reason
.B dsig
encountered a situation which may or may not invalidate the signature.
.TP
.BI "OK " message
The signature verified correctly.
.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.
.B dsig
exits zero if the signature was good.
.hP 1.
All
.BR OK ,
.B FAIL
and
.B WARN
messages are printed.
.hP 2.
As for level 1; also
.B BAD
messages are printed describing reasons why the signature verification
failed, and an
.B INFO
message is printed showing the signature file's comment if any.
.hP 3.
As for level 2; also
.B INFO
messages are shown listing the signing program's identification string,
the signing key, the signature and expiry dates, and actual signature
verification.
.hP 4.
As for level 3; also
.B INFO
messages are printed for each file covered, showing its name and hash.
.SH "OUTPUT FORMAT"
There are two output formats: textual and binary.  The hash used in the
digital signature is always computed on the
.I binary
version of the data, regardless of the external representation.
.SS "Textual format"
Within the file, whitespace and comments between strings are ignored.  A
comment begins with a hash
.RB (` # ')
and extends until the next newline.
.PP
Strings are either quoted or whitespace-delimited.  A string may be
quoted by
.BR ` ... ',
.BR ' ... '
or
.BR """" ... """".
The end-quote character can be backslash-escaped within the string.  An
occurrence of the unescaped end-quote character terminates the string.
A whitespace-delimited string is terminated by any unescaped whitespace
character.  The C-language escape sequences
.RB ` \ea ',
.RB ` \eb ',
.RB ` \ef ',
.RB ` \en ',
.RB ` \et ',
and
.RB ` \eb '
are recognized within either kind of string.
.PP
Blocks within the file consist of sequences of strings.  The first
string is a
.I tag
\(en a simple string ending in a colon
.RB (` : ')
\(en which describes the format of the remaining strings.
.SS "Binary format"
The file consists of a sequence of blocks, each of which begins with a
tag byte.  The format of the test of the block depends on the tag.
Strings are null-terminated; all integers are in network byte order.
.PP
A binary file always begins with an ident block, which has a tag of 0.
.SS "Block types"
The following block types are known.  They must appear in the order
given, and except where noted must appear exactly once each.
.TP
.BR "ident: " (0)
Identification string of the generating program.
.BR "keyid: " (1)
The signing key's id, as eight hex digits (text) or a 32-bit integer
(binary).
.TP
.BR "comment: " (2)
The comment string set with the
.B \-c
option to the
.B sign
command.  This block need not appear.
.TP
.BR "date: " (3)
The date the signature was made.  In a text file, this has the form
.IB yyyy-mm-dd
.IB hh:mm:ss
.IR timezone ;
in a binary file, it's a 64-bit integer representing the POSIX time.
.TP
.BR "expires: " (4)
The expiry time of the signature, expressed as for
.BR date: .
A non-expiring signature is represented by the string
.B forever
in text files, or all-bits-set in binary.
.TP
.BR "file: " (5)
A file hash.  In text, this is two strings which are the Base-64-encoded
hash and the file name; in binary, this is a 16-bit hash length, the raw
hash, and the null-terminated filename.  There can be any number of
.B file:
blocks.
.TP
.BR "signature: " (6)
The signature.  In text, this is the Base-64-encoded signature; in
binary, it is a 16-bit length followed by the binary signature.
.PP
The signature covers the
.I binary
representations of the file's
.BR date: ,
.B expires:
and
.B file:
blocks.
.SH "SEE ALSO"
.BR key (1),
.BR hashsum (1),
.BR catcrypt (1),
.BR catsign (1),
.BR keyring (5).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>