chiark / gitweb /
Merge branch '2.3.x'
[catacomb] / progs / dsig.1
1 .\" -*-nroff-*-
2 .de VS
3 .sp 1
4 .RS
5 .nf
6 .ft B
7 ..
8 .de VE
9 .ft R
10 .fi
11 .RE
12 .sp 1
13 ..
14 .ie t \{\
15 .  if \n(.g \{\
16 .    fam P
17 .  \}
18 .\}
19 .de hP
20 .IP
21 .ft B
22 \h'-\w'\\$1\ 'u'\\$1\ \c
23 .ft P
24 ..
25 .ie t .ds o \(bu
26 .el .ds o o
27 .TH dsig 1 "30 September 2004" "Straylight/Edgeware" "Catacomb cryptographic library"
28 .SH NAME
29 dsig \- compute and verify signatures on collections of files
30 .SH SYNOPSIS
31 .B dsig
32 .RB [ \-k
33 .IR keyring ]
34 .I command
35 .PP
36 where
37 .I command
38 is one of:
39 .PP
40 .B help
41 .RI [ command ...]
42 .br
43 .B show
44 .RI [ item ...]
45 .br
46 .B sign
47 .RB [ \-0bpqvC ]
48 .RB [ \-c
49 .IR comment ]
50 .RB [ \-k
51 .IR tag ]
52 .RB [ \-e
53 .IR expire ]
54 .br
55 \h'8n'
56 .RB [ \-f
57 .IR file ]
58 .RB [ \-h
59 .IR file ]
60 .RB [ \-o
61 .IR output ]
62 .br
63 .B verify
64 .RB [ \-pqvjC ]
65 .RI [ file ]
66 .SH DESCRIPTION
67 The
68 .B dsig
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
71 carried out.
72 .SS "Global options"
73 Before the command name,
74 .I "global options"
75 may be given.  The following global options are supported:
76 .TP
77 .BR "\-h, \-\-help " [ \fIcommand ...]
78 Writes a brief summary of
79 .BR dsig 's
80 various options to standard output, and returns a successful exit
81 status.  With command names, gives help on those commands.
82 .TP
83 .B "\-v, \-\-version"
84 Writes the program's version number to standard output, and returns a
85 successful exit status.
86 .TP
87 .B "\-u, \-\-usage"
88 Writes a very terse command line summary to standard output, and returns
89 a successful exit status.
90 .TP
91 .BI "\-k, \-\-keyring " file
92 Names the keyring file which
93 .B key
94 is to process.  The default keyring, used if this option doesn't specify
95 one, is the file named
96 .B keyring
97 in the current directory.  See
98 .BR key (1)
99 and
100 .BR keyring (5)
101 for more details about keyring files.
102 .SH "KEY SETUP"
103 A
104 .I sigalgspec
105 has the form
106 .IR sig \c
107 .RB [ / \c
108 .IR hash ].
109 If a
110 .B sig
111 attribute is present on the key, then it must have this form; otherwise,
112 the key's type must have the form
113 .BI dsig- \c
114 .IR sigalgspec .
115 Algorithm selections are taken from appropriately-named attributes, or,
116 failing that, from the
117 .IR sigalgspec .
118 .PP
119 The signature algorithm is chosen according to the setting of
120 .I sig
121 as follows.  Run
122 .B dsig show sig
123 for a list of supported signature algorithms.
124 .TP
125 .B rsapkcs1
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
129 .B DigestInfo
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
134 to attack.  Use the
135 .B rsa
136 algorithm of the
137 .B key add
138 command (see
139 .BR key (1))
140 to generate the key.
141 .TP
142 .B rsapss
143 This is the RSASSA-PSS algorithm described in RFC3447.  It is the
144 preferred RSA-based signature scheme.  Use the
145 .B rsa
146 algorithm of the
147 .B key add
148 command (see
149 .BR key (1))
150 to generate the key.
151 .TP
152 .B dsa
153 This is the DSA algorithm described in FIPS180-1 and FIPS180-2.  Use the
154 .B dsa
155 algorithm of the
156 .B key add
157 command (see
158 .BR key (1))
159 to generate the key.
160 .TP
161 .B ecdsa
162 This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2.  Use
163 the
164 .B ec
165 algorithm of the
166 .B key add
167 command (see
168 .BR key (1))
169 to generate the key.
170 .TP
171 .B kcdsa
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 ).
176 Use the
177 .B dh
178 algorithm of the
179 .B key add
180 command with the
181 .B \-LS
182 options (see
183 .BR key (1))
184 to generate the key.
185 .TP
186 .B eckcdsa
187 This is an unofficial elliptic-curve analogue of the KCDSA algorithm.
188 Use the
189 .B ec
190 algorithm of the
191 .B key add
192 command (see
193 .BR key (1))
194 to generate the key.
195 .TP
196 .B ed25519
197 This is Bernstein, Duif, Lange, Schwabe, and Yang's Ed25519 algorithm.
198 More specifically, this is HashEd25519
199 using the selected
200 .B hash
201 algorithm \(en by default
202 .BR sha512 .
203 Use the
204 .B ed25519
205 algorithm of the
206 .B key add
207 command
208 (see
209 .BR key (1))
210 to generate the key.
211 .TP
212 .B ed448
213 This is Bernstein, Duif, Lange, Schwabe, and Yang's EdDSA algorithm,
214 using Hamburg's Ed448-Goldilocks elliptic curve,
215 as specified in RFC8032.
216 More specifically, this is HashEd448
217 using the selected
218 .B hash
219 algorithm \(en by default
220 .BR sha3-512 .
221 Use the
222 .B ed448
223 algorithm of the
224 .B key add
225 command
226 (see
227 .BR key (1))
228 to generate the key.
229 .PP
230 As well as the signature algorithm itself, a hash function is used.
231 This is taken from the
232 .B hash
233 attribute on the key, or, failing that, from the
234 .I hash
235 specified in the
236 .IR sigalgspec ,
237 or, if that is absent, determined by the signature algorithm as follows.
238 .hP \*o
239 For
240 .BR rsapkcs1 ,
241 .BR rsapss ,
242 .BR dsa ,
243 and
244 .BR ecdsa ,
245 the default hash function is
246 .BR sha .
247 .hP \*o
248 For
249 .BR kcdsa
250 and
251 .BR eckcdsa ,
252 the default hash function is
253 .BR has160 .
254 For
255 .BR ed25519 ,
256 the default hash function is
257 .BR sha512 .
258 For
259 .BR ed448 ,
260 the default hash function is
261 .BR shake256 .
262 .PP
263 Run
264 .B dsig show hash
265 for a list of supported hash functions.
266 .SH "COMMAND REFERENCE"
267 .SS help
268 The
269 .B help
270 command behaves exactly as the
271 .B \-\-help
272 option.  With no arguments, it shows an overview of
273 .BR dsig 's
274 options; with arguments, it describes the named subcommands.
275 .SS show
276 The
277 .B show
278 command prints various lists of tokens understood by
279 .BR dsig .
280 With no arguments, it prints all of the lists; with arguments, it prints
281 just the named lists, in order.  The recognized lists can be enumerated
282 using the
283 .VS
284 dsig show list
285 .VE
286 command.  The lists are as follows.
287 .TP
288 .B list
289 The lists which can be enumerated by the
290 .B show
291 command.
292 .TP
293 .B sig
294 The signature algorithms which can be used in a key's
295 .B sig
296 attribute.
297 .TP
298 .B hash
299 The hash functions which can be used in a key's
300 .B hash
301 attribute.
302 .SS sign
303 The
304 .B sign
305 command creates a signature for a collection of files.  The default
306 behaviour is to read a list of whitespace-separated file names (see
307 below for the precise format) from standard input and write the
308 an output file, containing hashes of the files and a digital signature
309 made by the key
310 .B dsig
311 in the current keyring, to standard output, in plain text with binary
312 values Base64-encoded.  It is intended to be used in conjunction with
313 .BR find (1).
314 This behaviour can be modified by specifying command-line options.
315 .TP
316 .B "\-0, \-\-null"
317 Read null-terminated filenames, rather than whitespace-separated names.
318 This is the recommended mode of operation if you have a
319 .BR find (1)
320 which understands the
321 .B \-print0
322 option.
323 .TP
324 .B "\-b, \-\-binary"
325 Produce output in raw binary rather than the textual output.  This isn't
326 a useful thing to do unless you're trying to debug
327 .BR dsig .
328 .TP
329 .B "\-v, \-\-verbose"
330 Makes
331 .B dsig
332 more verbose.  At present, this just means that it'll print the hashes
333 of files that it comes across in hex.  (Use
334 .BR hashsum (1)
335 if this is the output you actually wanted.)
336 .TP
337 .B "\-q, \-\-quiet"
338 Makes
339 .B dsig
340 less verbose.
341 .TP
342 .BI "\-c, \-\-comment " string
343 Writes
344 .I string
345 as a comment in the output file.  The comment's integrity is protected
346 by the signature.
347 .TP
348 .BI "\-p, \-\-progress"
349 Write a progress meter to standard error while processing large files.
350 .TP
351 .BI "\-f, \-\-file " name
352 Read filenames from
353 .I name
354 instead of from standard input.
355 .TP
356 .BI "\-h, \-\-hashes " name
357 Rather than hashing files, read precomputed hashes from the file
358 .IR name ,
359 which should be in the format produced by
360 .BR hashsum (1).
361 .TP
362 .BI "\-o, \-\-output " name
363 Write output to
364 .I name
365 instead of to standard output.
366 .TP
367 .BI "\-k, \-\-key " tag
368 Use the key named
369 .I tag
370 rather than the default
371 .BR dsig .
372 .TP
373 .BI "\-e, \-\-expire " date
374 Set the signature to expire at
375 .IR date .
376 The default is to expire 28 days from creation.  Use
377 .B forever
378 to make the signature not expire.
379 .TP
380 .B "\-C, \-\-nocheck"
381 Don't check the private key for validity.  This makes signing go much
382 faster, but at the risk of using a duff key, and potentially leaking
383 information about the private key.
384 .PP
385 The whitespace-separated format for filenames allows quoting and
386 escaping of strange characters.  The backslash
387 .RB ` \e '
388 can be used to escape whitespace, quotes, or other special characters
389 (including itself), and to represent special characters using the
390 standard C escape sequences
391 .RB ` \ea ',
392 .RB ` \eb ',
393 .RB ` \ef ',
394 .RB ` \en ',
395 .RB ` \et ',
396 and
397 .RB ` \eb '.
398 A filename can be quoted in
399 .BR ` ... ',
400 .BR ' ... '
401 or
402 .BR """" ... """".
403 Whitespace within quotes is part of the filename.  The quotes must be at
404 the beginning and end of the name.
405 .SS verify
406 The
407 .B verify
408 command will verify signatures made by the
409 .B sign
410 command.  With no arguments, it expects to read a text-format signature
411 file from standard input; with an argument, it examines the file it
412 names to see whether it's text or binary.
413 .PP
414 Command-line options provided are:
415 .TP
416 .B "\-v, \-\-verbose"
417 Produce more informational output.  The default verbosity level is 1.
418 .TP
419 .B "\-q, \-\-quiet"
420 Produce less information output.
421 .TP
422 .B "\-j, \-\-junk"
423 Report files whose hashes have not been checked.
424 .TP
425 .BI "\-p, \-\-progress"
426 Write a progress meter to standard error while processing large files.
427 .TP
428 .B "\-C, \-\-nocheck"
429 Don't check the public key for validity.  This makes verification go
430 much faster, but at the risk of using a duff key, and potentially
431 accepting false signatures.
432 .PP
433 Output is written to standard output in a machine-readable format.
434 Formatting errors cause the program to write a diagnostic to standard
435 error and exit nonzero as usual.  Lines begin with a keyword:
436 .TP
437 .BI "FAIL " reason
438 An error prevented verification.
439 .TP
440 .BI "BAD " reason
441 The signature is bad: some file had the wrong hash or the signature is
442 invalid.
443 .TP
444 .BI "WARN " reason
445 .B dsig
446 encountered a situation which may or may not invalidate the signature.
447 .TP
448 .BI "OK " message
449 The signature verified correctly.
450 .TP
451 .BI "JUNK " type " " name
452 The file
453 .I name
454 was found (as a result of the search requested by the
455 .RB ` \-j '
456 option), but it was not mentioned in the signature file and therefore
457 has not been checked.
458 .TP
459 .BI "INFO " note
460 Any other information.
461 .PP
462 The information written at the various verbosity levels is as follows.
463 .hP 0.
464 No output.  Watch the exit status.
465 .B dsig
466 exits zero if the signature was good.
467 .hP 1.
468 All
469 .BR OK ,
470 .B FAIL
471 and
472 .B WARN
473 messages are printed.
474 .hP 2.
475 As for level 1; also
476 .B BAD
477 messages are printed describing reasons why the signature verification
478 failed, and an
479 .B INFO
480 message is printed showing the signature file's comment if any.
481 .hP 3.
482 As for level 2; also
483 .B INFO
484 messages are shown listing the signing program's identification string,
485 the signing key, the signature and expiry dates, and actual signature
486 verification.
487 .hP 4.
488 As for level 3; also
489 .B INFO
490 messages are printed for each file covered, showing its name and hash.
491 .SH "OUTPUT FORMAT"
492 There are two output formats: textual and binary.  The hash used in the
493 digital signature is always computed on the
494 .I binary
495 version of the data, regardless of the external representation.
496 .SS "Textual format"
497 Within the file, whitespace and comments between strings are ignored.  A
498 comment begins with a hash
499 .RB (` # ')
500 and extends until the next newline.
501 .PP
502 Strings are either quoted or whitespace-delimited.  A string may be
503 quoted by
504 .BR ` ... ',
505 .BR ' ... '
506 or
507 .BR """" ... """".
508 The end-quote character can be backslash-escaped within the string.  An
509 occurrence of the unescaped end-quote character terminates the string.
510 A whitespace-delimited string is terminated by any unescaped whitespace
511 character.  The C-language escape sequences
512 .RB ` \ea ',
513 .RB ` \eb ',
514 .RB ` \ef ',
515 .RB ` \en ',
516 .RB ` \et ',
517 and
518 .RB ` \eb '
519 are recognized within either kind of string.
520 .PP
521 Blocks within the file consist of sequences of strings.  The first
522 string is a
523 .I tag
524 \(en a simple string ending in a colon
525 .RB (` : ')
526 \(en which describes the format of the remaining strings.
527 .SS "Binary format"
528 The file consists of a sequence of blocks, each of which begins with a
529 tag byte.  The format of the test of the block depends on the tag.
530 Strings are null-terminated; all integers are in network byte order.
531 .PP
532 A binary file always begins with an ident block, which has a tag of 0.
533 .SS "Block types"
534 The following block types are known.  They must appear in the order
535 given, and except where noted must appear exactly once each.
536 .TP
537 .BR "ident: " (0)
538 Identification string of the generating program.
539 .BR "keyid: " (1)
540 The signing key's id, as eight hex digits (text) or a 32-bit integer
541 (binary).
542 .TP
543 .BR "comment: " (2)
544 The comment string set with the
545 .B \-c
546 option to the
547 .B sign
548 command.  This block need not appear.
549 .TP
550 .BR "date: " (3)
551 The date the signature was made.  In a text file, this has the form
552 .IB yyyy-mm-dd
553 .IB hh:mm:ss
554 .IR timezone ;
555 in a binary file, it's a 64-bit integer representing the POSIX time.
556 .TP
557 .BR "expires: " (4)
558 The expiry time of the signature, expressed as for
559 .BR date: .
560 A non-expiring signature is represented by the string
561 .B forever
562 in text files, or all-bits-set in binary.
563 .TP
564 .BR "file: " (5)
565 A file hash.  In text, this is two strings which are the Base-64-encoded
566 hash and the file name; in binary, this is a 16-bit hash length, the raw
567 hash, and the null-terminated filename.  There can be any number of
568 .B file:
569 blocks.
570 .TP
571 .BR "signature: " (6)
572 The signature.  In text, this is the Base-64-encoded signature; in
573 binary, it is a 16-bit length followed by the binary signature.
574 .PP
575 The signature covers the
576 .I binary
577 representations of the file's
578 .BR date: ,
579 .B expires:
580 and
581 .B file:
582 blocks.
583 .SH "SEE ALSO"
584 .BR key (1),
585 .BR hashsum (1),
586 .BR catcrypt (1),
587 .BR catsign (1),
588 .BR keyring (5).
589 .SH AUTHOR
590 Mark Wooding, <mdw@distorted.org.uk>