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