doc/apps/ts.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ts - Time Stamping Authority tool (client/server)
   6
   7 =head1 SYNOPSIS
   8
   9 B<openssl> B<ts>
  10 B<-query>
  11 [B<-help>]
  12 [B<-rand> file:file...]
  13 [B<-config> configfile]
  14 [B<-data> file_to_hash]
  15 [B<-digest> digest_bytes]
  16 [B<-[digest]>]
  17 [B<-policy> object_id]
  18 [B<-no_nonce>]
  19 [B<-cert>]
  20 [B<-in> request.tsq]
  21 [B<-out> request.tsq]
  22 [B<-text>]
  23
  24 B<openssl> B<ts>
  25 B<-reply>
  26 [B<-config> configfile]
  27 [B<-section> tsa_section]
  28 [B<-queryfile> request.tsq]
  29 [B<-passin> password_src]
  30 [B<-signer> tsa_cert.pem]
  31 [B<-inkey> private.pem]
  32 [B<-sha1|-sha224|-sha256|-sha384|-sha512>]
  33 [B<-chain> certs_file.pem]
  34 [B<-policy> object_id]
  35 [B<-in> response.tsr]
  36 [B<-token_in>]
  37 [B<-out> response.tsr]
  38 [B<-token_out>]
  39 [B<-text>]
  40 [B<-engine> id]
  41
  42 B<openssl> B<ts>
  43 B<-verify>
  44 [B<-data> file_to_hash]
  45 [B<-digest> digest_bytes]
  46 [B<-queryfile> request.tsq]
  47 [B<-in> response.tsr]
  48 [B<-token_in>]
  49 [B<-CApath> trusted_cert_path]
  50 [B<-CAfile> trusted_certs.pem]
  51 [B<-untrusted> cert_file.pem]
  52
  53 =head1 DESCRIPTION
  54
  55 The B<ts> command is a basic Time Stamping Authority (TSA) client and server
  56 application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A
  57 TSA can be part of a PKI deployment and its role is to provide long
  58 term proof of the existence of a certain datum before a particular
  59 time. Here is a brief description of the protocol:
  60
  61 =over 4
  62
  63 =item 1.
  64
  65 The TSA client computes a one-way hash value for a data file and sends
  66 the hash to the TSA.
  67
  68 =item 2.
  69
  70 The TSA attaches the current date and time to the received hash value,
  71 signs them and sends the time stamp token back to the client. By
  72 creating this token the TSA certifies the existence of the original
  73 data file at the time of response generation.
  74
  75 =item 3.
  76
  77 The TSA client receives the time stamp token and verifies the
  78 signature on it. It also checks if the token contains the same hash
  79 value that it had sent to the TSA.
  80
  81 =back
  82
  83 There is one DER encoded protocol data unit defined for transporting a time
  84 stamp request to the TSA and one for sending the time stamp response
  85 back to the client. The B<ts> command has three main functions:
  86 creating a time stamp request based on a data file,
  87 creating a time stamp response based on a request, verifying if a
  88 response corresponds to a particular request or a data file.
  89
  90 There is no support for sending the requests/responses automatically
  91 over HTTP or TCP yet as suggested in RFC 3161. The users must send the
  92 requests either by ftp or e-mail.
  93
  94 =head1 OPTIONS
  95
  96 =head2 Time Stamp Request generation
  97
  98 The B<-query> switch can be used for creating and printing a time stamp
  99 request with the following options:
 100
 101 =over 4
 102
 103 =item B<-help>
 104
 105 Print out a usage message.
 106
 107 =item B<-rand> file:file...
 108
 109 The files containing random data for seeding the random number
 110 generator. Multiple files can be specified, the separator is B<;> for
 111 MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
 112
 113 =item B<-config> configfile
 114
 115 The configuration file to use, this option overrides the
 116 B<OPENSSL_CONF> environment variable. Only the OID section
 117 of the config file is used with the B<-query> command. (Optional)
 118
 119 =item B<-data> file_to_hash
 120
 121 The data file for which the time stamp request needs to be
 122 created. stdin is the default if neither the B<-data> nor the B<-digest>
 123 parameter is specified. (Optional)
 124
 125 =item B<-digest> digest_bytes
 126
 127 It is possible to specify the message imprint explicitly without the data
 128 file. The imprint must be specified in a hexadecimal format, two characters
 129 per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
 130 1AF601...). The number of bytes must match the message digest algorithm
 131 in use. (Optional)
 132
 133 =item B<-[digest]>
 134
 135 The message digest to apply to the data file.
 136 Any digest supported by the OpenSSL B<dgst> command can be used.
 137 The default is SHA-1. (Optional)
 138
 139 =item B<-policy> object_id
 140
 141 The policy that the client expects the TSA to use for creating the
 142 time stamp token. Either the dotted OID notation or OID names defined
 143 in the config file can be used. If no policy is requested the TSA will
 144 use its own default policy. (Optional)
 145
 146 =item B<-no_nonce>
 147
 148 No nonce is specified in the request if this option is
 149 given. Otherwise a 64 bit long pseudo-random none is
 150 included in the request. It is recommended to use nonce to
 151 protect against replay-attacks. (Optional)
 152
 153 =item B<-cert>
 154
 155 The TSA is expected to include its signing certificate in the
 156 response. (Optional)
 157
 158 =item B<-in> request.tsq
 159
 160 This option specifies a previously created time stamp request in DER
 161 format that will be printed into the output file. Useful when you need
 162 to examine the content of a request in human-readable
 163
 164 format. (Optional)
 165
 166 =item B<-out> request.tsq
 167
 168 Name of the output file to which the request will be written. Default
 169 is stdout. (Optional)
 170
 171 =item B<-text>
 172
 173 If this option is specified the output is human-readable text format
 174 instead of DER. (Optional)
 175
 176 =back
 177
 178 =head2 Time Stamp Response generation
 179
 180 A time stamp response (TimeStampResp) consists of a response status
 181 and the time stamp token itself (ContentInfo), if the token generation was
 182 successful. The B<-reply> command is for creating a time stamp
 183 response or time stamp token based on a request and printing the
 184 response/token in human-readable format. If B<-token_out> is not
 185 specified the output is always a time stamp response (TimeStampResp),
 186 otherwise it is a time stamp token (ContentInfo).
 187
 188 =over 4
 189
 190 =item B<-config> configfile
 191
 192 The configuration file to use, this option overrides the
 193 B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE
 194 OPTIONS> for configurable variables. (Optional)
 195
 196 =item B<-section> tsa_section
 197
 198 The name of the config file section containing the settings for the
 199 response generation. If not specified the default TSA section is
 200 used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
 201
 202 =item B<-queryfile> request.tsq
 203
 204 The name of the file containing a DER encoded time stamp request. (Optional)
 205
 206 =item B<-passin> password_src
 207
 208 Specifies the password source for the private key of the TSA. See
 209 B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional)
 210
 211 =item B<-signer> tsa_cert.pem
 212
 213 The signer certificate of the TSA in PEM format. The TSA signing
 214 certificate must have exactly one extended key usage assigned to it:
 215 timeStamping. The extended key usage must also be critical, otherwise
 216 the certificate is going to be refused. Overrides the B<signer_cert>
 217 variable of the config file. (Optional)
 218
 219 =item B<-inkey> private.pem
 220
 221 The signer private key of the TSA in PEM format. Overrides the
 222 B<signer_key> config file option. (Optional)
 223
 224 =item B<-sha1|-sha224|-sha256|-sha384|-sha512>
 225
 226 Signing digest to use. Overrides the B<signer_digest> config file
 227 option. (Optional)
 228
 229 =item B<-chain> certs_file.pem
 230
 231 The collection of certificates in PEM format that will all
 232 be included in the response in addition to the signer certificate if
 233 the B<-cert> option was used for the request. This file is supposed to
 234 contain the certificate chain for the signer certificate from its
 235 issuer upwards. The B<-reply> command does not build a certificate
 236 chain automatically. (Optional)
 237
 238 =item B<-policy> object_id
 239
 240 The default policy to use for the response unless the client
 241 explicitly requires a particular TSA policy. The OID can be specified
 242 either in dotted notation or with its name. Overrides the
 243 B<default_policy> config file option. (Optional)
 244
 245 =item B<-in> response.tsr
 246
 247 Specifies a previously created time stamp response or time stamp token
 248 (if B<-token_in> is also specified) in DER format that will be written
 249 to the output file. This option does not require a request, it is
 250 useful e.g. when you need to examine the content of a response or
 251 token or you want to extract the time stamp token from a response. If
 252 the input is a token and the output is a time stamp response a default
 253 'granted' status info is added to the token. (Optional)
 254
 255 =item B<-token_in>
 256
 257 This flag can be used together with the B<-in> option and indicates
 258 that the input is a DER encoded time stamp token (ContentInfo) instead
 259 of a time stamp response (TimeStampResp). (Optional)
 260
 261 =item B<-out> response.tsr
 262
 263 The response is written to this file. The format and content of the
 264 file depends on other options (see B<-text>, B<-token_out>). The default is
 265 stdout. (Optional)
 266
 267 =item B<-token_out>
 268
 269 The output is a time stamp token (ContentInfo) instead of time stamp
 270 response (TimeStampResp). (Optional)
 271
 272 =item B<-text>
 273
 274 If this option is specified the output is human-readable text format
 275 instead of DER. (Optional)
 276
 277 =item B<-engine> id
 278
 279 Specifying an engine (by its unique B<id> string) will cause B<ts>
 280 to attempt to obtain a functional reference to the specified engine,
 281 thus initialising it if needed. The engine will then be set as the default
 282 for all available algorithms. Default is builtin. (Optional)
 283
 284 =back
 285
 286 =head2 Time Stamp Response verification
 287
 288 The B<-verify> command is for verifying if a time stamp response or time
 289 stamp token is valid and matches a particular time stamp request or
 290 data file. The B<-verify> command does not use the configuration file.
 291
 292 =over 4
 293
 294 =item B<-data> file_to_hash
 295
 296 The response or token must be verified against file_to_hash. The file
 297 is hashed with the message digest algorithm specified in the token.
 298 The B<-digest> and B<-queryfile> options must not be specified with this one.
 299 (Optional)
 300
 301 =item B<-digest> digest_bytes
 302
 303 The response or token must be verified against the message digest specified
 304 with this option. The number of bytes must match the message digest algorithm
 305 specified in the token. The B<-data> and B<-queryfile> options must not be
 306 specified with this one. (Optional)
 307
 308 =item B<-queryfile> request.tsq
 309
 310 The original time stamp request in DER format. The B<-data> and B<-digest>
 311 options must not be specified with this one. (Optional)
 312
 313 =item B<-in> response.tsr
 314
 315 The time stamp response that needs to be verified in DER format. (Mandatory)
 316
 317 =item B<-token_in>
 318
 319 This flag can be used together with the B<-in> option and indicates
 320 that the input is a DER encoded time stamp token (ContentInfo) instead
 321 of a time stamp response (TimeStampResp). (Optional)
 322
 323 =item B<-CApath> trusted_cert_path
 324
 325 The name of the directory containing the trusted CA certificates of the
 326 client. See the similar option of L<verify(1)> for additional
 327 details. Either this option or B<-CAfile> must be specified. (Optional)
 328
 329
 330 =item B<-CAfile> trusted_certs.pem
 331
 332 The name of the file containing a set of trusted self-signed CA
 333 certificates in PEM format. See the similar option of
 334 L<verify(1)> for additional details. Either this option
 335 or B<-CApath> must be specified.
 336 (Optional)
 337
 338 =item B<-untrusted> cert_file.pem
 339
 340 Set of additional untrusted certificates in PEM format which may be
 341 needed when building the certificate chain for the TSA's signing
 342 certificate. This file must contain the TSA signing certificate and
 343 all intermediate CA certificates unless the response includes them.
 344 (Optional)
 345
 346 =back
 347
 348 =head1 CONFIGURATION FILE OPTIONS
 349
 350 The B<-query> and B<-reply> commands make use of a configuration file
 351 defined by the B<OPENSSL_CONF> environment variable. See L<config(5)>
 352 for a general description of the syntax of the config file. The
 353 B<-query> command uses only the symbolic OID names section
 354 and it can work without it. However, the B<-reply> command needs the
 355 config file for its operation.
 356
 357 When there is a command line switch equivalent of a variable the
 358 switch always overrides the settings in the config file.
 359
 360 =over 4
 361
 362 =item B<tsa> section, B<default_tsa>
 363
 364 This is the main section and it specifies the name of another section
 365 that contains all the options for the B<-reply> command. This default
 366 section can be overridden with the B<-section> command line switch. (Optional)
 367
 368 =item B<oid_file>
 369
 370 See L<ca(1)> for description. (Optional)
 371
 372 =item B<oid_section>
 373
 374 See L<ca(1)> for description. (Optional)
 375
 376 =item B<RANDFILE>
 377
 378 See L<ca(1)> for description. (Optional)
 379
 380 =item B<serial>
 381
 382 The name of the file containing the hexadecimal serial number of the
 383 last time stamp response created. This number is incremented by 1 for
 384 each response. If the file does not exist at the time of response
 385 generation a new file is created with serial number 1. (Mandatory)
 386
 387 =item B<crypto_device>
 388
 389 Specifies the OpenSSL engine that will be set as the default for
 390 all available algorithms. The default value is builtin, you can specify
 391 any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
 392 (Optional)
 393
 394 =item B<signer_cert>
 395
 396 TSA signing certificate in PEM format. The same as the B<-signer>
 397 command line option. (Optional)
 398
 399 =item B<certs>
 400
 401 A file containing a set of PEM encoded certificates that need to be
 402 included in the response. The same as the B<-chain> command line
 403 option. (Optional)
 404
 405 =item B<signer_key>
 406
 407 The private key of the TSA in PEM format. The same as the B<-inkey>
 408 command line option. (Optional)
 409
 410 =item B<signer_digest>
 411
 412 Signing digest to use. The same as the
 413 B<-sha1|-sha224|-sha256|-sha384|-sha512> command line option. (Optional)
 414
 415 =item B<default_policy>
 416
 417 The default policy to use when the request does not mandate any
 418 policy. The same as the B<-policy> command line option. (Optional)
 419
 420 =item B<other_policies>
 421
 422 Comma separated list of policies that are also acceptable by the TSA
 423 and used only if the request explicitly specifies one of them. (Optional)
 424
 425 =item B<digests>
 426
 427 The list of message digest algorithms that the TSA accepts. At least
 428 one algorithm must be specified. (Mandatory)
 429
 430 =item B<accuracy>
 431
 432 The accuracy of the time source of the TSA in seconds, milliseconds
 433 and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
 434 the components is missing zero is assumed for that field. (Optional)
 435
 436 =item B<clock_precision_digits>
 437
 438 Specifies the maximum number of digits, which represent the fraction of
 439 seconds, that  need to be included in the time field. The trailing zeroes
 440 must be removed from the time, so there might actually be fewer digits,
 441 or no fraction of seconds at all. Supported only on UNIX platforms.
 442 The maximum value is 6, default is 0.
 443 (Optional)
 444
 445 =item B<ordering>
 446
 447 If this option is yes the responses generated by this TSA can always
 448 be ordered, even if the time difference between two responses is less
 449 than the sum of their accuracies. Default is no. (Optional)
 450
 451 =item B<tsa_name>
 452
 453 Set this option to yes if the subject name of the TSA must be included in
 454 the TSA name field of the response. Default is no. (Optional)
 455
 456 =item B<ess_cert_id_chain>
 457
 458 The SignedData objects created by the TSA always contain the
 459 certificate identifier of the signing certificate in a signed
 460 attribute (see RFC 2634, Enhanced Security Services). If this option
 461 is set to yes and either the B<certs> variable or the B<-chain> option
 462 is specified then the certificate identifiers of the chain will also
 463 be included in the SigningCertificate signed attribute. If this
 464 variable is set to no, only the signing certificate identifier is
 465 included. Default is no. (Optional)
 466
 467 =back
 468
 469 =head1 ENVIRONMENT VARIABLES
 470
 471 B<OPENSSL_CONF> contains the path of the configuration file and can be
 472 overridden by the B<-config> command line option.
 473
 474 =head1 EXAMPLES
 475
 476 All the examples below presume that B<OPENSSL_CONF> is set to a proper
 477 configuration file, e.g. the example configuration file
 478 openssl/apps/openssl.cnf will do.
 479
 480 =head2 Time Stamp Request
 481
 482 To create a time stamp request for design1.txt with SHA-1
 483 without nonce and policy and no certificate is required in the response:
 484
 485   openssl ts -query -data design1.txt -no_nonce \
 486         -out design1.tsq
 487
 488 To create a similar time stamp request with specifying the message imprint
 489 explicitly:
 490
 491   openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
 492          -no_nonce -out design1.tsq
 493
 494 To print the content of the previous request in human readable format:
 495
 496   openssl ts -query -in design1.tsq -text
 497
 498 To create a time stamp request which includes the MD-5 digest
 499 of design2.txt, requests the signer certificate and nonce,
 500 specifies a policy id (assuming the tsa_policy1 name is defined in the
 501 OID section of the config file):
 502
 503   openssl ts -query -data design2.txt -md5 \
 504         -policy tsa_policy1 -cert -out design2.tsq
 505
 506 =head2 Time Stamp Response
 507
 508 Before generating a response a signing certificate must be created for
 509 the TSA that contains the B<timeStamping> critical extended key usage extension
 510 without any other key usage extensions. You can add the
 511 'extendedKeyUsage = critical,timeStamping' line to the user certificate section
 512 of the config file to generate a proper certificate. See L<req(1)>,
 513 L<ca(1)>, L<x509(1)> for instructions. The examples
 514 below assume that cacert.pem contains the certificate of the CA,
 515 tsacert.pem is the signing certificate issued by cacert.pem and
 516 tsakey.pem is the private key of the TSA.
 517
 518 To create a time stamp response for a request:
 519
 520   openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
 521         -signer tsacert.pem -out design1.tsr
 522
 523 If you want to use the settings in the config file you could just write:
 524
 525   openssl ts -reply -queryfile design1.tsq -out design1.tsr
 526
 527 To print a time stamp reply to stdout in human readable format:
 528
 529   openssl ts -reply -in design1.tsr -text
 530
 531 To create a time stamp token instead of time stamp response:
 532
 533   openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
 534
 535 To print a time stamp token to stdout in human readable format:
 536
 537   openssl ts -reply -in design1_token.der -token_in -text -token_out
 538
 539 To extract the time stamp token from a response:
 540
 541   openssl ts -reply -in design1.tsr -out design1_token.der -token_out
 542
 543 To add 'granted' status info to a time stamp token thereby creating a
 544 valid response:
 545
 546   openssl ts -reply -in design1_token.der -token_in -out design1.tsr
 547
 548 =head2 Time Stamp Verification
 549
 550 To verify a time stamp reply against a request:
 551
 552   openssl ts -verify -queryfile design1.tsq -in design1.tsr \
 553         -CAfile cacert.pem -untrusted tsacert.pem
 554
 555 To verify a time stamp reply that includes the certificate chain:
 556
 557   openssl ts -verify -queryfile design2.tsq -in design2.tsr \
 558         -CAfile cacert.pem
 559
 560 To verify a time stamp token against the original data file:
 561   openssl ts -verify -data design2.txt -in design2.tsr \
 562         -CAfile cacert.pem
 563
 564 To verify a time stamp token against a message imprint:
 565   openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
 566          -in design2.tsr -CAfile cacert.pem
 567
 568 You could also look at the 'test' directory for more examples.
 569
 570 =head1 BUGS
 571
 572 If you find any bugs or you have suggestions please write to
 573 Zoltan Glozik <zglozik@opentsa.org>. Known issues:
 574
 575 =over 4
 576
 577 =item * No support for time stamps over SMTP, though it is quite easy
 578 to implement an automatic e-mail based TSA with L<procmail(1)>
 579 and L<perl(1)>. HTTP server support is provided in the form of
 580 a separate apache module. HTTP client support is provided by
 581 L<tsget(1)>. Pure TCP/IP protocol is not supported.
 582
 583 =item * The file containing the last serial number of the TSA is not
 584 locked when being read or written. This is a problem if more than one
 585 instance of L<openssl(1)> is trying to create a time stamp
 586 response at the same time. This is not an issue when using the apache
 587 server module, it does proper locking.
 588
 589 =item * Look for the FIXME word in the source files.
 590
 591 =item * The source code should really be reviewed by somebody else, too.
 592
 593 =item * More testing is needed, I have done only some basic tests (see
 594 test/testtsa).
 595
 596 =back
 597
 598 =cut
 599
 600 =head1 SEE ALSO
 601
 602 L<tsget(1)>, L<openssl(1)>, L<req(1)>,
 603 L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
 604 L<config(5)>
 605
 606 =cut