doc/man1/openssl-ts.pod.in

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