Debian Codegraph @

upstream/debian-unstable/man1/openssl-ts.1ssl

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