]>
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>] | |
f91d003a | 35 | [B<-inkey> I<filename>|I<uri>] |
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>] | |
d55e4487 | 44 | {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} |
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>] |
f62846b7 | 53 | [B<-untrusted> I<files>|I<uris>] |
03e16083 RS |
54 | [B<-CAfile> I<file>] |
55 | [B<-CApath> I<dir>] | |
56 | [B<-CAstore> I<uri>] | |
21d08b9e | 57 | {- $OpenSSL::safe::opt_v_synopsis -} |
6bd4e3f2 | 58 | {- $OpenSSL::safe::opt_provider_synopsis -} |
c7235be6 | 59 | |
9f3c076b | 60 | =for openssl ifdef engine |
1738c0ce | 61 | |
c7235be6 UM |
62 | =head1 DESCRIPTION |
63 | ||
35a810bb RL |
64 | This command is a basic Time Stamping Authority (TSA) client and |
65 | server application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A | |
c7235be6 UM |
66 | TSA can be part of a PKI deployment and its role is to provide long |
67 | term proof of the existence of a certain datum before a particular | |
68 | time. Here is a brief description of the protocol: | |
69 | ||
70 | =over 4 | |
71 | ||
72 | =item 1. | |
73 | ||
74 | The TSA client computes a one-way hash value for a data file and sends | |
75 | the hash to the TSA. | |
76 | ||
77 | =item 2. | |
78 | ||
79 | The TSA attaches the current date and time to the received hash value, | |
9c0586d5 | 80 | signs them and sends the timestamp token back to the client. By |
c7235be6 UM |
81 | creating this token the TSA certifies the existence of the original |
82 | data file at the time of response generation. | |
83 | ||
84 | =item 3. | |
85 | ||
9c0586d5 | 86 | The TSA client receives the timestamp token and verifies the |
c7235be6 UM |
87 | signature on it. It also checks if the token contains the same hash |
88 | value that it had sent to the TSA. | |
89 | ||
90 | =back | |
91 | ||
490c8711 GN |
92 | There is one DER encoded protocol data unit defined for transporting a |
93 | timestamp request to the TSA and one for sending the timestamp response | |
35a810bb | 94 | back to the client. This command has three main functions: |
9c0586d5 RS |
95 | creating a timestamp request based on a data file, |
96 | creating a timestamp response based on a request, verifying if a | |
c7235be6 UM |
97 | response corresponds to a particular request or a data file. |
98 | ||
99 | There is no support for sending the requests/responses automatically | |
100 | over HTTP or TCP yet as suggested in RFC 3161. The users must send the | |
101 | requests either by ftp or e-mail. | |
102 | ||
103 | =head1 OPTIONS | |
104 | ||
65718c51 RS |
105 | =over 4 |
106 | ||
107 | =item B<-help> | |
108 | ||
109 | Print out a usage message. | |
110 | ||
111 | =back | |
112 | ||
9c0586d5 | 113 | =head2 Timestamp Request generation |
c7235be6 | 114 | |
9c0586d5 | 115 | The B<-query> switch can be used for creating and printing a timestamp |
c7235be6 UM |
116 | request with the following options: |
117 | ||
118 | =over 4 | |
119 | ||
e8769719 | 120 | =item B<-config> I<configfile> |
c7235be6 | 121 | |
e9681f83 RS |
122 | The configuration file to use. |
123 | Optional; for a description of the default value, | |
124 | see L<openssl(1)/COMMAND SUMMARY>. | |
c7235be6 | 125 | |
e8769719 | 126 | =item B<-data> I<file_to_hash> |
c7235be6 | 127 | |
9c0586d5 | 128 | The data file for which the timestamp request needs to be |
c7235be6 UM |
129 | created. stdin is the default if neither the B<-data> nor the B<-digest> |
130 | parameter is specified. (Optional) | |
131 | ||
e8769719 | 132 | =item B<-digest> I<digest_bytes> |
c7235be6 UM |
133 | |
134 | It is possible to specify the message imprint explicitly without the data | |
135 | file. The imprint must be specified in a hexadecimal format, two characters | |
136 | per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or | |
4c583c36 | 137 | 1AF601...). The number of bytes must match the message digest algorithm |
c7235be6 UM |
138 | in use. (Optional) |
139 | ||
8dc57d76 | 140 | =item B<-I<digest>> |
c7235be6 | 141 | |
c03726ca | 142 | The message digest to apply to the data file. |
35a810bb | 143 | Any digest supported by the L<openssl-dgst(1)> command can be used. |
02f209bb | 144 | The default is SHA-256. (Optional) |
c7235be6 | 145 | |
e8769719 | 146 | =item B<-tspolicy> I<object_id> |
c7235be6 UM |
147 | |
148 | The policy that the client expects the TSA to use for creating the | |
9c0586d5 | 149 | timestamp token. Either the dotted OID notation or OID names defined |
c7235be6 UM |
150 | in the config file can be used. If no policy is requested the TSA will |
151 | use its own default policy. (Optional) | |
152 | ||
153 | =item B<-no_nonce> | |
154 | ||
155 | No nonce is specified in the request if this option is | |
156 | given. Otherwise a 64 bit long pseudo-random none is | |
157 | included in the request. It is recommended to use nonce to | |
158 | protect against replay-attacks. (Optional) | |
159 | ||
160 | =item B<-cert> | |
161 | ||
162 | The TSA is expected to include its signing certificate in the | |
163 | response. (Optional) | |
164 | ||
e8769719 | 165 | =item B<-in> I<request.tsq> |
c7235be6 | 166 | |
9c0586d5 | 167 | This option specifies a previously created timestamp request in DER |
c7235be6 UM |
168 | format that will be printed into the output file. Useful when you need |
169 | to examine the content of a request in human-readable | |
c7235be6 UM |
170 | format. (Optional) |
171 | ||
e8769719 | 172 | =item B<-out> I<request.tsq> |
c7235be6 UM |
173 | |
174 | Name of the output file to which the request will be written. Default | |
175 | is stdout. (Optional) | |
176 | ||
177 | =item B<-text> | |
178 | ||
179 | If this option is specified the output is human-readable text format | |
180 | instead of DER. (Optional) | |
181 | ||
9fcb9702 RS |
182 | {- $OpenSSL::safe::opt_r_item -} |
183 | ||
c7235be6 UM |
184 | =back |
185 | ||
9c0586d5 | 186 | =head2 Timestamp Response generation |
c7235be6 | 187 | |
9c0586d5 RS |
188 | A timestamp response (TimeStampResp) consists of a response status |
189 | and the timestamp token itself (ContentInfo), if the token generation was | |
190 | successful. The B<-reply> command is for creating a timestamp | |
191 | response or timestamp token based on a request and printing the | |
c7235be6 | 192 | response/token in human-readable format. If B<-token_out> is not |
9c0586d5 RS |
193 | specified the output is always a timestamp response (TimeStampResp), |
194 | otherwise it is a timestamp token (ContentInfo). | |
c7235be6 UM |
195 | |
196 | =over 4 | |
197 | ||
e8769719 | 198 | =item B<-config> I<configfile> |
c7235be6 | 199 | |
e9681f83 RS |
200 | The configuration file to use. |
201 | Optional; for a description of the default value, | |
202 | see L<openssl(1)/COMMAND SUMMARY>. | |
e8769719 | 203 | See L</CONFIGURATION FILE OPTIONS> for configurable variables. |
c7235be6 | 204 | |
e8769719 | 205 | =item B<-section> I<tsa_section> |
c7235be6 | 206 | |
4c583c36 | 207 | The name of the config file section containing the settings for the |
c7235be6 | 208 | response generation. If not specified the default TSA section is |
e8769719 | 209 | used, see L</CONFIGURATION FILE OPTIONS> for details. (Optional) |
c7235be6 | 210 | |
e8769719 | 211 | =item B<-queryfile> I<request.tsq> |
c7235be6 | 212 | |
9c0586d5 | 213 | The name of the file containing a DER encoded timestamp request. (Optional) |
c7235be6 | 214 | |
e8769719 | 215 | =item B<-passin> I<password_src> |
c7235be6 UM |
216 | |
217 | Specifies the password source for the private key of the TSA. See | |
e8769719 | 218 | description in L<openssl(1)>. (Optional) |
c7235be6 | 219 | |
e8769719 | 220 | =item B<-signer> I<tsa_cert.pem> |
c7235be6 UM |
221 | |
222 | The signer certificate of the TSA in PEM format. The TSA signing | |
223 | certificate must have exactly one extended key usage assigned to it: | |
224 | timeStamping. The extended key usage must also be critical, otherwise | |
225 | the certificate is going to be refused. Overrides the B<signer_cert> | |
226 | variable of the config file. (Optional) | |
227 | ||
f91d003a | 228 | =item B<-inkey> I<filename>|I<uri> |
c7235be6 UM |
229 | |
230 | The signer private key of the TSA in PEM format. Overrides the | |
231 | B<signer_key> config file option. (Optional) | |
232 | ||
8dc57d76 | 233 | =item B<-I<digest>> |
e20b4727 DSH |
234 | |
235 | Signing digest to use. Overrides the B<signer_digest> config file | |
29716a03 | 236 | option. (Mandatory unless specified in the config file) |
e20b4727 | 237 | |
e8769719 | 238 | =item B<-chain> I<certs_file.pem> |
c7235be6 UM |
239 | |
240 | The collection of certificates in PEM format that will all | |
241 | be included in the response in addition to the signer certificate if | |
242 | the B<-cert> option was used for the request. This file is supposed to | |
243 | contain the certificate chain for the signer certificate from its | |
244 | issuer upwards. The B<-reply> command does not build a certificate | |
245 | chain automatically. (Optional) | |
246 | ||
e8769719 | 247 | =item B<-tspolicy> I<object_id> |
c7235be6 UM |
248 | |
249 | The default policy to use for the response unless the client | |
250 | explicitly requires a particular TSA policy. The OID can be specified | |
251 | either in dotted notation or with its name. Overrides the | |
252 | B<default_policy> config file option. (Optional) | |
253 | ||
e8769719 | 254 | =item B<-in> I<response.tsr> |
c7235be6 | 255 | |
9c0586d5 | 256 | Specifies a previously created timestamp response or timestamp token |
c7235be6 UM |
257 | (if B<-token_in> is also specified) in DER format that will be written |
258 | to the output file. This option does not require a request, it is | |
259 | useful e.g. when you need to examine the content of a response or | |
9c0586d5 RS |
260 | token or you want to extract the timestamp token from a response. If |
261 | the input is a token and the output is a timestamp response a default | |
c7235be6 UM |
262 | 'granted' status info is added to the token. (Optional) |
263 | ||
264 | =item B<-token_in> | |
265 | ||
266 | This flag can be used together with the B<-in> option and indicates | |
9c0586d5 RS |
267 | that the input is a DER encoded timestamp token (ContentInfo) instead |
268 | of a timestamp response (TimeStampResp). (Optional) | |
c7235be6 | 269 | |
e8769719 | 270 | =item B<-out> I<response.tsr> |
c7235be6 UM |
271 | |
272 | The response is written to this file. The format and content of the | |
273 | file depends on other options (see B<-text>, B<-token_out>). The default is | |
274 | stdout. (Optional) | |
275 | ||
276 | =item B<-token_out> | |
277 | ||
9c0586d5 | 278 | The output is a timestamp token (ContentInfo) instead of timestamp |
c7235be6 UM |
279 | response (TimeStampResp). (Optional) |
280 | ||
281 | =item B<-text> | |
282 | ||
283 | If this option is specified the output is human-readable text format | |
284 | instead of DER. (Optional) | |
285 | ||
018aaeb4 | 286 | {- $OpenSSL::safe::opt_engine_item -} |
c7235be6 | 287 | |
6bd4e3f2 P |
288 | {- $OpenSSL::safe::opt_provider_item -} |
289 | ||
c7235be6 UM |
290 | =back |
291 | ||
9c0586d5 | 292 | =head2 Timestamp Response verification |
c7235be6 | 293 | |
490c8711 GN |
294 | The B<-verify> command is for verifying if a timestamp response or |
295 | timestamp token is valid and matches a particular timestamp request or | |
c7235be6 UM |
296 | data file. The B<-verify> command does not use the configuration file. |
297 | ||
298 | =over 4 | |
299 | ||
e8769719 | 300 | =item B<-data> I<file_to_hash> |
c7235be6 UM |
301 | |
302 | The response or token must be verified against file_to_hash. The file | |
4c583c36 | 303 | is hashed with the message digest algorithm specified in the token. |
c7235be6 UM |
304 | The B<-digest> and B<-queryfile> options must not be specified with this one. |
305 | (Optional) | |
306 | ||
e8769719 | 307 | =item B<-digest> I<digest_bytes> |
c7235be6 UM |
308 | |
309 | The response or token must be verified against the message digest specified | |
310 | with this option. The number of bytes must match the message digest algorithm | |
311 | specified in the token. The B<-data> and B<-queryfile> options must not be | |
312 | specified with this one. (Optional) | |
313 | ||
e8769719 | 314 | =item B<-queryfile> I<request.tsq> |
c7235be6 | 315 | |
9c0586d5 | 316 | The original timestamp request in DER format. The B<-data> and B<-digest> |
c7235be6 UM |
317 | options must not be specified with this one. (Optional) |
318 | ||
e8769719 | 319 | =item B<-in> I<response.tsr> |
c7235be6 | 320 | |
9c0586d5 | 321 | The timestamp response that needs to be verified in DER format. (Mandatory) |
c7235be6 UM |
322 | |
323 | =item B<-token_in> | |
324 | ||
325 | This flag can be used together with the B<-in> option and indicates | |
9c0586d5 RS |
326 | that the input is a DER encoded timestamp token (ContentInfo) instead |
327 | of a timestamp response (TimeStampResp). (Optional) | |
c7235be6 | 328 | |
f62846b7 | 329 | =item B<-untrusted> I<files>|I<uris> |
c7235be6 | 330 | |
c89fd035 DDO |
331 | A set of additional untrusted certificates which may be |
332 | needed when building the certificate chain for the TSA's signing certificate. | |
333 | These do not need to contain the TSA signing certificate and intermediate CA | |
334 | certificates as far as the response already includes them. | |
c7235be6 UM |
335 | (Optional) |
336 | ||
f62846b7 DDO |
337 | Multiple sources may be given, separated by commas and/or whitespace. |
338 | Each file may contain multiple certificates. | |
339 | ||
03e16083 | 340 | =item B<-CAfile> I<file>, B<-CApath> I<dir>, B<-CAstore> I<uri> |
21d08b9e | 341 | |
ac093b3f AS |
342 | See L<openssl-verification-options(1)/Trusted Certificate Options> for details. |
343 | At least one of B<-CAfile>, B<-CApath> or B<-CAstore> must be specified. | |
21d08b9e RS |
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 | |
6f72b210 | 375 | object identifier followed by whitespace then the short name followed |
376 | by whitespace 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 | |
63b64f19 DDO |
472 | attribute (see RFC 2634, Enhanced Security Services). |
473 | If this variable is set to no, only this signing certificate identifier | |
474 | is included in the SigningCertificate signed attribute. | |
475 | If this variable is set to yes and the B<certs> variable or the B<-chain> option | |
c7235be6 | 476 | is specified then the certificate identifiers of the chain will also |
63b64f19 DDO |
477 | be included, where the B<-chain> option overrides the B<certs> variable. |
478 | Default is no. (Optional) | |
c7235be6 | 479 | |
f0ef20bf MK |
480 | =item B<ess_cert_id_alg> |
481 | ||
482 | This option specifies the hash function to be used to calculate the TSA's | |
a6dfa188 | 483 | public key certificate identifier. Default is sha256. (Optional) |
f0ef20bf | 484 | |
c7235be6 UM |
485 | =back |
486 | ||
c7235be6 UM |
487 | =head1 EXAMPLES |
488 | ||
489 | All the examples below presume that B<OPENSSL_CONF> is set to a proper | |
4c583c36 | 490 | configuration file, e.g. the example configuration file |
1948394d | 491 | F<openssl/apps/openssl.cnf> will do. |
c7235be6 | 492 | |
9c0586d5 | 493 | =head2 Timestamp Request |
c7235be6 | 494 | |
1948394d | 495 | To create a timestamp request for F<design1.txt> with SHA-256 digest, |
02f209bb TM |
496 | without nonce and policy, and without requirement for a certificate |
497 | in the response: | |
c7235be6 UM |
498 | |
499 | openssl ts -query -data design1.txt -no_nonce \ | |
1bc74519 | 500 | -out design1.tsq |
c7235be6 | 501 | |
9c0586d5 | 502 | To create a similar timestamp request with specifying the message imprint |
c7235be6 UM |
503 | explicitly: |
504 | ||
505 | openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ | |
1bc74519 | 506 | -no_nonce -out design1.tsq |
c7235be6 UM |
507 | |
508 | To print the content of the previous request in human readable format: | |
509 | ||
510 | openssl ts -query -in design1.tsq -text | |
511 | ||
9c0586d5 | 512 | To create a timestamp request which includes the SHA-512 digest |
1948394d | 513 | of F<design2.txt>, requests the signer certificate and nonce, and |
c7235be6 UM |
514 | specifies a policy id (assuming the tsa_policy1 name is defined in the |
515 | OID section of the config file): | |
516 | ||
a6dfa188 | 517 | openssl ts -query -data design2.txt -sha512 \ |
1bc74519 | 518 | -tspolicy tsa_policy1 -cert -out design2.tsq |
c7235be6 | 519 | |
9c0586d5 | 520 | =head2 Timestamp Response |
c7235be6 UM |
521 | |
522 | Before generating a response a signing certificate must be created for | |
523 | the TSA that contains the B<timeStamping> critical extended key usage extension | |
dfee8626 RS |
524 | without any other key usage extensions. You can add this line to the |
525 | user certificate section of the config file to generate a proper certificate; | |
526 | ||
527 | extendedKeyUsage = critical,timeStamping | |
528 | ||
8bc93d2f RL |
529 | See L<openssl-req(1)>, L<openssl-ca(1)>, and L<openssl-x509(1)> for |
530 | instructions. The examples below assume that F<cacert.pem> contains the | |
531 | certificate of the CA, F<tsacert.pem> is the signing certificate issued | |
532 | by F<cacert.pem> and F<tsakey.pem> is the private key of the TSA. | |
c7235be6 | 533 | |
9c0586d5 | 534 | To create a timestamp response for a request: |
c7235be6 UM |
535 | |
536 | openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ | |
1bc74519 | 537 | -signer tsacert.pem -out design1.tsr |
c7235be6 UM |
538 | |
539 | If you want to use the settings in the config file you could just write: | |
540 | ||
541 | openssl ts -reply -queryfile design1.tsq -out design1.tsr | |
542 | ||
9c0586d5 | 543 | To print a timestamp reply to stdout in human readable format: |
c7235be6 UM |
544 | |
545 | openssl ts -reply -in design1.tsr -text | |
546 | ||
9c0586d5 | 547 | To create a timestamp token instead of timestamp response: |
c7235be6 UM |
548 | |
549 | openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out | |
550 | ||
9c0586d5 | 551 | To print a timestamp token to stdout in human readable format: |
c7235be6 UM |
552 | |
553 | openssl ts -reply -in design1_token.der -token_in -text -token_out | |
554 | ||
9c0586d5 | 555 | To extract the timestamp token from a response: |
c7235be6 UM |
556 | |
557 | openssl ts -reply -in design1.tsr -out design1_token.der -token_out | |
558 | ||
9c0586d5 | 559 | To add 'granted' status info to a timestamp token thereby creating a |
c7235be6 UM |
560 | valid response: |
561 | ||
562 | openssl ts -reply -in design1_token.der -token_in -out design1.tsr | |
563 | ||
9c0586d5 | 564 | =head2 Timestamp Verification |
c7235be6 | 565 | |
9c0586d5 | 566 | To verify a timestamp reply against a request: |
c7235be6 UM |
567 | |
568 | openssl ts -verify -queryfile design1.tsq -in design1.tsr \ | |
1bc74519 | 569 | -CAfile cacert.pem -untrusted tsacert.pem |
c7235be6 | 570 | |
9c0586d5 | 571 | To verify a timestamp reply that includes the certificate chain: |
c7235be6 UM |
572 | |
573 | openssl ts -verify -queryfile design2.tsq -in design2.tsr \ | |
1bc74519 | 574 | -CAfile cacert.pem |
c7235be6 | 575 | |
9c0586d5 | 576 | To verify a timestamp token against the original data file: |
c7235be6 | 577 | openssl ts -verify -data design2.txt -in design2.tsr \ |
1bc74519 | 578 | -CAfile cacert.pem |
c7235be6 | 579 | |
9c0586d5 | 580 | To verify a timestamp token against a message imprint: |
c7235be6 | 581 | openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ |
1bc74519 | 582 | -in design2.tsr -CAfile cacert.pem |
c7235be6 UM |
583 | |
584 | You could also look at the 'test' directory for more examples. | |
585 | ||
586 | =head1 BUGS | |
587 | ||
fadb57e5 | 588 | =for openssl foreign manual procmail(1) perl(1) |
b275f3b6 | 589 | |
2f61bc2e RS |
590 | =over 2 |
591 | ||
592 | =item * | |
c7235be6 | 593 | |
9c0586d5 | 594 | No support for timestamps over SMTP, though it is quite easy |
9b86974e RS |
595 | to implement an automatic e-mail based TSA with L<procmail(1)> |
596 | and L<perl(1)>. HTTP server support is provided in the form of | |
c7235be6 | 597 | a separate apache module. HTTP client support is provided by |
9b86974e | 598 | L<tsget(1)>. Pure TCP/IP protocol is not supported. |
c7235be6 | 599 | |
2f61bc2e RS |
600 | =item * |
601 | ||
602 | The file containing the last serial number of the TSA is not | |
c7235be6 | 603 | locked when being read or written. This is a problem if more than one |
9c0586d5 | 604 | instance of L<openssl(1)> is trying to create a timestamp |
c7235be6 UM |
605 | response at the same time. This is not an issue when using the apache |
606 | server module, it does proper locking. | |
607 | ||
2f61bc2e RS |
608 | =item * |
609 | ||
610 | Look for the FIXME word in the source files. | |
611 | ||
612 | =item * | |
613 | ||
614 | The source code should really be reviewed by somebody else, too. | |
c7235be6 | 615 | |
2f61bc2e | 616 | =item * |
c7235be6 | 617 | |
2f61bc2e | 618 | More testing is needed, I have done only some basic tests (see |
c7235be6 UM |
619 | test/testtsa). |
620 | ||
621 | =back | |
622 | ||
23f39931 DMSP |
623 | =head1 HISTORY |
624 | ||
625 | OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an improved | |
626 | seeding mechanism. The new seeding mechanism makes it unnecessary to | |
627 | define a RANDFILE for saving and restoring randomness. This option is | |
628 | retained mainly for compatibility reasons. | |
629 | ||
0f221d9c P |
630 | The B<-engine> option was deprecated in OpenSSL 3.0. |
631 | ||
c7235be6 UM |
632 | =head1 SEE ALSO |
633 | ||
b6b66573 | 634 | L<openssl(1)>, |
fadb57e5 | 635 | L<tsget(1)>, |
b6b66573 DMSP |
636 | L<openssl-req(1)>, |
637 | L<openssl-x509(1)>, | |
638 | L<openssl-ca(1)>, | |
639 | L<openssl-genrsa(1)>, | |
fd3397fc RL |
640 | L<config(5)>, |
641 | L<ossl_store-file(7)> | |
c7235be6 | 642 | |
e2f92610 RS |
643 | =head1 COPYRIGHT |
644 | ||
33388b44 | 645 | Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 646 | |
449040b4 | 647 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
648 | this file except in compliance with the License. You can obtain a copy |
649 | in the file LICENSE in the source distribution or at | |
650 | L<https://www.openssl.org/source/license.html>. | |
651 | ||
652 | =cut |