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