| blob | fb50fecb46d61863ec6f560bccb968d5e5f4a6ba |
1 .\" $NetBSD: openssl_tsget.1,v 1.15 2015/06/12 17:01:15 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "TSGET 1"
138 .TH TSGET 1 "2011-06-05" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 tsget \- Time Stamping HTTP/HTTPS client
145 .SH "LIBRARY"
146 libcrypto, -lcrypto
147 .SH "SYNOPSIS"
148 .IX Header "SYNOPSIS"
149 \&\fBtsget\fR
150 \&\fB\-h\fR server_url
151 [\fB\-e\fR extension]
152 [\fB\-o\fR output]
153 [\fB\-v\fR]
154 [\fB\-d\fR]
155 [\fB\-k\fR private_key.pem]
156 [\fB\-p\fR key_password]
157 [\fB\-c\fR client_cert.pem]
158 [\fB\-C\fR CA_certs.pem]
159 [\fB\-P\fR CA_path]
160 [\fB\-r\fR file:file...]
161 [\fB\-g\fR EGD_socket]
162 [request]...
163 .SH "DESCRIPTION"
164 .IX Header "DESCRIPTION"
165 The \fBtsget\fR command can be used for sending a time stamp request, as
166 specified in \fB\s-1RFC 3161\s0\fR, to a time stamp server over \s-1HTTP\s0 or \s-1HTTPS\s0 and storing
167 the time stamp response in a file. This tool cannot be used for creating the
168 requests and verifying responses, you can use the OpenSSL \fB\f(BIts\fB\|(1)\fR command to
169 do that. \fBtsget\fR can send several requests to the server without closing
170 the \s-1TCP\s0 connection if more than one requests are specified on the command
171 line.
172 .PP
173 The tool sends the following \s-1HTTP\s0 request for each time stamp request:
174 .PP
175 .Vb 7
176 \& POST url HTTP/1.1
177 \& User\-Agent: OpenTSA tsget.pl/<version>
178 \& Host: <host>:<port>
179 \& Pragma: no\-cache
180 \& Content\-Type: application/timestamp\-query
181 \& Accept: application/timestamp\-reply
182 \& Content\-Length: length of body
183 \&
184 \& ...binary request specified by the user...
185 .Ve
186 .PP
187 \&\fBtsget\fR expects a response of type application/timestamp\-reply, which is
188 written to a file without any interpretation.
189 .SH "OPTIONS"
190 .IX Header "OPTIONS"
191 .IP "\fB\-h\fR server_url" 4
192 .IX Item "-h server_url"
193 The \s-1URL\s0 of the \s-1HTTP/HTTPS\s0 server listening for time stamp requests.
194 .IP "\fB\-e\fR extension" 4
195 .IX Item "-e extension"
196 If the \fB\-o\fR option is not given this argument specifies the extension of the
197 output files. The base name of the output file will be the same as those of
198 the input files. Default extension is '.tsr'. (Optional)
199 .IP "\fB\-o\fR output" 4
200 .IX Item "-o output"
201 This option can be specified only when just one request is sent to the
202 server. The time stamp response will be written to the given output file. '\-'
203 means standard output. In case of multiple time stamp requests or the absence
204 of this argument the names of the output files will be derived from the names
205 of the input files and the default or specified extension argument. (Optional)
206 .IP "\fB\-v\fR" 4
207 .IX Item "-v"
208 The name of the currently processed request is printed on standard
209 error. (Optional)
210 .IP "\fB\-d\fR" 4
211 .IX Item "-d"
212 Switches on verbose mode for the underlying \fBcurl\fR library. You can see
213 detailed debug messages for the connection. (Optional)
214 .IP "\fB\-k\fR private_key.pem" 4
215 .IX Item "-k private_key.pem"
216 (\s-1HTTPS\s0) In case of certificate-based client authentication over \s-1HTTPS\s0
217 <private_key.pem> must contain the private key of the user. The private key
218 file can optionally be protected by a passphrase. The \fB\-c\fR option must also
219 be specified. (Optional)
220 .IP "\fB\-p\fR key_password" 4
221 .IX Item "-p key_password"
222 (\s-1HTTPS\s0) Specifies the passphrase for the private key specified by the \fB\-k\fR
223 argument. If this option is omitted and the key is passphrase protected \fBtsget\fR
224 will ask for it. (Optional)
225 .IP "\fB\-c\fR client_cert.pem" 4
226 .IX Item "-c client_cert.pem"
227 (\s-1HTTPS\s0) In case of certificate-based client authentication over \s-1HTTPS\s0
228 <client_cert.pem> must contain the X.509 certificate of the user. The \fB\-k\fR
229 option must also be specified. If this option is not specified no
230 certificate-based client authentication will take place. (Optional)
231 .IP "\fB\-C\fR CA_certs.pem" 4
232 .IX Item "-C CA_certs.pem"
233 (\s-1HTTPS\s0) The trusted \s-1CA\s0 certificate store. The certificate chain of the peer's
234 certificate must include one of the \s-1CA\s0 certificates specified in this file.
235 Either option \fB\-C\fR or option \fB\-P\fR must be given in case of \s-1HTTPS. \s0(Optional)
236 .IP "\fB\-P\fR CA_path" 4
237 .IX Item "-P CA_path"
238 (\s-1HTTPS\s0) The path containing the trusted \s-1CA\s0 certificates to verify the peer's
239 certificate. The directory must be prepared with the \fBc_rehash\fR
240 OpenSSL utility. Either option \fB\-C\fR or option \fB\-P\fR must be given in case of
241 \&\s-1HTTPS. \s0(Optional)
242 .IP "\fB\-rand\fR file:file..." 4
243 .IX Item "-rand file:file..."
244 The files containing random data for seeding the random number
245 generator. Multiple files can be specified, the separator is \fB;\fR for
246 MS-Windows, \fB,\fR for \s-1VMS\s0 and \fB:\fR for all other platforms. (Optional)
247 .IP "\fB\-g\fR EGD_socket" 4
248 .IX Item "-g EGD_socket"
249 The name of an \s-1EGD\s0 socket to get random data from. (Optional)
250 .IP "[request]..." 4
251 .IX Item "[request]..."
252 List of files containing \fB\s-1RFC 3161\s0\fR DER-encoded time stamp requests. If no
253 requests are specified only one request will be sent to the server and it will be
254 read from the standard input. (Optional)
255 .SH "ENVIRONMENT VARIABLES"
256 .IX Header "ENVIRONMENT VARIABLES"
257 The \fB\s-1TSGET\s0\fR environment variable can optionally contain default
258 arguments. The content of this variable is added to the list of command line
259 arguments.
260 .SH "EXAMPLES"
261 .IX Header "EXAMPLES"
262 The examples below presume that \fBfile1.tsq\fR and \fBfile2.tsq\fR contain valid
263 time stamp requests, tsa.opentsa.org listens at port 8080 for \s-1HTTP\s0 requests
264 and at port 8443 for \s-1HTTPS\s0 requests, the \s-1TSA\s0 service is available at the /tsa
265 absolute path.
266 .PP
267 Get a time stamp response for file1.tsq over \s-1HTTP,\s0 output is written to
268 file1.tsr:
269 .PP
270 .Vb 1
271 \& tsget \-h http://tsa.opentsa.org:8080/tsa file1.tsq
272 .Ve
273 .PP
274 Get a time stamp response for file1.tsq and file2.tsq over \s-1HTTP\s0 showing
275 progress, output is written to file1.reply and file2.reply respectively:
276 .PP
277 .Vb 2
278 \& tsget \-h http://tsa.opentsa.org:8080/tsa \-v \-e .reply \e
279 \& file1.tsq file2.tsq
280 .Ve
281 .PP
282 Create a time stamp request, write it to file3.tsq, send it to the server and
283 write the response to file3.tsr:
284 .PP
285 .Vb 3
286 \& openssl ts \-query \-data file3.txt \-cert | tee file3.tsq \e
287 \& | tsget \-h http://tsa.opentsa.org:8080/tsa \e
288 \& \-o file3.tsr
289 .Ve
290 .PP
291 Get a time stamp response for file1.tsq over \s-1HTTPS\s0 without client
292 authentication:
293 .PP
294 .Vb 2
295 \& tsget \-h https://tsa.opentsa.org:8443/tsa \e
296 \& \-C cacerts.pem file1.tsq
297 .Ve
298 .PP
299 Get a time stamp response for file1.tsq over \s-1HTTPS\s0 with certificate-based
300 client authentication (it will ask for the passphrase if client_key.pem is
301 protected):
302 .PP
303 .Vb 2
304 \& tsget \-h https://tsa.opentsa.org:8443/tsa \-C cacerts.pem \e
305 \& \-k client_key.pem \-c client_cert.pem file1.tsq
306 .Ve
307 .PP
308 You can shorten the previous command line if you make use of the \fB\s-1TSGET\s0\fR
309 environment variable. The following commands do the same as the previous
310 example:
311 .PP
312 .Vb 4
313 \& TSGET=\*(Aq\-h https://tsa.opentsa.org:8443/tsa \-C cacerts.pem \e
314 \& \-k client_key.pem \-c client_cert.pem\*(Aq
315 \& export TSGET
316 \& tsget file1.tsq
317 .Ve
318 .SH "AUTHOR"
319 .IX Header "AUTHOR"
320 Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
321 .SH "SEE ALSO"
322 .IX Header "SEE ALSO"
323 \&\fIopenssl\fR\|(1), \fIts\fR\|(1), \fIcurl\fR\|(1),
324 \&\fB\s-1RFC 3161\s0\fR