X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/5032daf4a16aebc784968e8d052dbe4233f88bfe..c65df27983057ec76ed0e72bb370f9a5ae7dad28:/dsig.1

diff --git a/dsig.1 b/dsig.1
new file mode 100644
index 0000000..0d7c83b
--- /dev/null
+++ b/dsig.1
@@ -0,0 +1,512 @@
+.\" -*-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 [ \-0bqv ]
+.RB [ \-c
+.IR comment ]
+.RB [ \-k
+.IR tag ]
+.RB [ \-e
+.IR expire ]
+.br
+\h'8n'
+.RB [ \-f
+.IR file ]
+.RB [ \-o
+.IR output ]
+.br
+.B verify
+.RB [ \-qv ]
+.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 "\-f, \-\-file " name
+Read filenames from
+.I name
+instead of from standard input.
+.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.
+.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.
+.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 keyring (5).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>