1OPENSSL-TS(1ossl) OpenSSL OPENSSL-TS(1ossl)
2
6 openssl-ts - Time Stamping Authority command
7
9 openssl ts -help
10 openssl ts -query [-config configfile] [-data file_to_hash] [-digest
12 digest_bytes] [-digest] [-tspolicy object_id] [-no_nonce] [-cert] [-in
13 request.tsq] [-out request.tsq] [-text] [-rand files] [-writerand file]
14 [-provider name] [-provider-path path] [-propquery propq]
15 openssl ts -reply [-config configfile] [-section tsa_section]
17 [-queryfile request.tsq] [-passin password_src] [-signer tsa_cert.pem]
18 [-inkey filename|uri] [-digest] [-chain certs_file.pem] [-tspolicy
19 object_id] [-in response.tsr] [-token_in] [-out response.tsr]
20 [-token_out] [-text] [-engine id] [-provider name] [-provider-path
21 path] [-propquery propq]
22 openssl ts -verify [-data file_to_hash] [-digest digest_bytes]
24 [-queryfile request.tsq] [-in response.tsr] [-token_in] [-untrusted
25 files|uris] [-CAfile file] [-CApath dir] [-CAstore uri]
26 [-allow_proxy_certs] [-attime timestamp] [-no_check_time]
27 [-check_ss_sig] [-crl_check] [-crl_check_all] [-explicit_policy]
28 [-extended_crl] [-ignore_critical] [-inhibit_any] [-inhibit_map]
29 [-partial_chain] [-policy arg] [-policy_check] [-policy_print]
30 [-purpose purpose] [-suiteB_128] [-suiteB_128_only] [-suiteB_192]
31 [-trusted_first] [-no_alt_chains] [-use_deltas] [-auth_level num]
32 [-verify_depth num] [-verify_email email] [-verify_hostname hostname]
33 [-verify_ip ip] [-verify_name name] [-x509_strict] [-issuer_checks]
34 [-provider name] [-provider-path path] [-propquery propq]
35
37 This command is a basic Time Stamping Authority (TSA) client and server
38 application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A TSA
39 can be part of a PKI deployment and its role is to provide long term
40 proof of the existence of a certain datum before a particular time.
41 Here is a brief description of the protocol:
42 1. The TSA client computes a one-way hash value for a data file and
44 sends the hash to the TSA.
45 2. The TSA attaches the current date and time to the received hash
47 value, signs them and sends the timestamp token back to the client.
48 By creating this token the TSA certifies the existence of the
49 original data file at the time of response generation.
50 3. The TSA client receives the timestamp token and verifies the
52 signature on it. It also checks if the token contains the same hash
53 value that it had sent to the TSA.
54 There is one DER encoded protocol data unit defined for transporting a
56 timestamp request to the TSA and one for sending the timestamp response
57 back to the client. This command has three main functions: creating a
58 timestamp request based on a data file, creating a timestamp response
59 based on a request, verifying if a response corresponds to a particular
60 request or a data file.
61 There is no support for sending the requests/responses automatically
63 over HTTP or TCP yet as suggested in RFC 3161. The users must send the
64 requests either by ftp or e-mail.
65
67 -help
68 Print out a usage message.
69 -query
71 Generate a TS query. For details see "Timestamp Request
72 generation".
73 -reply
75 Generate a TS reply. For details see "Timestamp Response
76 generation".
77 -verify
79 Verify a TS response. For details see "Timestamp Response
80 verification".
81 Timestamp Request generation
83 The -query command can be used for creating and printing a timestamp
84 request with the following options:
85 -config configfile
87 The configuration file to use. Optional; for a description of the
88 default value, see "COMMAND SUMMARY" in openssl(1).
89 -data file_to_hash
91 The data file for which the timestamp request needs to be created.
92 stdin is the default if neither the -data nor the -digest parameter
93 is specified. (Optional)
94 -digest digest_bytes
96 It is possible to specify the message imprint explicitly without
97 the data file. The imprint must be specified in a hexadecimal
98 format, two characters per byte, the bytes optionally separated by
99 colons (e.g. 1A:F6:01:... or 1AF601...). The number of bytes must
100 match the message digest algorithm in use. (Optional)
101 -digest
103 The message digest to apply to the data file. Any digest supported
104 by the openssl-dgst(1) command can be used. The default is
105 SHA-256. (Optional)
106 -tspolicy object_id
108 The policy that the client expects the TSA to use for creating the
109 timestamp token. Either the dotted OID notation or OID names
110 defined in the config file can be used. If no policy is requested
111 the TSA will use its own default policy. (Optional)
112 -no_nonce
114 No nonce is specified in the request if this option is given.
115 Otherwise a 64 bit long pseudo-random none is included in the
116 request. It is recommended to use nonce to protect against replay-
117 attacks. (Optional)
118 -cert
120 The TSA is expected to include its signing certificate in the
121 response. (Optional)
122 -in request.tsq
124 This option specifies a previously created timestamp request in DER
125 format that will be printed into the output file. Useful when you
126 need to examine the content of a request in human-readable format.
127 (Optional)
128 -out request.tsq
130 Name of the output file to which the request will be written.
131 Default is stdout. (Optional)
132 -text
134 If this option is specified the output is human-readable text
135 format instead of DER. (Optional)
136 -rand files, -writerand file
138 See "Random State Options" in openssl(1) for details.
139 Timestamp Response generation
141 A timestamp response (TimeStampResp) consists of a response status and
142 the timestamp token itself (ContentInfo), if the token generation was
143 successful. The -reply command is for creating a timestamp response or
144 timestamp token based on a request and printing the response/token in
145 human-readable format. If -token_out is not specified the output is
146 always a timestamp response (TimeStampResp), otherwise it is a
147 timestamp token (ContentInfo).
148 -config configfile
150 The configuration file to use. Optional; for a description of the
151 default value, see "COMMAND SUMMARY" in openssl(1). See
152 "CONFIGURATION FILE OPTIONS" for configurable variables.
153 -section tsa_section
155 The name of the config file section containing the settings for the
156 response generation. If not specified the default TSA section is
157 used, see "CONFIGURATION FILE OPTIONS" for details. (Optional)
158 -queryfile request.tsq
160 The name of the file containing a DER encoded timestamp request.
161 (Optional)
162 -passin password_src
164 Specifies the password source for the private key of the TSA. See
165 description in openssl(1). (Optional)
166 -signer tsa_cert.pem
168 The signer certificate of the TSA in PEM format. The TSA signing
169 certificate must have exactly one extended key usage assigned to
170 it: timeStamping. The extended key usage must also be critical,
171 otherwise the certificate is going to be refused. Overrides the
172 signer_cert variable of the config file. (Optional)
173 -inkey filename|uri
175 The signer private key of the TSA in PEM format. Overrides the
176 signer_key config file option. (Optional)
177 -digest
179 Signing digest to use. Overrides the signer_digest config file
180 option. (Mandatory unless specified in the config file)
181 -chain certs_file.pem
183 The collection of certificates in PEM format that will all be
184 included in the response in addition to the signer certificate if
185 the -cert option was used for the request. This file is supposed to
186 contain the certificate chain for the signer certificate from its
187 issuer upwards. The -reply command does not build a certificate
188 chain automatically. (Optional)
189 -tspolicy object_id
191 The default policy to use for the response unless the client
192 explicitly requires a particular TSA policy. The OID can be
193 specified either in dotted notation or with its name. Overrides the
194 default_policy config file option. (Optional)
195 -in response.tsr
197 Specifies a previously created timestamp response or timestamp
198 token (if -token_in is also specified) in DER format that will be
199 written to the output file. This option does not require a request,
200 it is useful e.g. when you need to examine the content of a
201 response or token or you want to extract the timestamp token from a
202 response. If the input is a token and the output is a timestamp
203 response a default 'granted' status info is added to the token.
204 (Optional)
205 -token_in
207 This flag can be used together with the -in option and indicates
208 that the input is a DER encoded timestamp token (ContentInfo)
209 instead of a timestamp response (TimeStampResp). (Optional)
210 -out response.tsr
212 The response is written to this file. The format and content of the
213 file depends on other options (see -text, -token_out). The default
214 is stdout. (Optional)
215 -token_out
217 The output is a timestamp token (ContentInfo) instead of timestamp
218 response (TimeStampResp). (Optional)
219 -text
221 If this option is specified the output is human-readable text
222 format instead of DER. (Optional)
223 -engine id
225 See "Engine Options" in openssl(1). This option is deprecated.
226 -provider name
228 -provider-path path
229 -propquery propq
230 See "Provider Options" in openssl(1), provider(7), and property(7).
231 Timestamp Response verification
233 The -verify command is for verifying if a timestamp response or
234 timestamp token is valid and matches a particular timestamp request or
235 data file. The -verify command does not use the configuration file.
236 -data file_to_hash
238 The response or token must be verified against file_to_hash. The
239 file is hashed with the message digest algorithm specified in the
240 token. The -digest and -queryfile options must not be specified
241 with this one. (Optional)
242 -digest digest_bytes
244 The response or token must be verified against the message digest
245 specified with this option. The number of bytes must match the
246 message digest algorithm specified in the token. The -data and
247 -queryfile options must not be specified with this one. (Optional)
248 -queryfile request.tsq
250 The original timestamp request in DER format. The -data and -digest
251 options must not be specified with this one. (Optional)
252 -in response.tsr
254 The timestamp response that needs to be verified in DER format.
255 (Mandatory)
256 -token_in
258 This flag can be used together with the -in option and indicates
259 that the input is a DER encoded timestamp token (ContentInfo)
260 instead of a timestamp response (TimeStampResp). (Optional)
261 -untrusted files|uris
263 A set of additional untrusted certificates which may be needed when
264 building the certificate chain for the TSA's signing certificate.
265 These do not need to contain the TSA signing certificate and
266 intermediate CA certificates as far as the response already
267 includes them. (Optional)
268 Multiple sources may be given, separated by commas and/or
270 whitespace. Each file may contain multiple certificates.
271 -CAfile file, -CApath dir, -CAstore uri
273 See "Trusted Certificate Options" in
274 openssl-verification-options(1) for details. At least one of
275 -CAfile, -CApath or -CAstore must be specified.
276 -allow_proxy_certs, -attime, -no_check_time, -check_ss_sig, -crl_check,
278 -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical,
279 -inhibit_any, -inhibit_map, -no_alt_chains, -partial_chain, -policy,
280 -policy_check, -policy_print, -purpose, -suiteB_128, -suiteB_128_only,
281 -suiteB_192, -trusted_first, -use_deltas, -auth_level, -verify_depth,
282 -verify_email, -verify_hostname, -verify_ip, -verify_name, -x509_strict
283 -issuer_checks
284 Set various options of certificate chain verification. See
285 "Verification Options" in openssl-verification-options(1) for
286 details.
287 Any verification errors cause the command to exit.
289
291 The -query and -reply commands make use of a configuration file. See
292 config(5) for a general description of the syntax of the config file.
293 The -query command uses only the symbolic OID names section and it can
294 work without it. However, the -reply command needs the config file for
295 its operation.
296 When there is a command line switch equivalent of a variable the switch
298 always overrides the settings in the config file.
299 tsa section, default_tsa
301 This is the main section and it specifies the name of another
302 section that contains all the options for the -reply command. This
303 default section can be overridden with the -section command line
304 switch. (Optional)
305 oid_file
307 This specifies a file containing additional OBJECT IDENTIFIERS.
308 Each line of the file should consist of the numerical form of the
309 object identifier followed by whitespace then the short name
310 followed by whitespace and finally the long name. (Optional)
311 oid_section
313 This specifies a section in the configuration file containing extra
314 object identifiers. Each line should consist of the short name of
315 the object identifier followed by = and the numerical form. The
316 short and long names are the same when this option is used.
317 (Optional)
318 RANDFILE
320 At startup the specified file is loaded into the random number
321 generator, and at exit 256 bytes will be written to it. (Note:
322 Using a RANDFILE is not necessary anymore, see the "HISTORY"
323 section.
324 serial
326 The name of the file containing the hexadecimal serial number of
327 the last timestamp response created. This number is incremented by
328 1 for each response. If the file does not exist at the time of
329 response generation a new file is created with serial number 1.
330 (Mandatory)
331 crypto_device
333 Specifies the OpenSSL engine that will be set as the default for
334 all available algorithms. The default value is built-in, you can
335 specify any other engines supported by OpenSSL (e.g. use chil for
336 the NCipher HSM). (Optional)
337 signer_cert
339 TSA signing certificate in PEM format. The same as the -signer
340 command line option. (Optional)
341 certs
343 A file containing a set of PEM encoded certificates that need to be
344 included in the response. The same as the -chain command line
345 option. (Optional)
346 signer_key
348 The private key of the TSA in PEM format. The same as the -inkey
349 command line option. (Optional)
350 signer_digest
352 Signing digest to use. The same as the -digest command line option.
353 (Mandatory unless specified on the command line)
354 default_policy
356 The default policy to use when the request does not mandate any
357 policy. The same as the -tspolicy command line option. (Optional)
358 other_policies
360 Comma separated list of policies that are also acceptable by the
361 TSA and used only if the request explicitly specifies one of them.
362 (Optional)
363 digests
365 The list of message digest algorithms that the TSA accepts. At
366 least one algorithm must be specified. (Mandatory)
367 accuracy
369 The accuracy of the time source of the TSA in seconds, milliseconds
370 and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any
371 of the components is missing zero is assumed for that field.
372 (Optional)
373 clock_precision_digits
375 Specifies the maximum number of digits, which represent the
376 fraction of seconds, that need to be included in the time field.
377 The trailing zeros must be removed from the time, so there might
378 actually be fewer digits, or no fraction of seconds at all.
379 Supported only on UNIX platforms. The maximum value is 6, default
380 is 0. (Optional)
381 ordering
383 If this option is yes the responses generated by this TSA can
384 always be ordered, even if the time difference between two
385 responses is less than the sum of their accuracies. Default is no.
386 (Optional)
387 tsa_name
389 Set this option to yes if the subject name of the TSA must be
390 included in the TSA name field of the response. Default is no.
391 (Optional)
392 ess_cert_id_chain
394 The SignedData objects created by the TSA always contain the
395 certificate identifier of the signing certificate in a signed
396 attribute (see RFC 2634, Enhanced Security Services). If this
397 variable is set to no, only this signing certificate identifier is
398 included in the SigningCertificate signed attribute. If this
399 variable is set to yes and the certs variable or the -chain option
400 is specified then the certificate identifiers of the chain will
401 also be included, where the -chain option overrides the certs
402 variable. Default is no. (Optional)
403 ess_cert_id_alg
405 This option specifies the hash function to be used to calculate the
406 TSA's public key certificate identifier. Default is sha256.
407 (Optional)
408
410 All the examples below presume that OPENSSL_CONF is set to a proper
411 configuration file, e.g. the example configuration file
412 openssl/apps/openssl.cnf will do.
413 Timestamp Request
415 To create a timestamp request for design1.txt with SHA-256 digest,
416 without nonce and policy, and without requirement for a certificate in
417 the response:
418 openssl ts -query -data design1.txt -no_nonce \
420 -out design1.tsq
421 To create a similar timestamp request with specifying the message
423 imprint explicitly:
424 openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
426 -no_nonce -out design1.tsq
427 To print the content of the previous request in human readable format:
429 openssl ts -query -in design1.tsq -text
431 To create a timestamp request which includes the SHA-512 digest of
433 design2.txt, requests the signer certificate and nonce, and specifies a
434 policy id (assuming the tsa_policy1 name is defined in the OID section
435 of the config file):
436 openssl ts -query -data design2.txt -sha512 \
438 -tspolicy tsa_policy1 -cert -out design2.tsq
439 Timestamp Response
441 Before generating a response a signing certificate must be created for
442 the TSA that contains the timeStamping critical extended key usage
443 extension without any other key usage extensions. You can add this line
444 to the user certificate section of the config file to generate a proper
445 certificate;
446 extendedKeyUsage = critical,timeStamping
448 See openssl-req(1), openssl-ca(1), and openssl-x509(1) for
450 instructions. The examples below assume that cacert.pem contains the
451 certificate of the CA, tsacert.pem is the signing certificate issued by
452 cacert.pem and tsakey.pem is the private key of the TSA.
453 To create a timestamp response for a request:
455 openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
457 -signer tsacert.pem -out design1.tsr
458 If you want to use the settings in the config file you could just
460 write:
461 openssl ts -reply -queryfile design1.tsq -out design1.tsr
463 To print a timestamp reply to stdout in human readable format:
465 openssl ts -reply -in design1.tsr -text
467 To create a timestamp token instead of timestamp response:
469 openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
471 To print a timestamp token to stdout in human readable format:
473 openssl ts -reply -in design1_token.der -token_in -text -token_out
475 To extract the timestamp token from a response:
477 openssl ts -reply -in design1.tsr -out design1_token.der -token_out
479 To add 'granted' status info to a timestamp token thereby creating a
481 valid response:
482 openssl ts -reply -in design1_token.der -token_in -out design1.tsr
484 Timestamp Verification
486 To verify a timestamp reply against a request:
487 openssl ts -verify -queryfile design1.tsq -in design1.tsr \
489 -CAfile cacert.pem -untrusted tsacert.pem
490 To verify a timestamp reply that includes the certificate chain:
492 openssl ts -verify -queryfile design2.tsq -in design2.tsr \
494 -CAfile cacert.pem
495 To verify a timestamp token against the original data file:
497 openssl ts -verify -data design2.txt -in design2.tsr \
498 -CAfile cacert.pem
499 To verify a timestamp token against a message imprint:
501 openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
502 -in design2.tsr -CAfile cacert.pem
503 You could also look at the 'test' directory for more examples.
505
507 • No support for timestamps over SMTP, though it is quite easy to
508 implement an automatic e-mail based TSA with procmail(1) and perl(1).
509 HTTP server support is provided in the form of a separate apache
510 module. HTTP client support is provided by tsget(1). Pure TCP/IP
511 protocol is not supported.
512 • The file containing the last serial number of the TSA is not locked
514 when being read or written. This is a problem if more than one
515 instance of openssl(1) is trying to create a timestamp response at
516 the same time. This is not an issue when using the apache server
517 module, it does proper locking.
518 • Look for the FIXME word in the source files.
520 • The source code should really be reviewed by somebody else, too.
522 • More testing is needed, I have done only some basic tests (see
524 test/testtsa).
525
527 OpenSSL 1.1.1 introduced a new random generator (CSPRNG) with an
528 improved seeding mechanism. The new seeding mechanism makes it
529 unnecessary to define a RANDFILE for saving and restoring randomness.
530 This option is retained mainly for compatibility reasons.
531 The -engine option was deprecated in OpenSSL 3.0.
533
535 openssl(1), tsget(1), openssl-req(1), openssl-x509(1), openssl-ca(1),
536 openssl-genrsa(1), config(5), ossl_store-file(7)
537
539 Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
540 Licensed under the Apache License 2.0 (the "License"). You may not use
542 this file except in compliance with the License. You can obtain a copy
543 in the file LICENSE in the source distribution or at
544 <https://www.openssl.org/source/license.html>.
5453.1.1 2023-08-31 OPENSSL-TS(1ossl)