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
69 command signs and verifies signatures on a collection of files. It
70 provides a number of subcommands, by which the various operations may be
73 Before the command name,
75 may be given. The following global options are supported:
77 .BR "\-h, \-\-help " [ \fIcommand ...]
78 Writes a brief summary of
80 various options to standard output, and returns a successful exit
81 status. With command names, gives help on those commands.
84 Writes the program's version number to standard output, and returns a
85 successful exit status.
88 Writes a very terse command line summary to standard output, and returns
89 a successful exit status.
91 .BI "\-k, \-\-keyring " file
92 Names the keyring file which
94 is to process. The default keyring, used if this option doesn't specify
95 one, is the file named
97 in the current directory. See
101 for more details about keyring files.
111 attribute is present on the key, then it must have this form; otherwise,
112 the key's type must have the form
115 Algorithm selections are taken from appropriately-named attributes, or,
116 failing that, from the
119 The signature algorithm is chosen according to the setting of
123 for a list of supported signature algorithms.
126 This is almost the same as the RSASSA-PKCS1-v1_5 algorithm described in
127 RFC3447; the difference is that the hash is left bare rather than being
128 wrapped in a DER-encoded
130 structure. This doesn't affect security since the key can only be used
131 with the one hash function anyway, and dropping the DER wrapping permits
132 rapid adoption of new hash functions. Regardless, use of this algorithm
133 is not recommended, since the padding method has been shown vulnerable
143 This is the RSASSA-PSS algorithm described in RFC3447. It is the
144 preferred RSA-based signature scheme. Use the
153 This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the
162 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use
172 This is the revised KCDSA (Korean Certificate-based Digital Signature
173 Algorithm) described in
174 .I The Revised Version of KCDSA
175 .RB ( http://dasan.sejong.ac.kr/~chlim/pub/kcdsa1.ps ).
187 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
197 This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm.
198 More specifically, this is HashEd25519
201 algorithm \(en by default
212 As well as the signature algorithm itself, a hash function is used.
213 This is taken from the
215 attribute on the key, or, failing that, from the
219 or, if that is absent, determined by the signature algorithm as follows.
227 the default hash function is
234 the default hash function is
238 the default hash function is
243 for a list of supported hash functions.
244 .SH "COMMAND REFERENCE"
248 command behaves exactly as the
250 option. With no arguments, it shows an overview of
252 options; with arguments, it describes the named subcommands.
256 command prints various lists of tokens understood by
258 With no arguments, it prints all of the lists; with arguments, it prints
259 just the named lists, in order. The recognized lists can be enumerated
264 command. The lists are as follows.
267 The lists which can be enumerated by the
272 The signature algorithms which can be used in a key's
277 The hash functions which can be used in a key's
283 command creates a signature for a collection of files. The default
284 behaviour is to read a list of whitespace-separated file names (see
285 below for the precise format) from standard input and write the
286 an output file, containing hashes of the files and a digital signature
289 in the current keyring, to standard output, in plain text with binary
290 values Base64-encoded. It is intended to be used in conjunction with
292 This behaviour can be modified by specifying command-line options.
295 Read null-terminated filenames, rather than whitespace-separated names.
296 This is the recommended mode of operation if you have a
298 which understands the
303 Produce output in raw binary rather than the textual output. This isn't
304 a useful thing to do unless you're trying to debug
307 .B "\-v, \-\-verbose"
310 more verbose. At present, this just means that it'll print the hashes
311 of files that it comes across in hex. (Use
313 if this is the output you actually wanted.)
320 .BI "\-c, \-\-comment " string
323 as a comment in the output file. The comment's integrity is protected
326 .BI "\-p, \-\-progress"
327 Write a progress meter to standard error while processing large files.
329 .BI "\-f, \-\-file " name
332 instead of from standard input.
334 .BI "\-h, \-\-hashes " name
335 Rather than hashing files, read precomputed hashes from the file
337 which should be in the format produced by
340 .BI "\-o, \-\-output " name
343 instead of to standard output.
345 .BI "\-k, \-\-key " tag
348 rather than the default
351 .BI "\-e, \-\-expire " date
352 Set the signature to expire at
354 The default is to expire 28 days from creation. Use
356 to make the signature not expire.
358 .B "\-C, \-\-nocheck"
359 Don't check the private key for validity. This makes signing go much
360 faster, but at the risk of using a duff key, and potentially leaking
361 information about the private key.
363 The whitespace-separated format for filenames allows quoting and
364 escaping of strange characters. The backslash
366 can be used to escape whitespace, quotes, or other special characters
367 (including itself), and to represent special characters using the
368 standard C escape sequences
376 A filename can be quoted in
381 Whitespace within quotes is part of the filename. The quotes must be at
382 the beginning and end of the name.
386 command will verify signatures made by the
388 command. With no arguments, it expects to read a text-format signature
389 file from standard input; with an argument, it examines the file it
390 names to see whether it's text or binary.
392 Command-line options provided are:
394 .B "\-v, \-\-verbose"
395 Produce more informational output. The default verbosity level is 1.
398 Produce less information output.
401 Report files whose hashes have not been checked.
403 .BI "\-p, \-\-progress"
404 Write a progress meter to standard error while processing large files.
406 .B "\-C, \-\-nocheck"
407 Don't check the public key for validity. This makes verification go
408 much faster, but at the risk of using a duff key, and potentially
409 accepting false signatures.
411 Output is written to standard output in a machine-readable format.
412 Formatting errors cause the program to write a diagnostic to standard
413 error and exit nonzero as usual. Lines begin with a keyword:
416 An error prevented verification.
419 The signature is bad: some file had the wrong hash or the signature is
424 encountered a situation which may or may not invalidate the signature.
427 The signature verified correctly.
429 .BI "JUNK " type " " name
432 was found (as a result of the search requested by the
434 option), but it was not mentioned in the signature file and therefore
435 has not been checked.
438 Any other information.
440 The information written at the various verbosity levels is as follows.
442 No output. Watch the exit status.
444 exits zero if the signature was good.
451 messages are printed.
455 messages are printed describing reasons why the signature verification
458 message is printed showing the signature file's comment if any.
462 messages are shown listing the signing program's identification string,
463 the signing key, the signature and expiry dates, and actual signature
468 messages are printed for each file covered, showing its name and hash.
470 There are two output formats: textual and binary. The hash used in the
471 digital signature is always computed on the
473 version of the data, regardless of the external representation.
475 Within the file, whitespace and comments between strings are ignored. A
476 comment begins with a hash
478 and extends until the next newline.
480 Strings are either quoted or whitespace-delimited. A string may be
486 The end-quote character can be backslash-escaped within the string. An
487 occurrence of the unescaped end-quote character terminates the string.
488 A whitespace-delimited string is terminated by any unescaped whitespace
489 character. The C-language escape sequences
497 are recognized within either kind of string.
499 Blocks within the file consist of sequences of strings. The first
502 \(en a simple string ending in a colon
504 \(en which describes the format of the remaining strings.
506 The file consists of a sequence of blocks, each of which begins with a
507 tag byte. The format of the test of the block depends on the tag.
508 Strings are null-terminated; all integers are in network byte order.
510 A binary file always begins with an ident block, which has a tag of 0.
512 The following block types are known. They must appear in the order
513 given, and except where noted must appear exactly once each.
516 Identification string of the generating program.
518 The signing key's id, as eight hex digits (text) or a 32-bit integer
522 The comment string set with the
526 command. This block need not appear.
529 The date the signature was made. In a text file, this has the form
533 in a binary file, it's a 64-bit integer representing the POSIX time.
536 The expiry time of the signature, expressed as for
538 A non-expiring signature is represented by the string
540 in text files, or all-bits-set in binary.
543 A file hash. In text, this is two strings which are the Base-64-encoded
544 hash and the file name; in binary, this is a 16-bit hash length, the raw
545 hash, and the null-terminated filename. There can be any number of
549 .BR "signature: " (6)
550 The signature. In text, this is the Base-64-encoded signature; in
551 binary, it is a 16-bit length followed by the binary signature.
553 The signature covers the
555 representations of the file's
568 Mark Wooding, <mdw@distorted.org.uk>
~mdw / catacomb / blob