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