| 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 | .PP |
| 196 | As well as the signature algorithm itself, a hash function is used. |
| 197 | This is taken from the |
| 198 | .B hash |
| 199 | attribute on the key, or, failing that, from the |
| 200 | .I hash |
| 201 | specified in the |
| 202 | .IR sigalgspec , |
| 203 | or, if that is absent, determined by the signature algorithm as follows. |
| 204 | .hP \*o |
| 205 | For |
| 206 | .BR rsapkcs1 , |
| 207 | .BR rsapss , |
| 208 | .BR dsa , |
| 209 | and |
| 210 | .BR ecdsa , |
| 211 | the default hash function is |
| 212 | .BR sha . |
| 213 | .hP \*o |
| 214 | For |
| 215 | .BR kcdsa |
| 216 | and |
| 217 | .BR eckcdsa , |
| 218 | the default hash function is |
| 219 | .BR has160 . |
| 220 | .PP |
| 221 | Run |
| 222 | .B dsig show hash |
| 223 | for a list of supported hash functions. |
| 224 | .SH "COMMAND REFERENCE" |
| 225 | .SS help |
| 226 | The |
| 227 | .B help |
| 228 | command behaves exactly as the |
| 229 | .B \-\-help |
| 230 | option. With no arguments, it shows an overview of |
| 231 | .BR dsig 's |
| 232 | options; with arguments, it describes the named subcommands. |
| 233 | .SS show |
| 234 | The |
| 235 | .B show |
| 236 | command prints various lists of tokens understood by |
| 237 | .BR dsig . |
| 238 | With no arguments, it prints all of the lists; with arguments, it prints |
| 239 | just the named lists, in order. The recognized lists can be enumerated |
| 240 | using the |
| 241 | .VS |
| 242 | dsig show list |
| 243 | .VE |
| 244 | command. The lists are as follows. |
| 245 | .TP |
| 246 | .B list |
| 247 | The lists which can be enumerated by the |
| 248 | .B show |
| 249 | command. |
| 250 | .TP |
| 251 | .B sig |
| 252 | The signature algorithms which can be used in a key's |
| 253 | .B sig |
| 254 | attribute. |
| 255 | .TP |
| 256 | .B hash |
| 257 | The hash functions which can be used in a key's |
| 258 | .B hash |
| 259 | attribute. |
| 260 | .SS sign |
| 261 | The |
| 262 | .B sign |
| 263 | command creates a signature for a collection of files. The default |
| 264 | behaviour is to read a list of whitespace-separated file names (see |
| 265 | below for the precise format) from standard input and write the |
| 266 | an output file, containing hashes of the files and a digital signature |
| 267 | made by the key |
| 268 | .B dsig |
| 269 | in the current keyring, to standard output, in plain text with binary |
| 270 | values Base64-encoded. It is intended to be used in conjunction with |
| 271 | .BR find (1). |
| 272 | This behaviour can be modified by specifying command-line options. |
| 273 | .TP |
| 274 | .B "\-0, \-\-null" |
| 275 | Read null-terminated filenames, rather than whitespace-separated names. |
| 276 | This is the recommended mode of operation if you have a |
| 277 | .BR find (1) |
| 278 | which understands the |
| 279 | .B \-print0 |
| 280 | option. |
| 281 | .TP |
| 282 | .B "\-b, \-\-binary" |
| 283 | Produce output in raw binary rather than the textual output. This isn't |
| 284 | a useful thing to do unless you're trying to debug |
| 285 | .BR dsig . |
| 286 | .TP |
| 287 | .B "\-v, \-\-verbose" |
| 288 | Makes |
| 289 | .B dsig |
| 290 | more verbose. At present, this just means that it'll print the hashes |
| 291 | of files that it comes across in hex. (Use |
| 292 | .BR hashsum (1) |
| 293 | if this is the output you actually wanted.) |
| 294 | .TP |
| 295 | .B "\-q, \-\-quiet" |
| 296 | Makes |
| 297 | .B dsig |
| 298 | less verbose. |
| 299 | .TP |
| 300 | .BI "\-c, \-\-comment " string |
| 301 | Writes |
| 302 | .I string |
| 303 | as a comment in the output file. The comment's integrity is protected |
| 304 | by the signature. |
| 305 | .TP |
| 306 | .BI "\-p, \-\-progress" |
| 307 | Write a progress meter to standard error while processing large files. |
| 308 | .TP |
| 309 | .BI "\-f, \-\-file " name |
| 310 | Read filenames from |
| 311 | .I name |
| 312 | instead of from standard input. |
| 313 | .TP |
| 314 | .BI "\-h, \-\-hashes " name |
| 315 | Rather than hashing files, read precomputed hashes from the file |
| 316 | .IR name , |
| 317 | which should be in the format produced by |
| 318 | .BR hashsum (1). |
| 319 | .TP |
| 320 | .BI "\-o, \-\-output " name |
| 321 | Write output to |
| 322 | .I name |
| 323 | instead of to standard output. |
| 324 | .TP |
| 325 | .BI "\-k, \-\-key " tag |
| 326 | Use the key named |
| 327 | .I tag |
| 328 | rather than the default |
| 329 | .BR dsig . |
| 330 | .TP |
| 331 | .BI "\-e, \-\-expire " date |
| 332 | Set the signature to expire at |
| 333 | .IR date . |
| 334 | The default is to expire 28 days from creation. Use |
| 335 | .B forever |
| 336 | to make the signature not expire. |
| 337 | .TP |
| 338 | .B "\-C, \-\-nocheck" |
| 339 | Don't check the private key for validity. This makes signing go much |
| 340 | faster, but at the risk of using a duff key, and potentially leaking |
| 341 | information about the private key. |
| 342 | .PP |
| 343 | The whitespace-separated format for filenames allows quoting and |
| 344 | escaping of strange characters. The backslash |
| 345 | .RB ` \e ' |
| 346 | can be used to escape whitespace, quotes, or other special characters |
| 347 | (including itself), and to represent special characters using the |
| 348 | standard C escape sequences |
| 349 | .RB ` \ea ', |
| 350 | .RB ` \eb ', |
| 351 | .RB ` \ef ', |
| 352 | .RB ` \en ', |
| 353 | .RB ` \et ', |
| 354 | and |
| 355 | .RB ` \eb '. |
| 356 | A filename can be quoted in |
| 357 | .BR ` ... ', |
| 358 | .BR ' ... ' |
| 359 | or |
| 360 | .BR """" ... """". |
| 361 | Whitespace within quotes is part of the filename. The quotes must be at |
| 362 | the beginning and end of the name. |
| 363 | .SS verify |
| 364 | The |
| 365 | .B verify |
| 366 | command will verify signatures made by the |
| 367 | .B sign |
| 368 | command. With no arguments, it expects to read a text-format signature |
| 369 | file from standard input; with an argument, it examines the file it |
| 370 | names to see whether it's text or binary. |
| 371 | .PP |
| 372 | Command-line options provided are: |
| 373 | .TP |
| 374 | .B "\-v, \-\-verbose" |
| 375 | Produce more informational output. The default verbosity level is 1. |
| 376 | .TP |
| 377 | .B "\-q, \-\-quiet" |
| 378 | Produce less information output. |
| 379 | .TP |
| 380 | .B "\-j, \-\-junk" |
| 381 | Report files whose hashes have not been checked. |
| 382 | .TP |
| 383 | .BI "\-p, \-\-progress" |
| 384 | Write a progress meter to standard error while processing large files. |
| 385 | .TP |
| 386 | .B "\-C, \-\-nocheck" |
| 387 | Don't check the public key for validity. This makes verification go |
| 388 | much faster, but at the risk of using a duff key, and potentially |
| 389 | accepting false signatures. |
| 390 | .PP |
| 391 | Output is written to standard output in a machine-readable format. |
| 392 | Formatting errors cause the program to write a diagnostic to standard |
| 393 | error and exit nonzero as usual. Lines begin with a keyword: |
| 394 | .TP |
| 395 | .BI "FAIL " reason |
| 396 | An error prevented verification. |
| 397 | .TP |
| 398 | .BI "BAD " reason |
| 399 | The signature is bad: some file had the wrong hash or the signature is |
| 400 | invalid. |
| 401 | .TP |
| 402 | .BI "WARN " reason |
| 403 | .B dsig |
| 404 | encountered a situation which may or may not invalidate the signature. |
| 405 | .TP |
| 406 | .BI "OK " message |
| 407 | The signature verified correctly. |
| 408 | .TP |
| 409 | .BI "JUNK " type " " name |
| 410 | The file |
| 411 | .I name |
| 412 | was found (as a result of the search requested by the |
| 413 | .RB ` \-j ' |
| 414 | option), but it was not mentioned in the signature file and therefore |
| 415 | has not been checked. |
| 416 | .TP |
| 417 | .BI "INFO " note |
| 418 | Any other information. |
| 419 | .PP |
| 420 | The information written at the various verbosity levels is as follows. |
| 421 | .hP 0. |
| 422 | No output. Watch the exit status. |
| 423 | .B dsig |
| 424 | exits zero if the signature was good. |
| 425 | .hP 1. |
| 426 | All |
| 427 | .BR OK , |
| 428 | .B FAIL |
| 429 | and |
| 430 | .B WARN |
| 431 | messages are printed. |
| 432 | .hP 2. |
| 433 | As for level 1; also |
| 434 | .B BAD |
| 435 | messages are printed describing reasons why the signature verification |
| 436 | failed, and an |
| 437 | .B INFO |
| 438 | message is printed showing the signature file's comment if any. |
| 439 | .hP 3. |
| 440 | As for level 2; also |
| 441 | .B INFO |
| 442 | messages are shown listing the signing program's identification string, |
| 443 | the signing key, the signature and expiry dates, and actual signature |
| 444 | verification. |
| 445 | .hP 4. |
| 446 | As for level 3; also |
| 447 | .B INFO |
| 448 | messages are printed for each file covered, showing its name and hash. |
| 449 | .SH "OUTPUT FORMAT" |
| 450 | There are two output formats: textual and binary. The hash used in the |
| 451 | digital signature is always computed on the |
| 452 | .I binary |
| 453 | version of the data, regardless of the external representation. |
| 454 | .SS "Textual format" |
| 455 | Within the file, whitespace and comments between strings are ignored. A |
| 456 | comment begins with a hash |
| 457 | .RB (` # ') |
| 458 | and extends until the next newline. |
| 459 | .PP |
| 460 | Strings are either quoted or whitespace-delimited. A string may be |
| 461 | quoted by |
| 462 | .BR ` ... ', |
| 463 | .BR ' ... ' |
| 464 | or |
| 465 | .BR """" ... """". |
| 466 | The end-quote character can be backslash-escaped within the string. An |
| 467 | occurrence of the unescaped end-quote character terminates the string. |
| 468 | A whitespace-delimited string is terminated by any unescaped whitespace |
| 469 | character. The C-language escape sequences |
| 470 | .RB ` \ea ', |
| 471 | .RB ` \eb ', |
| 472 | .RB ` \ef ', |
| 473 | .RB ` \en ', |
| 474 | .RB ` \et ', |
| 475 | and |
| 476 | .RB ` \eb ' |
| 477 | are recognized within either kind of string. |
| 478 | .PP |
| 479 | Blocks within the file consist of sequences of strings. The first |
| 480 | string is a |
| 481 | .I tag |
| 482 | \(en a simple string ending in a colon |
| 483 | .RB (` : ') |
| 484 | \(en which describes the format of the remaining strings. |
| 485 | .SS "Binary format" |
| 486 | The file consists of a sequence of blocks, each of which begins with a |
| 487 | tag byte. The format of the test of the block depends on the tag. |
| 488 | Strings are null-terminated; all integers are in network byte order. |
| 489 | .PP |
| 490 | A binary file always begins with an ident block, which has a tag of 0. |
| 491 | .SS "Block types" |
| 492 | The following block types are known. They must appear in the order |
| 493 | given, and except where noted must appear exactly once each. |
| 494 | .TP |
| 495 | .BR "ident: " (0) |
| 496 | Identification string of the generating program. |
| 497 | .BR "keyid: " (1) |
| 498 | The signing key's id, as eight hex digits (text) or a 32-bit integer |
| 499 | (binary). |
| 500 | .TP |
| 501 | .BR "comment: " (2) |
| 502 | The comment string set with the |
| 503 | .B \-c |
| 504 | option to the |
| 505 | .B sign |
| 506 | command. This block need not appear. |
| 507 | .TP |
| 508 | .BR "date: " (3) |
| 509 | The date the signature was made. In a text file, this has the form |
| 510 | .IB yyyy-mm-dd |
| 511 | .IB hh:mm:ss |
| 512 | .IR timezone ; |
| 513 | in a binary file, it's a 64-bit integer representing the POSIX time. |
| 514 | .TP |
| 515 | .BR "expires: " (4) |
| 516 | The expiry time of the signature, expressed as for |
| 517 | .BR date: . |
| 518 | A non-expiring signature is represented by the string |
| 519 | .B forever |
| 520 | in text files, or all-bits-set in binary. |
| 521 | .TP |
| 522 | .BR "file: " (5) |
| 523 | A file hash. In text, this is two strings which are the Base-64-encoded |
| 524 | hash and the file name; in binary, this is a 16-bit hash length, the raw |
| 525 | hash, and the null-terminated filename. There can be any number of |
| 526 | .B file: |
| 527 | blocks. |
| 528 | .TP |
| 529 | .BR "signature: " (6) |
| 530 | The signature. In text, this is the Base-64-encoded signature; in |
| 531 | binary, it is a 16-bit length followed by the binary signature. |
| 532 | .PP |
| 533 | The signature covers the |
| 534 | .I binary |
| 535 | representations of the file's |
| 536 | .BR date: , |
| 537 | .B expires: |
| 538 | and |
| 539 | .B file: |
| 540 | blocks. |
| 541 | .SH "SEE ALSO" |
| 542 | .BR key (1), |
| 543 | .BR hashsum (1), |
| 544 | .BR catcrypt (1), |
| 545 | .BR catsign (1), |
| 546 | .BR keyring (5). |
| 547 | .SH AUTHOR |
| 548 | Mark Wooding, <mdw@distorted.org.uk> |