1TS(1)                               OpenSSL                              TS(1)
2
3
4

NAME

6       openssl-ts, ts - Time Stamping Authority tool (client/server)
7

SYNOPSIS

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
14       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
20       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
25       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

DESCRIPTION

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
41       1.  The TSA client computes a one-way hash value for a data file and
42           sends the hash to the TSA.
43
44       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
49       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
53       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
60       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

OPTIONS

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
69       -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
75       [-writerand file]
76           Writes random data to the specified file upon exit.  This can be
77           used with a subsequent -rand flag.
78
79       -config configfile
80           The configuration file to use.  Optional; for a description of the
81           default value, see "COMMAND SUMMARY" in openssl(1).
82
83       -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
88       -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
95       -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
100       -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
106       -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
112       -cert
113           The TSA is expected to include its signing certificate in the
114           response. (Optional)
115
116       -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
122       -out request.tsq
123           Name of the output file to which the request will be written.
124           Default is stdout. (Optional)
125
126       -text
127           If this option is specified the output is human-readable text
128           format instead of DER. (Optional)
129
130   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
139       -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
144       -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
149       -queryfile request.tsq
150           The name of the file containing a DER encoded timestamp request.
151           (Optional)
152
153       -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
157       -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
164       -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
170       -digest
171           Signing digest to use. Overrides the signer_digest config file
172           option. (Mandatory unless specified in the config file)
173
174       -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
182       -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
188       -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
198       -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
203       -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
208       -token_out
209           The output is a timestamp token (ContentInfo) instead of timestamp
210           response (TimeStampResp). (Optional)
211
212       -text
213           If this option is specified the output is human-readable text
214           format instead of DER. (Optional)
215
216       -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
223   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
228       -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
234       -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
240       -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
244       -in response.tsr
245           The timestamp response that needs to be verified in DER format.
246           (Mandatory)
247
248       -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
253       -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
259       -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
265       -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
272       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

CONFIGURATION FILE OPTIONS

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
290       When there is a command line switch equivalent of a variable the switch
291       always overrides the settings in the config file.
292
293       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
299       oid_file
300           See ca(1) for description. (Optional)
301
302       oid_section
303           See ca(1) for description. (Optional)
304
305       RANDFILE
306           See ca(1) for description. (Optional)
307
308       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
315       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
321       signer_cert
322           TSA signing certificate in PEM format. The same as the -signer
323           command line option. (Optional)
324
325       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
330       signer_key
331           The private key of the TSA in PEM format. The same as the -inkey
332           command line option. (Optional)
333
334       signer_digest
335           Signing digest to use. The same as the -digest command line option.
336           (Mandatory unless specified on the command line)
337
338       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
342       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
347       digests
348           The list of message digest algorithms that the TSA accepts. At
349           least one algorithm must be specified. (Mandatory)
350
351       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
357       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
365       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
371       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
376       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
386       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

EXAMPLES

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
396   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
400         openssl ts -query -data design1.txt -no_nonce \
401               -out design1.tsq
402
403       To create a similar timestamp request with specifying the message
404       imprint explicitly:
405
406         openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
407                -no_nonce -out design1.tsq
408
409       To print the content of the previous request in human readable format:
410
411         openssl ts -query -in design1.tsq -text
412
413       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
418         openssl ts -query -data design2.txt -sha512 \
419               -tspolicy tsa_policy1 -cert -out design2.tsq
420
421   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
428          extendedKeyUsage = critical,timeStamping
429
430       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
435       To create a timestamp response for a request:
436
437         openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
438               -signer tsacert.pem -out design1.tsr
439
440       If you want to use the settings in the config file you could just
441       write:
442
443         openssl ts -reply -queryfile design1.tsq -out design1.tsr
444
445       To print a timestamp reply to stdout in human readable format:
446
447         openssl ts -reply -in design1.tsr -text
448
449       To create a timestamp token instead of timestamp response:
450
451         openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
452
453       To print a timestamp token to stdout in human readable format:
454
455         openssl ts -reply -in design1_token.der -token_in -text -token_out
456
457       To extract the timestamp token from a response:
458
459         openssl ts -reply -in design1.tsr -out design1_token.der -token_out
460
461       To add 'granted' status info to a timestamp token thereby creating a
462       valid response:
463
464         openssl ts -reply -in design1_token.der -token_in -out design1.tsr
465
466   Time Stamp Verification
467       To verify a timestamp reply against a request:
468
469         openssl ts -verify -queryfile design1.tsq -in design1.tsr \
470               -CAfile cacert.pem -untrusted tsacert.pem
471
472       To verify a timestamp reply that includes the certificate chain:
473
474         openssl ts -verify -queryfile design2.tsq -in design2.tsr \
475               -CAfile cacert.pem
476
477       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
481       To verify a timestamp token against a message imprint:
482         openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
483                -in design2.tsr -CAfile cacert.pem
484
485       You could also look at the 'test' directory for more examples.
486

BUGS

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
494       • 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
500       • Look for the FIXME word in the source files.
501
502       • The source code should really be reviewed by somebody else, too.
503
504       • More testing is needed, I have done only some basic tests (see
505         test/testtsa).
506

SEE ALSO

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
513       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>.
517
518
519
5201.1.1l                            2021-09-15                             TS(1)
Impressum