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