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