]>
Commit | Line | Data |
---|---|---|
c7235be6 UM |
1 | =pod |
2 | ||
9fcb9702 RS |
3 | =begin comment |
4 | {- join("\n", @autowarntext) -} | |
5 | ||
6 | =end comment | |
7 | ||
c7235be6 UM |
8 | =head1 NAME |
9 | ||
b6b66573 | 10 | openssl-ts - Time Stamping Authority tool (client/server) |
c7235be6 UM |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | B<openssl> B<ts> | |
15 | B<-query> | |
e8769719 RS |
16 | [B<-config> I<configfile>] |
17 | [B<-data> I<file_to_hash>] | |
18 | [B<-digest> I<digest_bytes>] | |
8dc57d76 | 19 | [B<-I<digest>>] |
e8769719 | 20 | [B<-tspolicy> I<object_id>] |
c7235be6 UM |
21 | [B<-no_nonce>] |
22 | [B<-cert>] | |
e8769719 RS |
23 | [B<-in> I<request.tsq>] |
24 | [B<-out> I<request.tsq>] | |
c7235be6 | 25 | [B<-text>] |
9fcb9702 | 26 | {- $OpenSSL::safe::opt_r_synopsis -} |
c7235be6 UM |
27 | |
28 | B<openssl> B<ts> | |
29 | B<-reply> | |
e8769719 RS |
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>] | |
8dc57d76 | 36 | [B<-I<digest>>] |
e8769719 RS |
37 | [B<-chain> I<certs_file.pem>] |
38 | [B<-tspolicy> I<object_id>] | |
39 | [B<-in> I<response.tsr>] | |
c7235be6 | 40 | [B<-token_in>] |
e8769719 | 41 | [B<-out> I<response.tsr>] |
c7235be6 UM |
42 | [B<-token_out>] |
43 | [B<-text>] | |
e8769719 | 44 | [B<-engine> I<id>] |
c7235be6 UM |
45 | |
46 | B<openssl> B<ts> | |
47 | B<-verify> | |
e8769719 RS |
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>] | |
c7235be6 | 52 | [B<-token_in>] |
e8769719 RS |
53 | [B<-CApath> I<trusted_cert_path>] |
54 | [B<-CAfile> I<trusted_certs.pem>] | |
55 | [B<-untrusted> I<cert_file.pem>] | |
08538fc0 | 56 | [I<verify options>] |
57 | ||
58 | I<verify options:> | |
e8769719 RS |
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>] | |
c7235be6 | 88 | |
9f3c076b | 89 | =for openssl ifdef engine |
1738c0ce | 90 | |
c7235be6 UM |
91 | =head1 DESCRIPTION |
92 | ||
35a810bb RL |
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 | |
c7235be6 UM |
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, | |
9c0586d5 | 109 | signs them and sends the timestamp token back to the client. By |
c7235be6 UM |
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 | ||
9c0586d5 | 115 | The TSA client receives the timestamp token and verifies the |
c7235be6 UM |
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 | |
9c0586d5 | 122 | stamp request to the TSA and one for sending the timestamp response |
35a810bb | 123 | back to the client. This command has three main functions: |
9c0586d5 RS |
124 | creating a timestamp request based on a data file, |
125 | creating a timestamp response based on a request, verifying if a | |
c7235be6 UM |
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 | ||
9c0586d5 | 134 | =head2 Timestamp Request generation |
c7235be6 | 135 | |
9c0586d5 | 136 | The B<-query> switch can be used for creating and printing a timestamp |
c7235be6 UM |
137 | request with the following options: |
138 | ||
139 | =over 4 | |
140 | ||
e8769719 | 141 | =item B<-config> I<configfile> |
c7235be6 | 142 | |
e9681f83 RS |
143 | The configuration file to use. |
144 | Optional; for a description of the default value, | |
145 | see L<openssl(1)/COMMAND SUMMARY>. | |
c7235be6 | 146 | |
e8769719 | 147 | =item B<-data> I<file_to_hash> |
c7235be6 | 148 | |
9c0586d5 | 149 | The data file for which the timestamp request needs to be |
c7235be6 UM |
150 | created. stdin is the default if neither the B<-data> nor the B<-digest> |
151 | parameter is specified. (Optional) | |
152 | ||
e8769719 | 153 | =item B<-digest> I<digest_bytes> |
c7235be6 UM |
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 | |
4c583c36 | 158 | 1AF601...). The number of bytes must match the message digest algorithm |
c7235be6 UM |
159 | in use. (Optional) |
160 | ||
8dc57d76 | 161 | =item B<-I<digest>> |
c7235be6 | 162 | |
c03726ca | 163 | The message digest to apply to the data file. |
35a810bb | 164 | Any digest supported by the L<openssl-dgst(1)> command can be used. |
02f209bb | 165 | The default is SHA-256. (Optional) |
c7235be6 | 166 | |
e8769719 | 167 | =item B<-tspolicy> I<object_id> |
c7235be6 UM |
168 | |
169 | The policy that the client expects the TSA to use for creating the | |
9c0586d5 | 170 | timestamp token. Either the dotted OID notation or OID names defined |
c7235be6 UM |
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 | ||
e8769719 | 186 | =item B<-in> I<request.tsq> |
c7235be6 | 187 | |
9c0586d5 | 188 | This option specifies a previously created timestamp request in DER |
c7235be6 UM |
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 | |
c7235be6 UM |
191 | format. (Optional) |
192 | ||
e8769719 | 193 | =item B<-out> I<request.tsq> |
c7235be6 UM |
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 | ||
9fcb9702 RS |
203 | {- $OpenSSL::safe::opt_r_item -} |
204 | ||
c7235be6 UM |
205 | =back |
206 | ||
9c0586d5 | 207 | =head2 Timestamp Response generation |
c7235be6 | 208 | |
9c0586d5 RS |
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 | |
c7235be6 | 213 | response/token in human-readable format. If B<-token_out> is not |
9c0586d5 RS |
214 | specified the output is always a timestamp response (TimeStampResp), |
215 | otherwise it is a timestamp token (ContentInfo). | |
c7235be6 UM |
216 | |
217 | =over 4 | |
218 | ||
e8769719 | 219 | =item B<-config> I<configfile> |
c7235be6 | 220 | |
e9681f83 RS |
221 | The configuration file to use. |
222 | Optional; for a description of the default value, | |
223 | see L<openssl(1)/COMMAND SUMMARY>. | |
e8769719 | 224 | See L</CONFIGURATION FILE OPTIONS> for configurable variables. |
c7235be6 | 225 | |
e8769719 | 226 | =item B<-section> I<tsa_section> |
c7235be6 | 227 | |
4c583c36 | 228 | The name of the config file section containing the settings for the |
c7235be6 | 229 | response generation. If not specified the default TSA section is |
e8769719 | 230 | used, see L</CONFIGURATION FILE OPTIONS> for details. (Optional) |
c7235be6 | 231 | |
e8769719 | 232 | =item B<-queryfile> I<request.tsq> |
c7235be6 | 233 | |
9c0586d5 | 234 | The name of the file containing a DER encoded timestamp request. (Optional) |
c7235be6 | 235 | |
e8769719 | 236 | =item B<-passin> I<password_src> |
c7235be6 UM |
237 | |
238 | Specifies the password source for the private key of the TSA. See | |
e8769719 | 239 | description in L<openssl(1)>. (Optional) |
c7235be6 | 240 | |
e8769719 | 241 | =item B<-signer> I<tsa_cert.pem> |
c7235be6 UM |
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 | ||
e8769719 | 249 | =item B<-inkey> I<file_or_id> |
c7235be6 UM |
250 | |
251 | The signer private key of the TSA in PEM format. Overrides the | |
252 | B<signer_key> config file option. (Optional) | |
48b53522 RS |
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. | |
c7235be6 | 255 | |
8dc57d76 | 256 | =item B<-I<digest>> |
e20b4727 DSH |
257 | |
258 | Signing digest to use. Overrides the B<signer_digest> config file | |
29716a03 | 259 | option. (Mandatory unless specified in the config file) |
e20b4727 | 260 | |
e8769719 | 261 | =item B<-chain> I<certs_file.pem> |
c7235be6 UM |
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 | ||
e8769719 | 270 | =item B<-tspolicy> I<object_id> |
c7235be6 UM |
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 | ||
e8769719 | 277 | =item B<-in> I<response.tsr> |
c7235be6 | 278 | |
9c0586d5 | 279 | Specifies a previously created timestamp response or timestamp token |
c7235be6 UM |
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 | |
9c0586d5 RS |
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 | |
c7235be6 UM |
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 | |
9c0586d5 RS |
290 | that the input is a DER encoded timestamp token (ContentInfo) instead |
291 | of a timestamp response (TimeStampResp). (Optional) | |
c7235be6 | 292 | |
e8769719 | 293 | =item B<-out> I<response.tsr> |
c7235be6 UM |
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 | ||
9c0586d5 | 301 | The output is a timestamp token (ContentInfo) instead of timestamp |
c7235be6 UM |
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 | ||
e8769719 | 309 | =item B<-engine> I<id> |
c7235be6 | 310 | |
35a810bb | 311 | Specifying an engine (by its unique I<id> string) will cause this command |
c7235be6 UM |
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 | |
9c0586d5 | 314 | for all available algorithms. Default is built-in. (Optional) |
c7235be6 UM |
315 | |
316 | =back | |
317 | ||
9c0586d5 | 318 | =head2 Timestamp Response verification |
c7235be6 | 319 | |
9c0586d5 RS |
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 | |
c7235be6 UM |
322 | data file. The B<-verify> command does not use the configuration file. |
323 | ||
324 | =over 4 | |
325 | ||
e8769719 | 326 | =item B<-data> I<file_to_hash> |
c7235be6 UM |
327 | |
328 | The response or token must be verified against file_to_hash. The file | |
4c583c36 | 329 | is hashed with the message digest algorithm specified in the token. |
c7235be6 UM |
330 | The B<-digest> and B<-queryfile> options must not be specified with this one. |
331 | (Optional) | |
332 | ||
e8769719 | 333 | =item B<-digest> I<digest_bytes> |
c7235be6 UM |
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 | ||
e8769719 | 340 | =item B<-queryfile> I<request.tsq> |
c7235be6 | 341 | |
9c0586d5 | 342 | The original timestamp request in DER format. The B<-data> and B<-digest> |
c7235be6 UM |
343 | options must not be specified with this one. (Optional) |
344 | ||
e8769719 | 345 | =item B<-in> I<response.tsr> |
c7235be6 | 346 | |
9c0586d5 | 347 | The timestamp response that needs to be verified in DER format. (Mandatory) |
c7235be6 UM |
348 | |
349 | =item B<-token_in> | |
350 | ||
351 | This flag can be used together with the B<-in> option and indicates | |
9c0586d5 RS |
352 | that the input is a DER encoded timestamp token (ContentInfo) instead |
353 | of a timestamp response (TimeStampResp). (Optional) | |
c7235be6 | 354 | |
a397aca4 | 355 | =item B<-CAfile> I<file>, B<-CApath> I<dir> |
c7235be6 | 356 | |
a397aca4 | 357 | See L<openssl(1)/Trusted Certificate Options> for more information. |
c7235be6 | 358 | |
e8769719 | 359 | =item B<-untrusted> I<cert_file.pem> |
c7235be6 UM |
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 | ||
08538fc0 | 367 | =item I<verify options> |
368 | ||
e8769719 | 369 | The options B<-attime>, B<-check_ss_sig>, B<-crl_check>, |
fbb82a60 VD |
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 | |
35a810bb | 377 | verification. See L<openssl-verify(1)>. |
08538fc0 | 378 | |
c7235be6 UM |
379 | =back |
380 | ||
381 | =head1 CONFIGURATION FILE OPTIONS | |
382 | ||
e9681f83 RS |
383 | The B<-query> and B<-reply> commands make use of a configuration file. |
384 | See L<config(5)> | |
c7235be6 UM |
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 | ||
4c583c36 | 395 | =item B<tsa> section, B<default_tsa> |
c7235be6 UM |
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 | |
2b4ffc65 | 399 | section can be overridden with the B<-section> command line switch. (Optional) |
c7235be6 UM |
400 | |
401 | =item B<oid_file> | |
402 | ||
8bc93d2f | 403 | See L<openssl-ca(1)> for description. (Optional) |
c7235be6 UM |
404 | |
405 | =item B<oid_section> | |
406 | ||
8bc93d2f | 407 | See L<openssl-ca(1)> for description. (Optional) |
c7235be6 UM |
408 | |
409 | =item B<RANDFILE> | |
410 | ||
8bc93d2f | 411 | See L<openssl-ca(1)> for description. (Optional) |
c7235be6 UM |
412 | |
413 | =item B<serial> | |
414 | ||
415 | The name of the file containing the hexadecimal serial number of the | |
9c0586d5 | 416 | last timestamp response created. This number is incremented by 1 for |
28f7e60d | 417 | each response. If the file does not exist at the time of response |
c7235be6 UM |
418 | generation a new file is created with serial number 1. (Mandatory) |
419 | ||
420 | =item B<crypto_device> | |
421 | ||
4c583c36 | 422 | Specifies the OpenSSL engine that will be set as the default for |
9c0586d5 | 423 | all available algorithms. The default value is built-in, you can specify |
c7235be6 UM |
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 | ||
e20b4727 DSH |
443 | =item B<signer_digest> |
444 | ||
445 | Signing digest to use. The same as the | |
8dc57d76 | 446 | B<-I<digest>> command line option. (Mandatory unless specified on the command |
29716a03 | 447 | line) |
e20b4727 | 448 | |
c7235be6 UM |
449 | =item B<default_policy> |
450 | ||
451 | The default policy to use when the request does not mandate any | |
08538fc0 | 452 | policy. The same as the B<-tspolicy> command line option. (Optional) |
c7235be6 UM |
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 | ||
4c583c36 | 472 | Specifies the maximum number of digits, which represent the fraction of |
9c0586d5 | 473 | seconds, that need to be included in the time field. The trailing zeros |
c7235be6 UM |
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 | ||
f0ef20bf MK |
501 | =item B<ess_cert_id_alg> |
502 | ||
503 | This option specifies the hash function to be used to calculate the TSA's | |
a6dfa188 | 504 | public key certificate identifier. Default is sha256. (Optional) |
f0ef20bf | 505 | |
c7235be6 UM |
506 | =back |
507 | ||
c7235be6 UM |
508 | =head1 EXAMPLES |
509 | ||
510 | All the examples below presume that B<OPENSSL_CONF> is set to a proper | |
4c583c36 | 511 | configuration file, e.g. the example configuration file |
1948394d | 512 | F<openssl/apps/openssl.cnf> will do. |
c7235be6 | 513 | |
9c0586d5 | 514 | =head2 Timestamp Request |
c7235be6 | 515 | |
1948394d | 516 | To create a timestamp request for F<design1.txt> with SHA-256 digest, |
02f209bb TM |
517 | without nonce and policy, and without requirement for a certificate |
518 | in the response: | |
c7235be6 UM |
519 | |
520 | openssl ts -query -data design1.txt -no_nonce \ | |
1bc74519 | 521 | -out design1.tsq |
c7235be6 | 522 | |
9c0586d5 | 523 | To create a similar timestamp request with specifying the message imprint |
c7235be6 UM |
524 | explicitly: |
525 | ||
526 | openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ | |
1bc74519 | 527 | -no_nonce -out design1.tsq |
c7235be6 UM |
528 | |
529 | To print the content of the previous request in human readable format: | |
530 | ||
531 | openssl ts -query -in design1.tsq -text | |
532 | ||
9c0586d5 | 533 | To create a timestamp request which includes the SHA-512 digest |
1948394d | 534 | of F<design2.txt>, requests the signer certificate and nonce, and |
c7235be6 UM |
535 | specifies a policy id (assuming the tsa_policy1 name is defined in the |
536 | OID section of the config file): | |
537 | ||
a6dfa188 | 538 | openssl ts -query -data design2.txt -sha512 \ |
1bc74519 | 539 | -tspolicy tsa_policy1 -cert -out design2.tsq |
c7235be6 | 540 | |
9c0586d5 | 541 | =head2 Timestamp Response |
c7235be6 UM |
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 | |
dfee8626 RS |
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 | ||
8bc93d2f RL |
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. | |
c7235be6 | 554 | |
9c0586d5 | 555 | To create a timestamp response for a request: |
c7235be6 UM |
556 | |
557 | openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ | |
1bc74519 | 558 | -signer tsacert.pem -out design1.tsr |
c7235be6 UM |
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 | ||
9c0586d5 | 564 | To print a timestamp reply to stdout in human readable format: |
c7235be6 UM |
565 | |
566 | openssl ts -reply -in design1.tsr -text | |
567 | ||
9c0586d5 | 568 | To create a timestamp token instead of timestamp response: |
c7235be6 UM |
569 | |
570 | openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out | |
571 | ||
9c0586d5 | 572 | To print a timestamp token to stdout in human readable format: |
c7235be6 UM |
573 | |
574 | openssl ts -reply -in design1_token.der -token_in -text -token_out | |
575 | ||
9c0586d5 | 576 | To extract the timestamp token from a response: |
c7235be6 UM |
577 | |
578 | openssl ts -reply -in design1.tsr -out design1_token.der -token_out | |
579 | ||
9c0586d5 | 580 | To add 'granted' status info to a timestamp token thereby creating a |
c7235be6 UM |
581 | valid response: |
582 | ||
583 | openssl ts -reply -in design1_token.der -token_in -out design1.tsr | |
584 | ||
9c0586d5 | 585 | =head2 Timestamp Verification |
c7235be6 | 586 | |
9c0586d5 | 587 | To verify a timestamp reply against a request: |
c7235be6 UM |
588 | |
589 | openssl ts -verify -queryfile design1.tsq -in design1.tsr \ | |
1bc74519 | 590 | -CAfile cacert.pem -untrusted tsacert.pem |
c7235be6 | 591 | |
9c0586d5 | 592 | To verify a timestamp reply that includes the certificate chain: |
c7235be6 UM |
593 | |
594 | openssl ts -verify -queryfile design2.tsq -in design2.tsr \ | |
1bc74519 | 595 | -CAfile cacert.pem |
c7235be6 | 596 | |
9c0586d5 | 597 | To verify a timestamp token against the original data file: |
c7235be6 | 598 | openssl ts -verify -data design2.txt -in design2.tsr \ |
1bc74519 | 599 | -CAfile cacert.pem |
c7235be6 | 600 | |
9c0586d5 | 601 | To verify a timestamp token against a message imprint: |
c7235be6 | 602 | openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ |
1bc74519 | 603 | -in design2.tsr -CAfile cacert.pem |
c7235be6 UM |
604 | |
605 | You could also look at the 'test' directory for more examples. | |
606 | ||
607 | =head1 BUGS | |
608 | ||
bb82531f | 609 | =for openssl foreign manuals: procmail(1), perl(1) |
b275f3b6 | 610 | |
2f61bc2e RS |
611 | =over 2 |
612 | ||
613 | =item * | |
c7235be6 | 614 | |
9c0586d5 | 615 | No support for timestamps over SMTP, though it is quite easy |
9b86974e RS |
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 | |
c7235be6 | 618 | a separate apache module. HTTP client support is provided by |
9b86974e | 619 | L<tsget(1)>. Pure TCP/IP protocol is not supported. |
c7235be6 | 620 | |
2f61bc2e RS |
621 | =item * |
622 | ||
623 | The file containing the last serial number of the TSA is not | |
c7235be6 | 624 | locked when being read or written. This is a problem if more than one |
9c0586d5 | 625 | instance of L<openssl(1)> is trying to create a timestamp |
c7235be6 UM |
626 | response at the same time. This is not an issue when using the apache |
627 | server module, it does proper locking. | |
628 | ||
2f61bc2e RS |
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. | |
c7235be6 | 636 | |
2f61bc2e | 637 | =item * |
c7235be6 | 638 | |
2f61bc2e | 639 | More testing is needed, I have done only some basic tests (see |
c7235be6 UM |
640 | test/testtsa). |
641 | ||
642 | =back | |
643 | ||
c7235be6 UM |
644 | =head1 SEE ALSO |
645 | ||
b6b66573 DMSP |
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)>, | |
9b86974e | 652 | L<config(5)> |
c7235be6 | 653 | |
e2f92610 RS |
654 | =head1 COPYRIGHT |
655 | ||
b6b66573 | 656 | Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 657 | |
449040b4 | 658 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |