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