crypto/openssl/doc/apps/ts.pod

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