Commit | Line | Data |
---|---|---|
c65df279 | 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 | |
cd6eca43 | 47 | .RB [ \-0bpqvC ] |
c65df279 | 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 ] | |
95d92463 MW |
58 | .RB [ \-h |
59 | .IR file ] | |
c65df279 | 60 | .RB [ \-o |
61 | .IR output ] | |
62 | .br | |
63 | .B verify | |
f5e91c02 | 64 | .RB [ \-pqvjC ] |
c65df279 | 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 | |
45c0fd36 | 128 | wrapped in a DER-encoded |
c65df279 | 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 | |
45c0fd36 | 153 | This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the |
c65df279 | 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. | |
d56fd9d1 MW |
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. | |
c578d5d8 MW |
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. | |
c65df279 | 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 | |
45c0fd36 | 249 | .BR kcdsa |
c65df279 | 250 | and |
251 | .BR eckcdsa , | |
252 | the default hash function is | |
253 | .BR has160 . | |
df8800f1 MW |
254 | For |
255 | .BR ed25519 , | |
256 | the default hash function is | |
257 | .BR sha512 . | |
c578d5d8 MW |
258 | For |
259 | .BR ed448 , | |
260 | the default hash function is | |
261 | .BR shake256 . | |
c65df279 | 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 | |
cd6eca43 MW |
348 | .BI "\-p, \-\-progress" |
349 | Write a progress meter to standard error while processing large files. | |
350 | .TP | |
c65df279 | 351 | .BI "\-f, \-\-file " name |
352 | Read filenames from | |
353 | .I name | |
354 | instead of from standard input. | |
355 | .TP | |
95d92463 MW |
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 | |
c65df279 | 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. | |
946c3f72 | 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. | |
c65df279 | 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. | |
946c3f72 | 421 | .TP |
f5e91c02 MW |
422 | .B "\-j, \-\-junk" |
423 | Report files whose hashes have not been checked. | |
424 | .TP | |
cd6eca43 MW |
425 | .BI "\-p, \-\-progress" |
426 | Write a progress meter to standard error while processing large files. | |
427 | .TP | |
946c3f72 | 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. | |
c65df279 | 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 | |
45c0fd36 | 442 | invalid. |
c65df279 | 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 | |
f5e91c02 MW |
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 | |
c65df279 | 459 | .BI "INFO " note |
45c0fd36 | 460 | Any other information. |
c65df279 | 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 | |
45c0fd36 | 552 | .IB yyyy-mm-dd |
c65df279 | 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), | |
fa54fe1e | 587 | .BR catsign (1), |
c65df279 | 588 | .BR keyring (5). |
589 | .SH AUTHOR | |
f387fcb1 | 590 | Mark Wooding, <mdw@distorted.org.uk> |