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