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