1TS(1) OpenSSL TS(1)
2
6 openssl-ts, ts - Time Stamping Authority tool (client/server)
7
9 openssl ts -query [-rand file...] [-writerand file] [-config
10 configfile] [-data file_to_hash] [-digest digest_bytes] [-digest]
11 [-tspolicy object_id] [-no_nonce] [-cert] [-in request.tsq] [-out
12 request.tsq] [-text]
13 openssl ts -reply [-config configfile] [-section tsa_section]
15 [-queryfile request.tsq] [-passin password_src] [-signer tsa_cert.pem]
16 [-inkey file_or_id] [-digest] [-chain certs_file.pem] [-tspolicy
17 object_id] [-in response.tsr] [-token_in] [-out response.tsr]
18 [-token_out] [-text] [-engine id]
19 openssl ts -verify [-data file_to_hash] [-digest digest_bytes]
21 [-queryfile request.tsq] [-in response.tsr] [-token_in] [-CApath
22 trusted_cert_path] [-CAfile trusted_certs.pem] [-untrusted
23 cert_file.pem] [verify options]
24 verify options: [-attime timestamp] [-check_ss_sig] [-crl_check]
26 [-crl_check_all] [-explicit_policy] [-extended_crl] [-ignore_critical]
27 [-inhibit_any] [-inhibit_map] [-issuer_checks] [-no_alt_chains]
28 [-no_check_time] [-partial_chain] [-policy arg] [-policy_check]
29 [-policy_print] [-purpose purpose] [-suiteB_128] [-suiteB_128_only]
30 [-suiteB_192] [-trusted_first] [-use_deltas] [-auth_level num]
31 [-verify_depth num] [-verify_email email] [-verify_hostname hostname]
32 [-verify_ip ip] [-verify_name name] [-x509_strict]
33
35 The ts command is a basic Time Stamping Authority (TSA) client and
36 server application as specified in RFC 3161 (Time-Stamp Protocol, TSP).
37 A TSA can be part of a PKI deployment and its role is to provide long
38 term proof of the existence of a certain datum before a particular
39 time. Here is a brief description of the protocol:
40 1. The TSA client computes a one-way hash value for a data file and
42 sends the hash to the TSA.
43 2. The TSA attaches the current date and time to the received hash
45 value, signs them and sends the timestamp token back to the client.
46 By creating this token the TSA certifies the existence of the
47 original data file at the time of response generation.
48 3. The TSA client receives the timestamp token and verifies the
50 signature on it. It also checks if the token contains the same hash
51 value that it had sent to the TSA.
52 There is one DER encoded protocol data unit defined for transporting a
54 timestamp request to the TSA and one for sending the timestamp response
55 back to the client. The ts command has three main functions: creating a
56 timestamp request based on a data file, creating a timestamp response
57 based on a request, verifying if a response corresponds to a particular
58 request or a data file.
59 There is no support for sending the requests/responses automatically
61 over HTTP or TCP yet as suggested in RFC 3161. The users must send the
62 requests either by ftp or e-mail.
63
65 Time Stamp Request generation
66 The -query switch can be used for creating and printing a timestamp
67 request with the following options:
68 -rand file...
70 A file or files containing random data used to seed the random
71 number generator. Multiple files can be specified separated by an
72 OS-dependent character. The separator is ; for MS-Windows, , for
73 OpenVMS, and : for all others.
74 [-writerand file]
76 Writes random data to the specified file upon exit. This can be
77 used with a subsequent -rand flag.
78 -config configfile
80 The configuration file to use. Optional; for a description of the
81 default value, see "COMMAND SUMMARY" in openssl(1).
82 -data file_to_hash
84 The data file for which the timestamp request needs to be created.
85 stdin is the default if neither the -data nor the -digest parameter
86 is specified. (Optional)
87 -digest digest_bytes
89 It is possible to specify the message imprint explicitly without
90 the data file. The imprint must be specified in a hexadecimal
91 format, two characters per byte, the bytes optionally separated by
92 colons (e.g. 1A:F6:01:... or 1AF601...). The number of bytes must
93 match the message digest algorithm in use. (Optional)
94 -digest
96 The message digest to apply to the data file. Any digest supported
97 by the OpenSSL dgst command can be used. The default is SHA-1.
98 (Optional)
99 -tspolicy object_id
101 The policy that the client expects the TSA to use for creating the
102 timestamp token. Either the dotted OID notation or OID names
103 defined in the config file can be used. If no policy is requested
104 the TSA will use its own default policy. (Optional)
105 -no_nonce
107 No nonce is specified in the request if this option is given.
108 Otherwise a 64 bit long pseudo-random none is included in the
109 request. It is recommended to use nonce to protect against replay-
110 attacks. (Optional)
111 -cert
113 The TSA is expected to include its signing certificate in the
114 response. (Optional)
115 -in request.tsq
117 This option specifies a previously created timestamp request in DER
118 format that will be printed into the output file. Useful when you
119 need to examine the content of a request in human-readable format.
120 (Optional)
121 -out request.tsq
123 Name of the output file to which the request will be written.
124 Default is stdout. (Optional)
125 -text
127 If this option is specified the output is human-readable text
128 format instead of DER. (Optional)
129 Time Stamp Response generation
131 A timestamp response (TimeStampResp) consists of a response status and
132 the timestamp token itself (ContentInfo), if the token generation was
133 successful. The -reply command is for creating a timestamp response or
134 timestamp token based on a request and printing the response/token in
135 human-readable format. If -token_out is not specified the output is
136 always a timestamp response (TimeStampResp), otherwise it is a
137 timestamp token (ContentInfo).
138 -config configfile
140 The configuration file to use. Optional; for a description of the
141 default value, see "COMMAND SUMMARY" in openssl(1). See
142 CONFIGURATION FILE OPTIONS for configurable variables.
143 -section tsa_section
145 The name of the config file section containing the settings for the
146 response generation. If not specified the default TSA section is
147 used, see CONFIGURATION FILE OPTIONS for details. (Optional)
148 -queryfile request.tsq
150 The name of the file containing a DER encoded timestamp request.
151 (Optional)
152 -passin password_src
154 Specifies the password source for the private key of the TSA. See
155 "Pass Phrase Options" in openssl(1). (Optional)
156 -signer tsa_cert.pem
158 The signer certificate of the TSA in PEM format. The TSA signing
159 certificate must have exactly one extended key usage assigned to
160 it: timeStamping. The extended key usage must also be critical,
161 otherwise the certificate is going to be refused. Overrides the
162 signer_cert variable of the config file. (Optional)
163 -inkey file_or_id
165 The signer private key of the TSA in PEM format. Overrides the
166 signer_key config file option. (Optional) If no engine is used, the
167 argument is taken as a file; if an engine is specified, the
168 argument is given to the engine as a key identifier.
169 -digest
171 Signing digest to use. Overrides the signer_digest config file
172 option. (Mandatory unless specified in the config file)
173 -chain certs_file.pem
175 The collection of certificates in PEM format that will all be
176 included in the response in addition to the signer certificate if
177 the -cert option was used for the request. This file is supposed to
178 contain the certificate chain for the signer certificate from its
179 issuer upwards. The -reply command does not build a certificate
180 chain automatically. (Optional)
181 -tspolicy object_id
183 The default policy to use for the response unless the client
184 explicitly requires a particular TSA policy. The OID can be
185 specified either in dotted notation or with its name. Overrides the
186 default_policy config file option. (Optional)
187 -in response.tsr
189 Specifies a previously created timestamp response or timestamp
190 token (if -token_in is also specified) in DER format that will be
191 written to the output file. This option does not require a request,
192 it is useful e.g. when you need to examine the content of a
193 response or token or you want to extract the timestamp token from a
194 response. If the input is a token and the output is a timestamp
195 response a default 'granted' status info is added to the token.
196 (Optional)
197 -token_in
199 This flag can be used together with the -in option and indicates
200 that the input is a DER encoded timestamp token (ContentInfo)
201 instead of a timestamp response (TimeStampResp). (Optional)
202 -out response.tsr
204 The response is written to this file. The format and content of the
205 file depends on other options (see -text, -token_out). The default
206 is stdout. (Optional)
207 -token_out
209 The output is a timestamp token (ContentInfo) instead of timestamp
210 response (TimeStampResp). (Optional)
211 -text
213 If this option is specified the output is human-readable text
214 format instead of DER. (Optional)
215 -engine id
217 Specifying an engine (by its unique id string) will cause ts to
218 attempt to obtain a functional reference to the specified engine,
219 thus initialising it if needed. The engine will then be set as the
220 default for all available algorithms. Default is builtin.
221 (Optional)
222 Time Stamp Response verification
224 The -verify command is for verifying if a timestamp response or
225 timestamp token is valid and matches a particular timestamp request or
226 data file. The -verify command does not use the configuration file.
227 -data file_to_hash
229 The response or token must be verified against file_to_hash. The
230 file is hashed with the message digest algorithm specified in the
231 token. The -digest and -queryfile options must not be specified
232 with this one. (Optional)
233 -digest digest_bytes
235 The response or token must be verified against the message digest
236 specified with this option. The number of bytes must match the
237 message digest algorithm specified in the token. The -data and
238 -queryfile options must not be specified with this one. (Optional)
239 -queryfile request.tsq
241 The original timestamp request in DER format. The -data and -digest
242 options must not be specified with this one. (Optional)
243 -in response.tsr
245 The timestamp response that needs to be verified in DER format.
246 (Mandatory)
247 -token_in
249 This flag can be used together with the -in option and indicates
250 that the input is a DER encoded timestamp token (ContentInfo)
251 instead of a timestamp response (TimeStampResp). (Optional)
252 -CApath trusted_cert_path
254 The name of the directory containing the trusted CA certificates of
255 the client. See the similar option of verify(1) for additional
256 details. Either this option or -CAfile must be specified.
257 (Optional)
258 -CAfile trusted_certs.pem
260 The name of the file containing a set of trusted self-signed CA
261 certificates in PEM format. See the similar option of verify(1) for
262 additional details. Either this option or -CApath must be
263 specified. (Optional)
264 -untrusted cert_file.pem
266 Set of additional untrusted certificates in PEM format which may be
267 needed when building the certificate chain for the TSA's signing
268 certificate. This file must contain the TSA signing certificate and
269 all intermediate CA certificates unless the response includes them.
270 (Optional)
271 verify options
273 The options -attime timestamp, -check_ss_sig, -crl_check,
274 -crl_check_all, -explicit_policy, -extended_crl, -ignore_critical,
275 -inhibit_any, -inhibit_map, -issuer_checks, -no_alt_chains,
276 -no_check_time, -partial_chain, -policy, -policy_check,
277 -policy_print, -purpose, -suiteB_128, -suiteB_128_only,
278 -suiteB_192, -trusted_first, -use_deltas, -auth_level,
279 -verify_depth, -verify_email, -verify_hostname, -verify_ip,
280 -verify_name, and -x509_strict can be used to control timestamp
281 verification. See verify(1).
282
284 The -query and -reply commands make use of a configuration file. See
285 config(5) for a general description of the syntax of the config file.
286 The -query command uses only the symbolic OID names section and it can
287 work without it. However, the -reply command needs the config file for
288 its operation.
289 When there is a command line switch equivalent of a variable the switch
291 always overrides the settings in the config file.
292 tsa section, default_tsa
294 This is the main section and it specifies the name of another
295 section that contains all the options for the -reply command. This
296 default section can be overridden with the -section command line
297 switch. (Optional)
298 oid_file
300 See ca(1) for description. (Optional)
301 oid_section
303 See ca(1) for description. (Optional)
304 RANDFILE
306 See ca(1) for description. (Optional)
307 serial
309 The name of the file containing the hexadecimal serial number of
310 the last timestamp response created. This number is incremented by
311 1 for each response. If the file does not exist at the time of
312 response generation a new file is created with serial number 1.
313 (Mandatory)
314 crypto_device
316 Specifies the OpenSSL engine that will be set as the default for
317 all available algorithms. The default value is builtin, you can
318 specify any other engines supported by OpenSSL (e.g. use chil for
319 the NCipher HSM). (Optional)
320 signer_cert
322 TSA signing certificate in PEM format. The same as the -signer
323 command line option. (Optional)
324 certs
326 A file containing a set of PEM encoded certificates that need to be
327 included in the response. The same as the -chain command line
328 option. (Optional)
329 signer_key
331 The private key of the TSA in PEM format. The same as the -inkey
332 command line option. (Optional)
333 signer_digest
335 Signing digest to use. The same as the -digest command line option.
336 (Mandatory unless specified on the command line)
337 default_policy
339 The default policy to use when the request does not mandate any
340 policy. The same as the -tspolicy command line option. (Optional)
341 other_policies
343 Comma separated list of policies that are also acceptable by the
344 TSA and used only if the request explicitly specifies one of them.
345 (Optional)
346 digests
348 The list of message digest algorithms that the TSA accepts. At
349 least one algorithm must be specified. (Mandatory)
350 accuracy
352 The accuracy of the time source of the TSA in seconds, milliseconds
353 and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any
354 of the components is missing zero is assumed for that field.
355 (Optional)
356 clock_precision_digits
358 Specifies the maximum number of digits, which represent the
359 fraction of seconds, that need to be included in the time field.
360 The trailing zeros must be removed from the time, so there might
361 actually be fewer digits, or no fraction of seconds at all.
362 Supported only on UNIX platforms. The maximum value is 6, default
363 is 0. (Optional)
364 ordering
366 If this option is yes the responses generated by this TSA can
367 always be ordered, even if the time difference between two
368 responses is less than the sum of their accuracies. Default is no.
369 (Optional)
370 tsa_name
372 Set this option to yes if the subject name of the TSA must be
373 included in the TSA name field of the response. Default is no.
374 (Optional)
375 ess_cert_id_chain
377 The SignedData objects created by the TSA always contain the
378 certificate identifier of the signing certificate in a signed
379 attribute (see RFC 2634, Enhanced Security Services). If this
380 option is set to yes and either the certs variable or the -chain
381 option is specified then the certificate identifiers of the chain
382 will also be included in the SigningCertificate signed attribute.
383 If this variable is set to no, only the signing certificate
384 identifier is included. Default is no. (Optional)
385 ess_cert_id_alg
387 This option specifies the hash function to be used to calculate the
388 TSA's public key certificate identifier. Default is sha256.
389 (Optional)
390
392 All the examples below presume that OPENSSL_CONF is set to a proper
393 configuration file, e.g. the example configuration file
394 openssl/apps/openssl.cnf will do.
395 Time Stamp Request
397 To create a timestamp request for design1.txt with SHA-256 without
398 nonce and policy and no certificate is required in the response:
399 openssl ts -query -data design1.txt -no_nonce \
401 -out design1.tsq
402 To create a similar timestamp request with specifying the message
404 imprint explicitly:
405 openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
407 -no_nonce -out design1.tsq
408 To print the content of the previous request in human readable format:
410 openssl ts -query -in design1.tsq -text
412 To create a timestamp request which includes the SHA-512 digest of
414 design2.txt, requests the signer certificate and nonce, specifies a
415 policy id (assuming the tsa_policy1 name is defined in the OID section
416 of the config file):
417 openssl ts -query -data design2.txt -sha512 \
419 -tspolicy tsa_policy1 -cert -out design2.tsq
420 Time Stamp Response
422 Before generating a response a signing certificate must be created for
423 the TSA that contains the timeStamping critical extended key usage
424 extension without any other key usage extensions. You can add this line
425 to the user certificate section of the config file to generate a proper
426 certificate;
427 extendedKeyUsage = critical,timeStamping
429 See req(1), ca(1), and x509(1) for instructions. The examples below
431 assume that cacert.pem contains the certificate of the CA, tsacert.pem
432 is the signing certificate issued by cacert.pem and tsakey.pem is the
433 private key of the TSA.
434 To create a timestamp response for a request:
436 openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
438 -signer tsacert.pem -out design1.tsr
439 If you want to use the settings in the config file you could just
441 write:
442 openssl ts -reply -queryfile design1.tsq -out design1.tsr
444 To print a timestamp reply to stdout in human readable format:
446 openssl ts -reply -in design1.tsr -text
448 To create a timestamp token instead of timestamp response:
450 openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
452 To print a timestamp token to stdout in human readable format:
454 openssl ts -reply -in design1_token.der -token_in -text -token_out
456 To extract the timestamp token from a response:
458 openssl ts -reply -in design1.tsr -out design1_token.der -token_out
460 To add 'granted' status info to a timestamp token thereby creating a
462 valid response:
463 openssl ts -reply -in design1_token.der -token_in -out design1.tsr
465 Time Stamp Verification
467 To verify a timestamp reply against a request:
468 openssl ts -verify -queryfile design1.tsq -in design1.tsr \
470 -CAfile cacert.pem -untrusted tsacert.pem
471 To verify a timestamp reply that includes the certificate chain:
473 openssl ts -verify -queryfile design2.tsq -in design2.tsr \
475 -CAfile cacert.pem
476 To verify a timestamp token against the original data file:
478 openssl ts -verify -data design2.txt -in design2.tsr \
479 -CAfile cacert.pem
480 To verify a timestamp token against a message imprint:
482 openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
483 -in design2.tsr -CAfile cacert.pem
484 You could also look at the 'test' directory for more examples.
486
488 • No support for timestamps over SMTP, though it is quite easy to
489 implement an automatic e-mail based TSA with procmail(1) and perl(1).
490 HTTP server support is provided in the form of a separate apache
491 module. HTTP client support is provided by tsget(1). Pure TCP/IP
492 protocol is not supported.
493 • The file containing the last serial number of the TSA is not locked
495 when being read or written. This is a problem if more than one
496 instance of openssl(1) is trying to create a timestamp response at
497 the same time. This is not an issue when using the apache server
498 module, it does proper locking.
499 • Look for the FIXME word in the source files.
501 • The source code should really be reviewed by somebody else, too.
503 • More testing is needed, I have done only some basic tests (see
505 test/testtsa).
506
508 tsget(1), openssl(1), req(1), x509(1), ca(1), genrsa(1), config(5)
509
511 Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
512 Licensed under the OpenSSL license (the "License"). You may not use
514 this file except in compliance with the License. You can obtain a copy
515 in the file LICENSE in the source distribution or at
516 <https://www.openssl.org/source/license.html>.
5171.1.1l 2021-09-15 TS(1)