Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / usr.bin / openssl / man / ts.1
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
01185282
PA
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"
e3261593 127.TH TS 1 "2012-01-04" "1.0.0f" "OpenSSL"
01185282
PA
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"
133ts \- 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"
179The \fBts\fR command is a basic Time Stamping Authority (\s-1TSA\s0) client and server
180application 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
182term proof of the existence of a certain datum before a particular
183time. Here is a brief description of the protocol:
184.IP "1." 4
185The \s-1TSA\s0 client computes a one-way hash value for a data file and sends
186the hash to the \s-1TSA\s0.
187.IP "2." 4
188The \s-1TSA\s0 attaches the current date and time to the received hash value,
189signs them and sends the time stamp token back to the client. By
190creating this token the \s-1TSA\s0 certifies the existence of the original
191data file at the time of response generation.
192.IP "3." 4
193The \s-1TSA\s0 client receives the time stamp token and verifies the
194signature on it. It also checks if the token contains the same hash
195value that it had sent to the \s-1TSA\s0.
196.PP
197There is one \s-1DER\s0 encoded protocol data unit defined for transporting a time
198stamp request to the \s-1TSA\s0 and one for sending the time stamp response
199back to the client. The \fBts\fR command has three main functions:
200creating a time stamp request based on a data file,
201creating a time stamp response based on a request, verifying if a
202response corresponds to a particular request or a data file.
203.PP
204There is no support for sending the requests/responses automatically
205over \s-1HTTP\s0 or \s-1TCP\s0 yet as suggested in \s-1RFC\s0 3161. The users must send the
206requests 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"
211The \fB\-query\fR switch can be used for creating and printing a time stamp
212request with the following options:
213.IP "\fB\-rand\fR file:file..." 4
214.IX Item "-rand file:file..."
215The files containing random data for seeding the random number
216generator. Multiple files can be specified, the separator is \fB;\fR for
217MS-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"
220The configuration file to use, this option overrides the
221\&\fB\s-1OPENSSL_CONF\s0\fR environment variable. Only the \s-1OID\s0 section
222of 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"
225The data file for which the time stamp request needs to be
226created. stdin is the default if neither the \fB\-data\fR nor the \fB\-digest\fR
227parameter is specified. (Optional)
228.IP "\fB\-digest\fR digest_bytes" 4
229.IX Item "-digest digest_bytes"
230It is possible to specify the message imprint explicitly without the data
231file. The imprint must be specified in a hexadecimal format, two characters
232per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
2331AF601...). The number of bytes must match the message digest algorithm
234in 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|..."
237The message digest to apply to the data file, it supports all the message
238digest algorithms that are supported by the openssl \fBdgst\fR command.
239The default is \s-1SHA\-1\s0. (Optional)
240.IP "\fB\-policy\fR object_id" 4
241.IX Item "-policy object_id"
242The policy that the client expects the \s-1TSA\s0 to use for creating the
243time stamp token. Either the dotted \s-1OID\s0 notation or \s-1OID\s0 names defined
244in the config file can be used. If no policy is requested the \s-1TSA\s0 will
245use its own default policy. (Optional)
246.IP "\fB\-no_nonce\fR" 4
247.IX Item "-no_nonce"
248No nonce is specified in the request if this option is
249given. Otherwise a 64 bit long pseudo-random none is
250included in the request. It is recommended to use nonce to
251protect against replay-attacks. (Optional)
252.IP "\fB\-cert\fR" 4
253.IX Item "-cert"
254The \s-1TSA\s0 is expected to include its signing certificate in the
255response. (Optional)
256.IP "\fB\-in\fR request.tsq" 4
257.IX Item "-in request.tsq"
258This option specifies a previously created time stamp request in \s-1DER\s0
259format that will be printed into the output file. Useful when you need
260to examine the content of a request in human-readable
261.Sp
262format. (Optional)
263.IP "\fB\-out\fR request.tsq" 4
264.IX Item "-out request.tsq"
265Name of the output file to which the request will be written. Default
266is stdout. (Optional)
267.IP "\fB\-text\fR" 4
268.IX Item "-text"
269If this option is specified the output is human-readable text format
270instead of \s-1DER\s0. (Optional)
271.SS "Time Stamp Response generation"
272.IX Subsection "Time Stamp Response generation"
273A time stamp response (TimeStampResp) consists of a response status
274and the time stamp token itself (ContentInfo), if the token generation was
275successful. The \fB\-reply\fR command is for creating a time stamp
276response or time stamp token based on a request and printing the
277response/token in human-readable format. If \fB\-token_out\fR is not
278specified the output is always a time stamp response (TimeStampResp),
279otherwise it is a time stamp token (ContentInfo).
280.IP "\fB\-config\fR configfile" 4
281.IX Item "-config configfile"
282The 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"
287The name of the config file section conatining the settings for the
288response generation. If not specified the default \s-1TSA\s0 section is
289used, 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"
292The 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"
295Specifies 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"
299The signer certificate of the \s-1TSA\s0 in \s-1PEM\s0 format. The \s-1TSA\s0 signing
300certificate must have exactly one extended key usage assigned to it:
301timeStamping. The extended key usage must also be critical, otherwise
302the certificate is going to be refused. Overrides the \fBsigner_cert\fR
303variable of the config file. (Optional)
304.IP "\fB\-inkey\fR private.pem" 4
305.IX Item "-inkey private.pem"
306The 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"
310The collection of certificates in \s-1PEM\s0 format that will all
311be included in the response in addition to the signer certificate if
312the \fB\-cert\fR option was used for the request. This file is supposed to
313contain the certificate chain for the signer certificate from its
314issuer upwards. The \fB\-reply\fR command does not build a certificate
315chain automatically. (Optional)
316.IP "\fB\-policy\fR object_id" 4
317.IX Item "-policy object_id"
318The default policy to use for the response unless the client
319explicitly requires a particular \s-1TSA\s0 policy. The \s-1OID\s0 can be specified
320either 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"
324Specifies 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
326to the output file. This option does not require a request, it is
327useful e.g. when you need to examine the content of a response or
328token or you want to extract the time stamp token from a response. If
329the 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"
333This flag can be used together with the \fB\-in\fR option and indicates
334that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead
335of a time stamp response (TimeStampResp). (Optional)
336.IP "\fB\-out\fR response.tsr" 4
337.IX Item "-out response.tsr"
338The response is written to this file. The format and content of the
339file depends on other options (see \fB\-text\fR, \fB\-token_out\fR). The default is
340stdout. (Optional)
341.IP "\fB\-token_out\fR" 4
342.IX Item "-token_out"
343The output is a time stamp token (ContentInfo) instead of time stamp
344response (TimeStampResp). (Optional)
345.IP "\fB\-text\fR" 4
346.IX Item "-text"
347If this option is specified the output is human-readable text format
348instead of \s-1DER\s0. (Optional)
349.IP "\fB\-engine\fR id" 4
350.IX Item "-engine id"
351Specifying an engine (by its unique \fBid\fR string) will cause \fBts\fR
352to attempt to obtain a functional reference to the specified engine,
353thus initialising it if needed. The engine will then be set as the default
354for all available algorithms. Default is builtin. (Optional)
355.SS "Time Stamp Response verification"
356.IX Subsection "Time Stamp Response verification"
357The \fB\-verify\fR command is for verifying if a time stamp response or time
358stamp token is valid and matches a particular time stamp request or
359data 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"
362The response or token must be verified against file_to_hash. The file
363is hashed with the message digest algorithm specified in the token.
364The \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"
368The response or token must be verified against the message digest specified
369with this option. The number of bytes must match the message digest algorithm
370specified in the token. The \fB\-data\fR and \fB\-queryfile\fR options must not be
371specified with this one. (Optional)
372.IP "\fB\-queryfile\fR request.tsq" 4
373.IX Item "-queryfile request.tsq"
374The original time stamp request in \s-1DER\s0 format. The \fB\-data\fR and \fB\-digest\fR
375options must not be specified with this one. (Optional)
376.IP "\fB\-in\fR response.tsr" 4
377.IX Item "-in response.tsr"
378The 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"
381This flag can be used together with the \fB\-in\fR option and indicates
382that the input is a \s-1DER\s0 encoded time stamp token (ContentInfo) instead
383of a time stamp response (TimeStampResp). (Optional)
384.IP "\fB\-CApath\fR trusted_cert_path" 4
385.IX Item "-CApath trusted_cert_path"
386The name of the directory containing the trused \s-1CA\s0 certificates of the
387client. See the similar option of \fIverify\fR\|(1) for additional
388details. 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"
391The name of the file containing a set of trusted self-signed \s-1CA\s0
392certificates in \s-1PEM\s0 format. See the similar option of
393\&\fIverify\fR\|(1) for additional details. Either this option
394or \fB\-CApath\fR must be specified.
395(Optional)
396.IP "\fB\-untrusted\fR cert_file.pem" 4
397.IX Item "-untrusted cert_file.pem"
398Set of additional untrusted certificates in \s-1PEM\s0 format which may be
399needed when building the certificate chain for the \s-1TSA\s0's signing
400certificate. This file must contain the \s-1TSA\s0 signing certificate and
401all intermediate \s-1CA\s0 certificates unless the response includes them.
402(Optional)
403.SH "CONFIGURATION FILE OPTIONS"
404.IX Header "CONFIGURATION FILE OPTIONS"
405The \fB\-query\fR and \fB\-reply\fR commands make use of a configuration file
406defined by the \fB\s-1OPENSSL_CONF\s0\fR environment variable. See \fIconfig\fR\|(5)
407for 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
409and it can work without it. However, the \fB\-reply\fR command needs the
410config file for its operation.
411.PP
412When there is a command line switch equivalent of a variable the
413switch always overrides the settings in the config file.
414.IP "\fBtsa\fR section, \fBdefault_tsa\fR" 4
415.IX Item "tsa section, default_tsa"
416This is the main section and it specifies the name of another section
417that contains all the options for the \fB\-reply\fR command. This default
418section can be overriden with the \fB\-section\fR command line switch. (Optional)
419.IP "\fBoid_file\fR" 4
420.IX Item "oid_file"
421See \fIca\fR\|(1) for description. (Optional)
422.IP "\fBoid_section\fR" 4
423.IX Item "oid_section"
424See \fIca\fR\|(1) for description. (Optional)
425.IP "\fB\s-1RANDFILE\s0\fR" 4
426.IX Item "RANDFILE"
427See \fIca\fR\|(1) for description. (Optional)
428.IP "\fBserial\fR" 4
429.IX Item "serial"
430The name of the file containing the hexadecimal serial number of the
431last time stamp response created. This number is incremented by 1 for
432each response. If the file does not exist at the time of response
433generation a new file is created with serial number 1. (Mandatory)
434.IP "\fBcrypto_device\fR" 4
435.IX Item "crypto_device"
436Specifies the OpenSSL engine that will be set as the default for
437all available algorithms. The default value is builtin, you can specify
438any 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
443command line option. (Optional)
444.IP "\fBcerts\fR" 4
445.IX Item "certs"
446A file containing a set of \s-1PEM\s0 encoded certificates that need to be
447included in the response. The same as the \fB\-chain\fR command line
448option. (Optional)
449.IP "\fBsigner_key\fR" 4
450.IX Item "signer_key"
451The private key of the \s-1TSA\s0 in \s-1PEM\s0 format. The same as the \fB\-inkey\fR
452command line option. (Optional)
453.IP "\fBdefault_policy\fR" 4
454.IX Item "default_policy"
455The default policy to use when the request does not mandate any
456policy. The same as the \fB\-policy\fR command line option. (Optional)
457.IP "\fBother_policies\fR" 4
458.IX Item "other_policies"
459Comma separated list of policies that are also acceptable by the \s-1TSA\s0
460and used only if the request explicitly specifies one of them. (Optional)
461.IP "\fBdigests\fR" 4
462.IX Item "digests"
463The list of message digest algorithms that the \s-1TSA\s0 accepts. At least
464one algorithm must be specified. (Mandatory)
465.IP "\fBaccuracy\fR" 4
466.IX Item "accuracy"
467The accuracy of the time source of the \s-1TSA\s0 in seconds, milliseconds
468and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
469the components is missing zero is assumed for that field. (Optional)
470.IP "\fBclock_precision_digits\fR" 4
471.IX Item "clock_precision_digits"
472Specifies the maximum number of digits, which represent the fraction of
473seconds, that need to be included in the time field. The trailing zeroes
474must be removed from the time, so there might actually be fewer digits,
475or no fraction of seconds at all. Supported only on \s-1UNIX\s0 platforms.
476The maximum value is 6, default is 0.
477(Optional)
478.IP "\fBordering\fR" 4
479.IX Item "ordering"
480If this option is yes the responses generated by this \s-1TSA\s0 can always
481be ordered, even if the time difference between two responses is less
482than the sum of their accuracies. Default is no. (Optional)
483.IP "\fBtsa_name\fR" 4
484.IX Item "tsa_name"
485Set this option to yes if the subject name of the \s-1TSA\s0 must be included in
486the \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"
489The SignedData objects created by the \s-1TSA\s0 always contain the
490certificate identifier of the signing certificate in a signed
491attribute (see \s-1RFC\s0 2634, Enhanced Security Services). If this option
492is set to yes and either the \fBcerts\fR variable or the \fB\-chain\fR option
493is specified then the certificate identifiers of the chain will also
494be included in the SigningCertificate signed attribute. If this
495variable is set to no, only the signing certificate identifier is
496included. 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
500overriden by the \fB\-config\fR command line option.
501.SH "EXAMPLES"
502.IX Header "EXAMPLES"
503All the examples below presume that \fB\s-1OPENSSL_CONF\s0\fR is set to a proper
504configuration file, e.g. the example configuration file
505openssl/apps/openssl.cnf will do.
506.SS "Time Stamp Request"
507.IX Subsection "Time Stamp Request"
508To create a time stamp request for design1.txt with \s-1SHA\-1\s0
509without 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
516To create a similar time stamp request with specifying the message imprint
517explicitly:
518.PP
519.Vb 2
520\& openssl ts \-query \-digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
521\& \-no_nonce \-out design1.tsq
522.Ve
523.PP
524To 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
530To create a time stamp request which includes the \s-1MD\-5\s0 digest
531of design2.txt, requests the signer certificate and nonce,
532specifies 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"
541Before generating a response a signing certificate must be created for
542the \s-1TSA\s0 that contains the \fBtimeStamping\fR critical extended key usage extension
543without any other key usage extensions. You can add the
544\&'extendedKeyUsage = critical,timeStamping' line to the user certificate section
545of the config file to generate a proper certificate. See \fIreq\fR\|(1),
546\&\fIca\fR\|(1), \fIx509\fR\|(1) for instructions. The examples
547below assume that cacert.pem contains the certificate of the \s-1CA\s0,
548tsacert.pem is the signing certificate issued by cacert.pem and
549tsakey.pem is the private key of the \s-1TSA\s0.
550.PP
551To 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
558If 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
564To 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
570To 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
576To 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
582To 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
588To add 'granted' status info to a time stamp token thereby creating a
589valid 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"
596To 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
603To 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
610To 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
614To 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
618You could also look at the 'test' directory for more examples.
619.SH "BUGS"
620.IX Header "BUGS"
621If you find any bugs or you have suggestions please write to
622Zoltan Glozik <zglozik@opentsa.org>. Known issues:
623.IP "\(bu" 4
624No support for time stamps over \s-1SMTP\s0, though it is quite easy
625to implement an automatic e\-mail based \s-1TSA\s0 with \fIprocmail\fR\|(1)
626and \fIperl\fR\|(1). \s-1HTTP\s0 server support is provided in the form of
627a 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
630The file containing the last serial number of the \s-1TSA\s0 is not
631locked when being read or written. This is a problem if more than one
632instance of \fIopenssl\fR\|(1) is trying to create a time stamp
633response at the same time. This is not an issue when using the apache
634server module, it does proper locking.
635.IP "\(bu" 4
636Look for the \s-1FIXME\s0 word in the source files.
637.IP "\(bu" 4
638The source code should really be reviewed by somebody else, too.
639.IP "\(bu" 4
640More testing is needed, I have done only some basic tests (see
641test/testtsa).
642.SH "AUTHOR"
643.IX Header "AUTHOR"
644Zoltan 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)