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