22 \h'-\w'\\$1\ 'u'\\$1\ \c
27 .TH dsig 1 "30 September 2004" "Straylight/Edgeware" "Catacomb cryptographic library"
29 dsig \- compute and verify signatures on collections of files
67 command signs and verifies signatures on a collection of files. It
68 provides a number of subcommands, by which the various operations may be
71 Before the command name,
73 may be given. The following global options are supported:
75 .BR "\-h, \-\-help " [ \fIcommand ...]
76 Writes a brief summary of
78 various options to standard output, and returns a successful exit
79 status. With command names, gives help on those commands.
82 Writes the program's version number to standard output, and returns a
83 successful exit status.
86 Writes a very terse command line summary to standard output, and returns
87 a successful exit status.
89 .BI "\-k, \-\-keyring " file
90 Names the keyring file which
92 is to process. The default keyring, used if this option doesn't specify
93 one, is the file named
95 in the current directory. See
99 for more details about keyring files.
109 attribute is present on the key, then it must have this form; otherwise,
110 the key's type must have the form
113 Algorithm selections are taken from appropriately-named attributes, or,
114 failing that, from the
117 The signature algorithm is chosen according to the setting of
121 for a list of supported signature algorithms.
124 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
125 RFC3447; the difference is that the hash is left bare rather than being
126 wrapped in a DER-encoded
128 structure. This doesn't affect security since the key can only be used
129 with the one hash function anyway, and dropping the DER wrapping permits
130 rapid adoption of new hash functions. Regardless, use of this algorithm
131 is not recommended, since the padding method has been shown vulnerable
141 This is the RSASSA-PSS algorithm described in RFC3447. It is the
142 preferred RSA-based signature scheme. Use the
151 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
160 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
170 This is the revised KCDSA (Korean Certificate-based Digital Signature
171 Algorithm) described in
172 .I The Revised Version of KCDSA
173 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
185 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
194 As well as the signature algorithm itself, a hash function is used.
195 This is taken from the
197 attribute on the key, or, failing that, from the
201 or, if that is absent, determined by the signature algorithm as follows.
209 the default hash function is
216 the default hash function is
221 for a list of supported hash functions.
222 .SH "COMMAND REFERENCE"
226 command behaves exactly as the
228 option. With no arguments, it shows an overview of
230 options; with arguments, it describes the named subcommands.
234 command prints various lists of tokens understood by
236 With no arguments, it prints all of the lists; with arguments, it prints
237 just the named lists, in order. The recognized lists can be enumerated
242 command. The lists are as follows.
245 The lists which can be enumerated by the
250 The signature algorithms which can be used in a key's
255 The hash functions which can be used in a key's
261 command creates a signature for a collection of files. The default
262 behaviour is to read a list of whitespace-separated file names (see
263 below for the precise format) from standard input and write the
264 an output file, containing hashes of the files and a digital signature
267 in the current keyring, to standard output, in plain text with binary
268 values Base64-encoded. It is intended to be used in conjunction with
270 This behaviour can be modified by specifying command-line options.
273 Read null-terminated filenames, rather than whitespace-separated names.
274 This is the recommended mode of operation if you have a
276 which understands the
281 Produce output in raw binary rather than the textual output. This isn't
282 a useful thing to do unless you're trying to debug
285 .B "\-v, \-\-verbose"
288 more verbose. At present, this just means that it'll print the hashes
289 of files that it comes across in hex. (Use
291 if this is the output you actually wanted.)
298 .BI "\-c, \-\-comment " string
301 as a comment in the output file. The comment's integrity is protected
304 .BI "\-f, \-\-file " name
307 instead of from standard input.
309 .BI "\-o, \-\-output " name
312 instead of to standard output.
314 .BI "\-k, \-\-key " tag
317 rather than the default
320 .BI "\-e, \-\-expire " date
321 Set the signature to expire at
323 The default is to expire 28 days from creation. Use
325 to make the signature not expire.
327 .B "\-C, \-\-nocheck"
328 Don't check the private key for validity. This makes signing go much
329 faster, but at the risk of using a duff key, and potentially leaking
330 information about the private key.
332 The whitespace-separated format for filenames allows quoting and
333 escaping of strange characters. The backslash
335 can be used to escape whitespace, quotes, or other special characters
336 (including itself), and to represent special characters using the
337 standard C escape sequences
345 A filename can be quoted in
350 Whitespace within quotes is part of the filename. The quotes must be at
351 the beginning and end of the name.
355 command will verify signatures made by the
357 command. With no arguments, it expects to read a text-format signature
358 file from standard input; with an argument, it examines the file it
359 names to see whether it's text or binary.
361 Command-line options provided are:
363 .B "\-v, \-\-verbose"
364 Produce more informational output. The default verbosity level is 1.
367 Produce less information output.
369 .B "\-C, \-\-nocheck"
370 Don't check the public key for validity. This makes verification go
371 much faster, but at the risk of using a duff key, and potentially
372 accepting false signatures.
374 Output is written to standard output in a machine-readable format.
375 Formatting errors cause the program to write a diagnostic to standard
376 error and exit nonzero as usual. Lines begin with a keyword:
379 An error prevented verification.
382 The signature is bad: some file had the wrong hash or the signature is
387 encountered a situation which may or may not invalidate the signature.
390 The signature verified correctly.
393 Any other information.
395 The information written at the various verbosity levels is as follows.
397 No output. Watch the exit status.
399 exits zero if the signature was good.
406 messages are printed.
410 messages are printed describing reasons why the signature verification
413 message is printed showing the signature file's comment if any.
417 messages are shown listing the signing program's identification string,
418 the signing key, the signature and expiry dates, and actual signature
423 messages are printed for each file covered, showing its name and hash.
425 There are two output formats: textual and binary. The hash used in the
426 digital signature is always computed on the
428 version of the data, regardless of the external representation.
430 Within the file, whitespace and comments between strings are ignored. A
431 comment begins with a hash
433 and extends until the next newline.
435 Strings are either quoted or whitespace-delimited. A string may be
441 The end-quote character can be backslash-escaped within the string. An
442 occurrence of the unescaped end-quote character terminates the string.
443 A whitespace-delimited string is terminated by any unescaped whitespace
444 character. The C-language escape sequences
452 are recognized within either kind of string.
454 Blocks within the file consist of sequences of strings. The first
457 \(en a simple string ending in a colon
459 \(en which describes the format of the remaining strings.
461 The file consists of a sequence of blocks, each of which begins with a
462 tag byte. The format of the test of the block depends on the tag.
463 Strings are null-terminated; all integers are in network byte order.
465 A binary file always begins with an ident block, which has a tag of 0.
467 The following block types are known. They must appear in the order
468 given, and except where noted must appear exactly once each.
471 Identification string of the generating program.
473 The signing key's id, as eight hex digits (text) or a 32-bit integer
477 The comment string set with the
481 command. This block need not appear.
484 The date the signature was made. In a text file, this has the form
488 in a binary file, it's a 64-bit integer representing the POSIX time.
491 The expiry time of the signature, expressed as for
493 A non-expiring signature is represented by the string
495 in text files, or all-bits-set in binary.
498 A file hash. In text, this is two strings which are the Base-64-encoded
499 hash and the file name; in binary, this is a 16-bit hash length, the raw
500 hash, and the null-terminated filename. There can be any number of
504 .BR "signature: " (6)
505 The signature. In text, this is the Base-64-encoded signature; in
506 binary, it is a 16-bit length followed by the binary signature.
508 The signature covers the
510 representations of the file's
523 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob