+++ /dev/null
-.\" -*-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 [ \-pqvjC ]
-.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
-.B "\-j, \-\-junk"
-Report files whose hashes have not been checked.
-.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 "JUNK " type " " name
-The file
-.I name
-was found (as a result of the search requested by the
-.RB ` \-j '
-option), but it was not mentioned in the signature file and therefore
-has not been checked.
-.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>
projects / u / mdw / catacomb / blobdiff