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 |
946c3f72 |
47 | .RB [ \-0bqvC ] |
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 ] |
58 | .RB [ \-o |
59 | .IR output ] |
60 | .br |
61 | .B verify |
946c3f72 |
62 | .RB [ \-qvC ] |
c65df279 |
63 | .RI [ file ] |
64 | .SH DESCRIPTION |
65 | The |
66 | .B dsig |
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 |
69 | carried out. |
70 | .SS "Global options" |
71 | Before the command name, |
72 | .I "global options" |
73 | may be given. The following global options are supported: |
74 | .TP |
75 | .BR "\-h, \-\-help " [ \fIcommand ...] |
76 | Writes a brief summary of |
77 | .BR dsig 's |
78 | various options to standard output, and returns a successful exit |
79 | status. With command names, gives help on those commands. |
80 | .TP |
81 | .B "\-v, \-\-version" |
82 | Writes the program's version number to standard output, and returns a |
83 | successful exit status. |
84 | .TP |
85 | .B "\-u, \-\-usage" |
86 | Writes a very terse command line summary to standard output, and returns |
87 | a successful exit status. |
88 | .TP |
89 | .BI "\-k, \-\-keyring " file |
90 | Names the keyring file which |
91 | .B key |
92 | is to process. The default keyring, used if this option doesn't specify |
93 | one, is the file named |
94 | .B keyring |
95 | in the current directory. See |
96 | .BR key (1) |
97 | and |
98 | .BR keyring (5) |
99 | for more details about keyring files. |
100 | .SH "KEY SETUP" |
101 | A |
102 | .I sigalgspec |
103 | has the form |
104 | .IR sig \c |
105 | .RB [ / \c |
106 | .IR hash ]. |
107 | If a |
108 | .B sig |
109 | attribute is present on the key, then it must have this form; otherwise, |
110 | the key's type must have the form |
111 | .BI dsig- \c |
112 | .IR sigalgspec . |
113 | Algorithm selections are taken from appropriately-named attributes, or, |
114 | failing that, from the |
115 | .IR sigalgspec . |
116 | .PP |
117 | The signature algorithm is chosen according to the setting of |
118 | .I sig |
119 | as follows. Run |
120 | .B dsig show sig |
121 | for a list of supported signature algorithms. |
122 | .TP |
123 | .B rsapkcs1 |
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 |
127 | .B DigestInfo |
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 |
132 | to attack. Use the |
133 | .B rsa |
134 | algorithm of the |
135 | .B key add |
136 | command (see |
137 | .BR key (1)) |
138 | to generate the key. |
139 | .TP |
140 | .B rsapss |
141 | This is the RSASSA-PSS algorithm described in RFC3447. It is the |
142 | preferred RSA-based signature scheme. Use the |
143 | .B rsa |
144 | algorithm of the |
145 | .B key add |
146 | command (see |
147 | .BR key (1)) |
148 | to generate the key. |
149 | .TP |
150 | .B dsa |
151 | This is the DSA algorithm described in FIPS180-1 and FIPS180-2. Use the |
152 | .B dsa |
153 | algorithm of the |
154 | .B key add |
155 | command (see |
156 | .BR key (1)) |
157 | to generate the key. |
158 | .TP |
159 | .B ecdsa |
160 | This is the ECDSA algorithm described in ANSI X9.62 and FIPS180-2. Use |
161 | the |
162 | .B ec |
163 | algorithm of the |
164 | .B key add |
165 | command (see |
166 | .BR key (1)) |
167 | to generate the key. |
168 | .TP |
169 | .B kcdsa |
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 ). |
174 | Use the |
175 | .B dh |
176 | algorithm of the |
177 | .B key add |
178 | command with the |
179 | .B \-LS |
180 | options (see |
181 | .BR key (1)) |
182 | to generate the key. |
183 | .TP |
184 | .B eckcdsa |
185 | This is an unofficial elliptic-curve analogue of the KCDSA algorithm. |
186 | Use the |
187 | .B ec |
188 | algorithm of the |
189 | .B key add |
190 | command (see |
191 | .BR key (1)) |
192 | to generate the key. |
193 | .PP |
194 | As well as the signature algorithm itself, a hash function is used. |
195 | This is taken from the |
196 | .B hash |
197 | attribute on the key, or, failing that, from the |
198 | .I hash |
199 | specified in the |
200 | .IR sigalgspec , |
201 | or, if that is absent, determined by the signature algorithm as follows. |
202 | .hP \*o |
203 | For |
204 | .BR rsapkcs1 , |
205 | .BR rsapss , |
206 | .BR dsa , |
207 | and |
208 | .BR ecdsa , |
209 | the default hash function is |
210 | .BR sha . |
211 | .hP \*o |
212 | For |
213 | .BR kcdsa |
214 | and |
215 | .BR eckcdsa , |
216 | the default hash function is |
217 | .BR has160 . |
218 | .PP |
219 | Run |
220 | .B dsig show hash |
221 | for a list of supported hash functions. |
222 | .SH "COMMAND REFERENCE" |
223 | .SS help |
224 | The |
225 | .B help |
226 | command behaves exactly as the |
227 | .B \-\-help |
228 | option. With no arguments, it shows an overview of |
229 | .BR dsig 's |
230 | options; with arguments, it describes the named subcommands. |
231 | .SS show |
232 | The |
233 | .B show |
234 | command prints various lists of tokens understood by |
235 | .BR dsig . |
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 |
238 | using the |
239 | .VS |
240 | dsig show list |
241 | .VE |
242 | command. The lists are as follows. |
243 | .TP |
244 | .B list |
245 | The lists which can be enumerated by the |
246 | .B show |
247 | command. |
248 | .TP |
249 | .B sig |
250 | The signature algorithms which can be used in a key's |
251 | .B sig |
252 | attribute. |
253 | .TP |
254 | .B hash |
255 | The hash functions which can be used in a key's |
256 | .B hash |
257 | attribute. |
258 | .SS sign |
259 | The |
260 | .B sign |
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 |
265 | made by the key |
266 | .B dsig |
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 |
269 | .BR find (1). |
270 | This behaviour can be modified by specifying command-line options. |
271 | .TP |
272 | .B "\-0, \-\-null" |
273 | Read null-terminated filenames, rather than whitespace-separated names. |
274 | This is the recommended mode of operation if you have a |
275 | .BR find (1) |
276 | which understands the |
277 | .B \-print0 |
278 | option. |
279 | .TP |
280 | .B "\-b, \-\-binary" |
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 |
283 | .BR dsig . |
284 | .TP |
285 | .B "\-v, \-\-verbose" |
286 | Makes |
287 | .B dsig |
288 | more verbose. At present, this just means that it'll print the hashes |
289 | of files that it comes across in hex. (Use |
290 | .BR hashsum (1) |
291 | if this is the output you actually wanted.) |
292 | .TP |
293 | .B "\-q, \-\-quiet" |
294 | Makes |
295 | .B dsig |
296 | less verbose. |
297 | .TP |
298 | .BI "\-c, \-\-comment " string |
299 | Writes |
300 | .I string |
301 | as a comment in the output file. The comment's integrity is protected |
302 | by the signature. |
303 | .TP |
304 | .BI "\-f, \-\-file " name |
305 | Read filenames from |
306 | .I name |
307 | instead of from standard input. |
308 | .TP |
309 | .BI "\-o, \-\-output " name |
310 | Write output to |
311 | .I name |
312 | instead of to standard output. |
313 | .TP |
314 | .BI "\-k, \-\-key " tag |
315 | Use the key named |
316 | .I tag |
317 | rather than the default |
318 | .BR dsig . |
319 | .TP |
320 | .BI "\-e, \-\-expire " date |
321 | Set the signature to expire at |
322 | .IR date . |
323 | The default is to expire 28 days from creation. Use |
324 | .B forever |
325 | to make the signature not expire. |
946c3f72 |
326 | .TP |
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. |
c65df279 |
331 | .PP |
332 | The whitespace-separated format for filenames allows quoting and |
333 | escaping of strange characters. The backslash |
334 | .RB ` \e ' |
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 |
338 | .RB ` \ea ', |
339 | .RB ` \eb ', |
340 | .RB ` \ef ', |
341 | .RB ` \en ', |
342 | .RB ` \et ', |
343 | and |
344 | .RB ` \eb '. |
345 | A filename can be quoted in |
346 | .BR ` ... ', |
347 | .BR ' ... ' |
348 | or |
349 | .BR """" ... """". |
350 | Whitespace within quotes is part of the filename. The quotes must be at |
351 | the beginning and end of the name. |
352 | .SS verify |
353 | The |
354 | .B verify |
355 | command will verify signatures made by the |
356 | .B sign |
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. |
360 | .PP |
361 | Command-line options provided are: |
362 | .TP |
363 | .B "\-v, \-\-verbose" |
364 | Produce more informational output. The default verbosity level is 1. |
365 | .TP |
366 | .B "\-q, \-\-quiet" |
367 | Produce less information output. |
946c3f72 |
368 | .TP |
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. |
c65df279 |
373 | .PP |
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: |
377 | .TP |
378 | .BI "FAIL " reason |
379 | An error prevented verification. |
380 | .TP |
381 | .BI "BAD " reason |
382 | The signature is bad: some file had the wrong hash or the signature is |
383 | invalid. |
384 | .TP |
385 | .BI "WARN " reason |
386 | .B dsig |
387 | encountered a situation which may or may not invalidate the signature. |
388 | .TP |
389 | .BI "OK " message |
390 | The signature verified correctly. |
391 | .TP |
392 | .BI "INFO " note |
393 | Any other information. |
394 | .PP |
395 | The information written at the various verbosity levels is as follows. |
396 | .hP 0. |
397 | No output. Watch the exit status. |
398 | .B dsig |
399 | exits zero if the signature was good. |
400 | .hP 1. |
401 | All |
402 | .BR OK , |
403 | .B FAIL |
404 | and |
405 | .B WARN |
406 | messages are printed. |
407 | .hP 2. |
408 | As for level 1; also |
409 | .B BAD |
410 | messages are printed describing reasons why the signature verification |
411 | failed, and an |
412 | .B INFO |
413 | message is printed showing the signature file's comment if any. |
414 | .hP 3. |
415 | As for level 2; also |
416 | .B INFO |
417 | messages are shown listing the signing program's identification string, |
418 | the signing key, the signature and expiry dates, and actual signature |
419 | verification. |
420 | .hP 4. |
421 | As for level 3; also |
422 | .B INFO |
423 | messages are printed for each file covered, showing its name and hash. |
424 | .SH "OUTPUT FORMAT" |
425 | There are two output formats: textual and binary. The hash used in the |
426 | digital signature is always computed on the |
427 | .I binary |
428 | version of the data, regardless of the external representation. |
429 | .SS "Textual format" |
430 | Within the file, whitespace and comments between strings are ignored. A |
431 | comment begins with a hash |
432 | .RB (` # ') |
433 | and extends until the next newline. |
434 | .PP |
435 | Strings are either quoted or whitespace-delimited. A string may be |
436 | quoted by |
437 | .BR ` ... ', |
438 | .BR ' ... ' |
439 | or |
440 | .BR """" ... """". |
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 |
445 | .RB ` \ea ', |
446 | .RB ` \eb ', |
447 | .RB ` \ef ', |
448 | .RB ` \en ', |
449 | .RB ` \et ', |
450 | and |
451 | .RB ` \eb ' |
452 | are recognized within either kind of string. |
453 | .PP |
454 | Blocks within the file consist of sequences of strings. The first |
455 | string is a |
456 | .I tag |
457 | \(en a simple string ending in a colon |
458 | .RB (` : ') |
459 | \(en which describes the format of the remaining strings. |
460 | .SS "Binary format" |
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. |
464 | .PP |
465 | A binary file always begins with an ident block, which has a tag of 0. |
466 | .SS "Block types" |
467 | The following block types are known. They must appear in the order |
468 | given, and except where noted must appear exactly once each. |
469 | .TP |
470 | .BR "ident: " (0) |
471 | Identification string of the generating program. |
472 | .BR "keyid: " (1) |
473 | The signing key's id, as eight hex digits (text) or a 32-bit integer |
474 | (binary). |
475 | .TP |
476 | .BR "comment: " (2) |
477 | The comment string set with the |
478 | .B \-c |
479 | option to the |
480 | .B sign |
481 | command. This block need not appear. |
482 | .TP |
483 | .BR "date: " (3) |
484 | The date the signature was made. In a text file, this has the form |
485 | .IB yyyy-mm-dd |
486 | .IB hh:mm:ss |
487 | .IR timezone ; |
488 | in a binary file, it's a 64-bit integer representing the POSIX time. |
489 | .TP |
490 | .BR "expires: " (4) |
491 | The expiry time of the signature, expressed as for |
492 | .BR date: . |
493 | A non-expiring signature is represented by the string |
494 | .B forever |
495 | in text files, or all-bits-set in binary. |
496 | .TP |
497 | .BR "file: " (5) |
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 |
501 | .B file: |
502 | blocks. |
503 | .TP |
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. |
507 | .PP |
508 | The signature covers the |
509 | .I binary |
510 | representations of the file's |
511 | .BR date: , |
512 | .B expires: |
513 | and |
514 | .B file: |
515 | blocks. |
516 | .SH "SEE ALSO" |
517 | .BR key (1), |
518 | .BR hashsum (1), |
519 | .BR catcrypt (1), |
fa54fe1e |
520 | .BR catsign (1), |
c65df279 |
521 | .BR keyring (5). |
522 | .SH AUTHOR |
f387fcb1 |
523 | Mark Wooding, <mdw@distorted.org.uk> |