Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / usr.bin / openssl / man / ts.1
1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65 .    \" fudge factors for nroff and troff
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 .    \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 .    \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 .    \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "TS 1"
127 .TH TS 1 "2012-01-04" "1.0.0f" "OpenSSL"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 ts \- Time Stamping Authority tool (client/server)
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 \&\fBopenssl\fR \fBts\fR
137 \&\fB\-query\fR
138 [\fB\-rand\fR file:file...]
139 [\fB\-config\fR configfile]
140 [\fB\-data\fR file_to_hash]
141 [\fB\-digest\fR digest_bytes]
142 [\fB\-md2\fR|\fB\-md4\fR|\fB\-md5\fR|\fB\-sha\fR|\fB\-sha1\fR|\fB\-mdc2\fR|\fB\-ripemd160\fR|\fB...\fR]
143 [\fB\-policy\fR object_id]
144 [\fB\-no_nonce\fR]
145 [\fB\-cert\fR]
146 [\fB\-in\fR request.tsq]
147 [\fB\-out\fR request.tsq]
148 [\fB\-text\fR]
149 .PP
150 \&\fBopenssl\fR \fBts\fR
151 \&\fB\-reply\fR
152 [\fB\-config\fR configfile]
153 [\fB\-section\fR tsa_section]
154 [\fB\-queryfile\fR request.tsq]
155 [\fB\-passin\fR password_src]
156 [\fB\-signer\fR tsa_cert.pem]
157 [\fB\-inkey\fR private.pem]
158 [\fB\-chain\fR certs_file.pem]
159 [\fB\-policy\fR object_id]
160 [\fB\-in\fR response.tsr]
161 [\fB\-token_in\fR]
162 [\fB\-out\fR response.tsr]
163 [\fB\-token_out\fR]
164 [\fB\-text\fR]
165 [\fB\-engine\fR id]
166 .PP
167 \&\fBopenssl\fR \fBts\fR
168 \&\fB\-verify\fR
169 [\fB\-data\fR file_to_hash]
170 [\fB\-digest\fR digest_bytes]
171 [\fB\-queryfile\fR request.tsq]
172 [\fB\-in\fR response.tsr]
173 [\fB\-token_in\fR]
174 [\fB\-CApath\fR trusted_cert_path]
175 [\fB\-CAfile\fR trusted_certs.pem]
176 [\fB\-untrusted\fR cert_file.pem]
177 .SH "DESCRIPTION"
178 .IX Header "DESCRIPTION"
179 The \fBts\fR command is a basic Time Stamping Authority (\s-1TSA\s0) client and server
180 application as specified in \s-1RFC\s0 3161 (Time-Stamp Protocol, \s-1TSP\s0). A
181 \&\s-1TSA\s0 can be part of a \s-1PKI\s0 deployment and its role is to provide long
182 term proof of the existence of a certain datum before a particular
183 time. Here is a brief description of the protocol:
184 .IP "1." 4
185 The \s-1TSA\s0 client computes a one-way hash value for a data file and sends
186 the hash to the \s-1TSA\s0.
187 .IP "2." 4
188 The \s-1TSA\s0 attaches the current date and time to the received hash value,
189 signs them and sends the time stamp token back to the client. By
190 creating this token the \s-1TSA\s0 certifies the existence of the original
191 data file at the time of response generation.
192 .IP "3." 4
193 The \s-1TSA\s0 client receives the time stamp token and verifies the
194 signature on it. It also checks if the token contains the same hash
195 value that it had sent to the \s-1TSA\s0.
196 .PP
197 There is one \s-1DER\s0 encoded protocol data unit defined for transporting a time
198 stamp request to the \s-1TSA\s0 and one for sending the time stamp response
199 back to the client. The \fBts\fR command has three main functions:
200 creating a time stamp request based on a data file,
201 creating a time stamp response based on a request, verifying if a
202 response corresponds to a particular request or a data file.
203 .PP
204 There is no support for sending the requests/responses automatically
205 over \s-1HTTP\s0 or \s-1TCP\s0 yet as suggested in \s-1RFC\s0 3161. The users must send the
206 requests either by ftp or e\-mail.
207 .SH "OPTIONS"
208 .IX Header "OPTIONS"
209 .SS "Time Stamp Request generation"
210 .IX Subsection "Time Stamp Request generation"
211 The \fB\-query\fR switch can be used for creating and printing a time stamp
212 request with the following options:
213 .IP "\fB\-rand\fR file:file..." 4
214 .IX Item "-rand file:file..."
215 The files containing random data for seeding the random number
216 generator. Multiple files can be specified, the separator is \fB;\fR for
217 MS-Windows, \fB,\fR for \s-1VMS\s0 and \fB:\fR for all other platforms. (Optional)
218 .IP "\fB\-config\fR configfile" 4
219 .IX Item "-config configfile"
220 The configuration file to use, this option overrides the
221 \&\fB\s-1OPENSSL_CONF\s0\fR environment variable. Only the \s-1OID\s0 section
222 of the config file is used with the \fB\-query\fR command. (Optional)
223 .IP "\fB\-data\fR file_to_hash" 4
224 .IX Item "-data file_to_hash"
225 The data file for which the time stamp request needs to be
226 created. stdin is the default if neither the \fB\-data\fR nor the \fB\-digest\fR
227 parameter is specified. (Optional)
228 .IP "\fB\-digest\fR digest_bytes" 4
229 .IX Item "-digest digest_bytes"
230 It is possible to specify the message imprint explicitly without the data
231 file. The imprint must be specified in a hexadecimal format, two characters
232 per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
233 1AF601...). The number of bytes must match the message digest algorithm 
234 in use. (Optional)
235 .IP "\fB\-md2\fR|\fB\-md4\fR|\fB\-md5\fR|\fB\-sha\fR|\fB\-sha1\fR|\fB\-mdc2\fR|\fB\-ripemd160\fR|\fB...\fR" 4
236 .IX Item "-md2|-md4|-md5|-sha|-sha1|-mdc2|-ripemd160|..."
237 The message digest to apply to the data file, it supports all the message
238 digest algorithms that are supported by the openssl \fBdgst\fR command.
239 The default is \s-1SHA\-1\s0. (Optional)
240 .IP "\fB\-policy\fR object_id" 4
241 .IX Item "-policy object_id"
242 The policy that the client expects the \s-1TSA\s0 to use for creating the
243 time stamp token. Either the dotted \s-1OID\s0 notation or \s-1OID\s0 names defined
244 in the config file can be used. If no policy is requested the \s-1TSA\s0 will
245 use its own default policy. (Optional)
246 .IP "\fB\-no_nonce\fR" 4
247 .IX Item "-no_nonce"
248 No nonce is specified in the request if this option is
249 given. Otherwise a 64 bit long pseudo-random none is
250 included in the request. It is recommended to use nonce to
251 protect against replay-attacks. (Optional)
252 .IP "\fB\-cert\fR" 4
253 .IX Item "-cert"
254 The \s-1TSA\s0 is expected to include its signing certificate in the
255 response. (Optional)
256 .IP "\fB\-in\fR request.tsq" 4
257 .IX Item "-in request.tsq"
258 This option specifies a previously created time stamp request in \s-1DER\s0
259 format that will be printed into the output file. Useful when you need
260 to examine the content of a request in human-readable
261 .Sp
262 format. (Optional)
263 .IP "\fB\-out\fR request.tsq" 4
264 .IX Item "-out request.tsq"
265 Name of the output file to which the request will be written. Default
266 is stdout. (Optional)
267 .IP "\fB\-text\fR" 4
268 .IX Item "-text"
269 If this option is specified the output is human-readable text format
270 instead of \s-1DER\s0. (Optional)
271 .SS "Time Stamp Response generation"
272 .IX Subsection "Time Stamp Response generation"
273 A time stamp response (TimeStampResp) consists of a response status
274 and the time stamp token itself (ContentInfo), if the token generation was
275 successful. The \fB\-reply\fR command is for creating a time stamp
276 response or time stamp token based on a request and printing the
277 response/token in human-readable format. If \fB\-token_out\fR is not
278 specified the output is always a time stamp response (TimeStampResp),
279 otherwise it is a time stamp token (ContentInfo).
280 .IP "\fB\-config\fR configfile" 4
281 .IX Item "-config configfile"
282 The configuration file to use, this option overrides the
283 \&\fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fB\s-1CONFIGURATION\s0 \s-1FILE\s0
284 \&\s-1OPTIONS\s0\fR for configurable variables. (Optional)
285 .IP "\fB\-section\fR tsa_section" 4
286 .IX Item "-section tsa_section"
287 The name of the config file section conatining the settings for the
288 response generation. If not specified the default \s-1TSA\s0 section is
289 used, see \fB\s-1CONFIGURATION\s0 \s-1FILE\s0 \s-1OPTIONS\s0\fR for details. (Optional)
290 .IP "\fB\-queryfile\fR request.tsq" 4
291 .IX Item "-queryfile request.tsq"
292 The name of the file containing a \s-1DER\s0 encoded time stamp request. (Optional)
293 .IP "\fB\-passin\fR password_src" 4
294 .IX Item "-passin password_src"
295 Specifies the password source for the private key of the \s-1TSA\s0. See
296 \&\fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR in \fIopenssl\fR\|(1). (Optional)
297 .IP "\fB\-signer\fR tsa_cert.pem" 4
298 .IX Item "-signer tsa_cert.pem"
299 The signer certificate of the \s-1TSA\s0 in \s-1PEM\s0 format. The \s-1TSA\s0 signing
300 certificate must have exactly one extended key usage assigned to it:
301 timeStamping. The extended key usage must also be critical, otherwise
302 the certificate is going to be refused. Overrides the \fBsigner_cert\fR
303 variable of the config file. (Optional)
304 .IP "\fB\-inkey\fR private.pem" 4
305 .IX Item "-inkey private.pem"
306 The signer private key of the \s-1TSA\s0 in \s-1PEM\s0 format. Overrides the
307 \&\fBsigner_key\fR config file option. (Optional)
308 .IP "\fB\-chain\fR certs_file.pem" 4
309 .IX Item "-chain certs_file.pem"
310 The collection of certificates in \s-1PEM\s0 format that will all
311 be included in the response in addition to the signer certificate if
312 the \fB\-cert\fR option was used for the request. This file is supposed to
313 contain the certificate chain for the signer certificate from its
314 issuer upwards. The \fB\-reply\fR command does not build a certificate
315 chain automatically. (Optional)
316 .IP "\fB\-policy\fR object_id" 4
317 .IX Item "-policy object_id"
318 The default policy to use for the response unless the client
319 explicitly requires a particular \s-1TSA\s0 policy. The \s-1OID\s0 can be specified
320 either in dotted notation or with its name. Overrides the
321 \&\fBdefault_policy\fR config file option. (Optional)
322 .IP "\fB\-in\fR response.tsr" 4
323 .IX Item "-in response.tsr"
324 Specifies a previously created time stamp response or time stamp token
325 (if \fB\-token_in\fR is also specified) in \s-1DER\s0 format that will be written
326 to the output file. This option does not require a request, it is
327 useful e.g. when you need to examine the content of a response or
328 token or you want to extract the time stamp token from a response. If
329 the input is a token and the output is a time stamp response a default
330 \&'granted' status info is added to the token. (Optional)
331 .IP "\fB\-token_in\fR" 4
332 .IX Item "-token_in"
333 This flag can be used together with the \fB\-in\fR option and indicates
334 that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead
335 of a time stamp response (TimeStampResp). (Optional)
336 .IP "\fB\-out\fR response.tsr" 4
337 .IX Item "-out response.tsr"
338 The response is written to this file. The format and content of the
339 file depends on other options (see \fB\-text\fR, \fB\-token_out\fR). The default is
340 stdout. (Optional)
341 .IP "\fB\-token_out\fR" 4
342 .IX Item "-token_out"
343 The output is a time stamp token (ContentInfo) instead of time stamp
344 response (TimeStampResp). (Optional)
345 .IP "\fB\-text\fR" 4
346 .IX Item "-text"
347 If this option is specified the output is human-readable text format
348 instead of \s-1DER\s0. (Optional)
349 .IP "\fB\-engine\fR id" 4
350 .IX Item "-engine id"
351 Specifying an engine (by its unique \fBid\fR string) will cause \fBts\fR
352 to attempt to obtain a functional reference to the specified engine,
353 thus initialising it if needed. The engine will then be set as the default
354 for all available algorithms. Default is builtin. (Optional)
355 .SS "Time Stamp Response verification"
356 .IX Subsection "Time Stamp Response verification"
357 The \fB\-verify\fR command is for verifying if a time stamp response or time
358 stamp token is valid and matches a particular time stamp request or
359 data file. The \fB\-verify\fR command does not use the configuration file.
360 .IP "\fB\-data\fR file_to_hash" 4
361 .IX Item "-data file_to_hash"
362 The response or token must be verified against file_to_hash. The file
363 is hashed with the message digest algorithm specified in the token. 
364 The \fB\-digest\fR and \fB\-queryfile\fR options must not be specified with this one.
365 (Optional)
366 .IP "\fB\-digest\fR digest_bytes" 4
367 .IX Item "-digest digest_bytes"
368 The response or token must be verified against the message digest specified
369 with this option. The number of bytes must match the message digest algorithm
370 specified in the token. The \fB\-data\fR and \fB\-queryfile\fR options must not be
371 specified with this one. (Optional)
372 .IP "\fB\-queryfile\fR request.tsq" 4
373 .IX Item "-queryfile request.tsq"
374 The original time stamp request in \s-1DER\s0 format. The \fB\-data\fR and \fB\-digest\fR
375 options must not be specified with this one. (Optional)
376 .IP "\fB\-in\fR response.tsr" 4
377 .IX Item "-in response.tsr"
378 The time stamp response that needs to be verified in \s-1DER\s0 format. (Mandatory)
379 .IP "\fB\-token_in\fR" 4
380 .IX Item "-token_in"
381 This flag can be used together with the \fB\-in\fR option and indicates
382 that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead
383 of a time stamp response (TimeStampResp). (Optional)
384 .IP "\fB\-CApath\fR trusted_cert_path" 4
385 .IX Item "-CApath trusted_cert_path"
386 The name of the directory containing the trused \s-1CA\s0 certificates of the
387 client. See the similar option of \fIverify\fR\|(1) for additional
388 details. Either this option or \fB\-CAfile\fR must be specified. (Optional)
389 .IP "\fB\-CAfile\fR trusted_certs.pem" 4
390 .IX Item "-CAfile trusted_certs.pem"
391 The name of the file containing a set of trusted self-signed \s-1CA\s0 
392 certificates in \s-1PEM\s0 format. See the similar option of 
393 \&\fIverify\fR\|(1) for additional details. Either this option 
394 or \fB\-CApath\fR must be specified.
395 (Optional)
396 .IP "\fB\-untrusted\fR cert_file.pem" 4
397 .IX Item "-untrusted cert_file.pem"
398 Set of additional untrusted certificates in \s-1PEM\s0 format which may be
399 needed when building the certificate chain for the \s-1TSA\s0's signing
400 certificate. This file must contain the \s-1TSA\s0 signing certificate and
401 all intermediate \s-1CA\s0 certificates unless the response includes them.
402 (Optional)
403 .SH "CONFIGURATION FILE OPTIONS"
404 .IX Header "CONFIGURATION FILE OPTIONS"
405 The \fB\-query\fR and \fB\-reply\fR commands make use of a configuration file
406 defined by the \fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fIconfig\fR\|(5)
407 for a general description of the syntax of the config file. The
408 \&\fB\-query\fR command uses only the symbolic \s-1OID\s0 names section
409 and it can work without it. However, the \fB\-reply\fR command needs the
410 config file for its operation.
411 .PP
412 When there is a command line switch equivalent of a variable the
413 switch always overrides the settings in the config file.
414 .IP "\fBtsa\fR section, \fBdefault_tsa\fR" 4
415 .IX Item "tsa section, default_tsa"
416 This is the main section and it specifies the name of another section
417 that contains all the options for the \fB\-reply\fR command. This default
418 section can be overriden with the \fB\-section\fR command line switch. (Optional)
419 .IP "\fBoid_file\fR" 4
420 .IX Item "oid_file"
421 See \fIca\fR\|(1) for description. (Optional)
422 .IP "\fBoid_section\fR" 4
423 .IX Item "oid_section"
424 See \fIca\fR\|(1) for description. (Optional)
425 .IP "\fB\s-1RANDFILE\s0\fR" 4
426 .IX Item "RANDFILE"
427 See \fIca\fR\|(1) for description. (Optional)
428 .IP "\fBserial\fR" 4
429 .IX Item "serial"
430 The name of the file containing the hexadecimal serial number of the
431 last time stamp response created. This number is incremented by 1 for
432 each response. If the file does not exist at the time of response
433 generation a new file is created with serial number 1. (Mandatory)
434 .IP "\fBcrypto_device\fR" 4
435 .IX Item "crypto_device"
436 Specifies the OpenSSL engine that will be set as the default for 
437 all available algorithms. The default value is builtin, you can specify 
438 any other engines supported by OpenSSL (e.g. use chil for the NCipher \s-1HSM\s0).
439 (Optional)
440 .IP "\fBsigner_cert\fR" 4
441 .IX Item "signer_cert"
442 \&\s-1TSA\s0 signing certificate in \s-1PEM\s0 format. The same as the \fB\-signer\fR
443 command line option. (Optional)
444 .IP "\fBcerts\fR" 4
445 .IX Item "certs"
446 A file containing a set of \s-1PEM\s0 encoded certificates that need to be
447 included in the response. The same as the \fB\-chain\fR command line
448 option. (Optional)
449 .IP "\fBsigner_key\fR" 4
450 .IX Item "signer_key"
451 The private key of the \s-1TSA\s0 in \s-1PEM\s0 format. The same as the \fB\-inkey\fR
452 command line option. (Optional)
453 .IP "\fBdefault_policy\fR" 4
454 .IX Item "default_policy"
455 The default policy to use when the request does not mandate any
456 policy. The same as the \fB\-policy\fR command line option. (Optional)
457 .IP "\fBother_policies\fR" 4
458 .IX Item "other_policies"
459 Comma separated list of policies that are also acceptable by the \s-1TSA\s0
460 and used only if the request explicitly specifies one of them. (Optional)
461 .IP "\fBdigests\fR" 4
462 .IX Item "digests"
463 The list of message digest algorithms that the \s-1TSA\s0 accepts. At least
464 one algorithm must be specified. (Mandatory)
465 .IP "\fBaccuracy\fR" 4
466 .IX Item "accuracy"
467 The accuracy of the time source of the \s-1TSA\s0 in seconds, milliseconds
468 and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
469 the components is missing zero is assumed for that field. (Optional)
470 .IP "\fBclock_precision_digits\fR" 4
471 .IX Item "clock_precision_digits"
472 Specifies the maximum number of digits, which represent the fraction of 
473 seconds, that  need to be included in the time field. The trailing zeroes
474 must be removed from the time, so there might actually be fewer digits,
475 or no fraction of seconds at all. Supported only on \s-1UNIX\s0 platforms.
476 The maximum value is 6, default is 0.
477 (Optional)
478 .IP "\fBordering\fR" 4
479 .IX Item "ordering"
480 If this option is yes the responses generated by this \s-1TSA\s0 can always
481 be ordered, even if the time difference between two responses is less
482 than the sum of their accuracies. Default is no. (Optional)
483 .IP "\fBtsa_name\fR" 4
484 .IX Item "tsa_name"
485 Set this option to yes if the subject name of the \s-1TSA\s0 must be included in
486 the \s-1TSA\s0 name field of the response. Default is no. (Optional)
487 .IP "\fBess_cert_id_chain\fR" 4
488 .IX Item "ess_cert_id_chain"
489 The SignedData objects created by the \s-1TSA\s0 always contain the
490 certificate identifier of the signing certificate in a signed
491 attribute (see \s-1RFC\s0 2634, Enhanced Security Services). If this option
492 is set to yes and either the \fBcerts\fR variable or the \fB\-chain\fR option
493 is specified then the certificate identifiers of the chain will also
494 be included in the SigningCertificate signed attribute. If this
495 variable is set to no, only the signing certificate identifier is
496 included. Default is no. (Optional)
497 .SH "ENVIRONMENT VARIABLES"
498 .IX Header "ENVIRONMENT VARIABLES"
499 \&\fB\s-1OPENSSL_CONF\s0\fR contains the path of the configuration file and can be
500 overriden by the \fB\-config\fR command line option.
501 .SH "EXAMPLES"
502 .IX Header "EXAMPLES"
503 All the examples below presume that \fB\s-1OPENSSL_CONF\s0\fR is set to a proper
504 configuration file, e.g. the example configuration file 
505 openssl/apps/openssl.cnf will do.
506 .SS "Time Stamp Request"
507 .IX Subsection "Time Stamp Request"
508 To create a time stamp request for design1.txt with \s-1SHA\-1\s0 
509 without nonce and policy and no certificate is required in the response:
510 .PP
511 .Vb 2
512 \&  openssl ts \-query \-data design1.txt \-no_nonce \e
513 \&        \-out design1.tsq
514 .Ve
515 .PP
516 To create a similar time stamp request with specifying the message imprint
517 explicitly:
518 .PP
519 .Vb 2
520 \&  openssl ts \-query \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
521 \&         \-no_nonce \-out design1.tsq
522 .Ve
523 .PP
524 To print the content of the previous request in human readable format:
525 .PP
526 .Vb 1
527 \&  openssl ts \-query \-in design1.tsq \-text
528 .Ve
529 .PP
530 To create a time stamp request which includes the \s-1MD\-5\s0 digest 
531 of design2.txt, requests the signer certificate and nonce,
532 specifies a policy id (assuming the tsa_policy1 name is defined in the
533 \&\s-1OID\s0 section of the config file):
534 .PP
535 .Vb 2
536 \&  openssl ts \-query \-data design2.txt \-md5 \e
537 \&        \-policy tsa_policy1 \-cert \-out design2.tsq
538 .Ve
539 .SS "Time Stamp Response"
540 .IX Subsection "Time Stamp Response"
541 Before generating a response a signing certificate must be created for
542 the \s-1TSA\s0 that contains the \fBtimeStamping\fR critical extended key usage extension
543 without any other key usage extensions. You can add the
544 \&'extendedKeyUsage = critical,timeStamping' line to the user certificate section
545 of the config file to generate a proper certificate. See \fIreq\fR\|(1),
546 \&\fIca\fR\|(1), \fIx509\fR\|(1) for instructions. The examples
547 below assume that cacert.pem contains the certificate of the \s-1CA\s0,
548 tsacert.pem is the signing certificate issued by cacert.pem and
549 tsakey.pem is the private key of the \s-1TSA\s0.
550 .PP
551 To create a time stamp response for a request:
552 .PP
553 .Vb 2
554 \&  openssl ts \-reply \-queryfile design1.tsq \-inkey tsakey.pem \e
555 \&        \-signer tsacert.pem \-out design1.tsr
556 .Ve
557 .PP
558 If you want to use the settings in the config file you could just write:
559 .PP
560 .Vb 1
561 \&  openssl ts \-reply \-queryfile design1.tsq \-out design1.tsr
562 .Ve
563 .PP
564 To print a time stamp reply to stdout in human readable format:
565 .PP
566 .Vb 1
567 \&  openssl ts \-reply \-in design1.tsr \-text
568 .Ve
569 .PP
570 To create a time stamp token instead of time stamp response:
571 .PP
572 .Vb 1
573 \&  openssl ts \-reply \-queryfile design1.tsq \-out design1_token.der \-token_out
574 .Ve
575 .PP
576 To print a time stamp token to stdout in human readable format:
577 .PP
578 .Vb 1
579 \&  openssl ts \-reply \-in design1_token.der \-token_in \-text \-token_out
580 .Ve
581 .PP
582 To extract the time stamp token from a response:
583 .PP
584 .Vb 1
585 \&  openssl ts \-reply \-in design1.tsr \-out design1_token.der \-token_out
586 .Ve
587 .PP
588 To add 'granted' status info to a time stamp token thereby creating a
589 valid response:
590 .PP
591 .Vb 1
592 \&  openssl ts \-reply \-in design1_token.der \-token_in \-out design1.tsr
593 .Ve
594 .SS "Time Stamp Verification"
595 .IX Subsection "Time Stamp Verification"
596 To verify a time stamp reply against a request:
597 .PP
598 .Vb 2
599 \&  openssl ts \-verify \-queryfile design1.tsq \-in design1.tsr \e
600 \&        \-CAfile cacert.pem \-untrusted tsacert.pem
601 .Ve
602 .PP
603 To verify a time stamp reply that includes the certificate chain:
604 .PP
605 .Vb 2
606 \&  openssl ts \-verify \-queryfile design2.tsq \-in design2.tsr \e
607 \&        \-CAfile cacert.pem
608 .Ve
609 .PP
610 To verify a time stamp token against the original data file:
611   openssl ts \-verify \-data design2.txt \-in design2.tsr \e
612         \-CAfile cacert.pem
613 .PP
614 To verify a time stamp token against a message imprint:
615   openssl ts \-verify \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
616          \-in design2.tsr \-CAfile cacert.pem
617 .PP
618 You could also look at the 'test' directory for more examples.
619 .SH "BUGS"
620 .IX Header "BUGS"
621 If you find any bugs or you have suggestions please write to
622 Zoltan Glozik <zglozik@opentsa.org>. Known issues:
623 .IP "\(bu" 4
624 No support for time stamps over \s-1SMTP\s0, though it is quite easy
625 to implement an automatic e\-mail based \s-1TSA\s0 with \fIprocmail\fR\|(1) 
626 and \fIperl\fR\|(1). \s-1HTTP\s0 server support is provided in the form of 
627 a separate apache module. \s-1HTTP\s0 client support is provided by
628 \&\fItsget\fR\|(1). Pure \s-1TCP/IP\s0 protocol is not supported.
629 .IP "\(bu" 4
630 The file containing the last serial number of the \s-1TSA\s0 is not
631 locked when being read or written. This is a problem if more than one
632 instance of \fIopenssl\fR\|(1) is trying to create a time stamp
633 response at the same time. This is not an issue when using the apache
634 server module, it does proper locking.
635 .IP "\(bu" 4
636 Look for the \s-1FIXME\s0 word in the source files.
637 .IP "\(bu" 4
638 The source code should really be reviewed by somebody else, too.
639 .IP "\(bu" 4
640 More testing is needed, I have done only some basic tests (see
641 test/testtsa).
642 .SH "AUTHOR"
643 .IX Header "AUTHOR"
644 Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
645 .SH "SEE ALSO"
646 .IX Header "SEE ALSO"
647 \&\fItsget\fR\|(1), \fIopenssl\fR\|(1), \fIreq\fR\|(1), 
648 \&\fIx509\fR\|(1), \fIca\fR\|(1), \fIgenrsa\fR\|(1), 
649 \&\fIconfig\fR\|(5)