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