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