]>
Commit | Line | Data |
---|---|---|
c7235be6 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | tsget - Time Stamping HTTP/HTTPS client | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<tsget> | |
10 | B<-h> server_url | |
11 | [B<-e> extension] | |
12 | [B<-o> output] | |
13 | [B<-v>] | |
14 | [B<-d>] | |
15 | [B<-k> private_key.pem] | |
16 | [B<-p> key_password] | |
17 | [B<-c> client_cert.pem] | |
18 | [B<-C> CA_certs.pem] | |
19 | [B<-P> CA_path] | |
20 | [B<-r> file:file...] | |
21 | [B<-g> EGD_socket] | |
22 | [request]... | |
23 | ||
24 | =head1 DESCRIPTION | |
25 | ||
26 | The B<tsget> command can be used for sending a time stamp request, as | |
27 | specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing | |
28 | the time stamp response in a file. This tool cannot be used for creating the | |
29 | requests and verifying responses, you can use the OpenSSL B<ts(1)> command to | |
30 | do that. B<tsget> can send several requests to the server without closing | |
31 | the TCP connection if more than one requests are specified on the command | |
32 | line. | |
33 | ||
34 | The tool sends the following HTTP request for each time stamp request: | |
35 | ||
1bc74519 RS |
36 | POST url HTTP/1.1 |
37 | User-Agent: OpenTSA tsget.pl/<version> | |
38 | Host: <host>:<port> | |
39 | Pragma: no-cache | |
40 | Content-Type: application/timestamp-query | |
41 | Accept: application/timestamp-reply | |
42 | Content-Length: length of body | |
c7235be6 | 43 | |
1bc74519 | 44 | ...binary request specified by the user... |
c7235be6 UM |
45 | |
46 | B<tsget> expects a response of type application/timestamp-reply, which is | |
47 | written to a file without any interpretation. | |
48 | ||
49 | =head1 OPTIONS | |
50 | ||
51 | =over 4 | |
52 | ||
53 | =item B<-h> server_url | |
54 | ||
55 | The URL of the HTTP/HTTPS server listening for time stamp requests. | |
56 | ||
57 | =item B<-e> extension | |
58 | ||
59 | If the B<-o> option is not given this argument specifies the extension of the | |
60 | output files. The base name of the output file will be the same as those of | |
61 | the input files. Default extension is '.tsr'. (Optional) | |
62 | ||
63 | =item B<-o> output | |
64 | ||
65 | This option can be specified only when just one request is sent to the | |
66 | server. The time stamp response will be written to the given output file. '-' | |
67 | means standard output. In case of multiple time stamp requests or the absence | |
68 | of this argument the names of the output files will be derived from the names | |
69 | of the input files and the default or specified extension argument. (Optional) | |
70 | ||
71 | =item B<-v> | |
72 | ||
73 | The name of the currently processed request is printed on standard | |
74 | error. (Optional) | |
75 | ||
76 | =item B<-d> | |
77 | ||
78 | Switches on verbose mode for the underlying B<curl> library. You can see | |
79 | detailed debug messages for the connection. (Optional) | |
80 | ||
81 | =item B<-k> private_key.pem | |
82 | ||
83 | (HTTPS) In case of certificate-based client authentication over HTTPS | |
84 | <private_key.pem> must contain the private key of the user. The private key | |
85 | file can optionally be protected by a passphrase. The B<-c> option must also | |
86 | be specified. (Optional) | |
87 | ||
88 | =item B<-p> key_password | |
89 | ||
90 | (HTTPS) Specifies the passphrase for the private key specified by the B<-k> | |
91 | argument. If this option is omitted and the key is passphrase protected B<tsget> | |
92 | will ask for it. (Optional) | |
93 | ||
94 | =item B<-c> client_cert.pem | |
95 | ||
96 | (HTTPS) In case of certificate-based client authentication over HTTPS | |
97 | <client_cert.pem> must contain the X.509 certificate of the user. The B<-k> | |
98 | option must also be specified. If this option is not specified no | |
99 | certificate-based client authentication will take place. (Optional) | |
100 | ||
101 | =item B<-C> CA_certs.pem | |
102 | ||
103 | (HTTPS) The trusted CA certificate store. The certificate chain of the peer's | |
104 | certificate must include one of the CA certificates specified in this file. | |
105 | Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional) | |
106 | ||
107 | =item B<-P> CA_path | |
108 | ||
109 | (HTTPS) The path containing the trusted CA certificates to verify the peer's | |
110 | certificate. The directory must be prepared with the B<c_rehash> | |
111 | OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of | |
112 | HTTPS. (Optional) | |
113 | ||
114 | =item B<-rand> file:file... | |
115 | ||
116 | The files containing random data for seeding the random number | |
117 | generator. Multiple files can be specified, the separator is B<;> for | |
118 | MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) | |
119 | ||
120 | =item B<-g> EGD_socket | |
121 | ||
122 | The name of an EGD socket to get random data from. (Optional) | |
123 | ||
124 | =item [request]... | |
125 | ||
126 | List of files containing B<RFC 3161> DER-encoded time stamp requests. If no | |
2b4ffc65 | 127 | requests are specified only one request will be sent to the server and it will be |
c7235be6 UM |
128 | read from the standard input. (Optional) |
129 | ||
130 | =back | |
131 | ||
132 | =head1 ENVIRONMENT VARIABLES | |
133 | ||
134 | The B<TSGET> environment variable can optionally contain default | |
135 | arguments. The content of this variable is added to the list of command line | |
136 | arguments. | |
137 | ||
138 | =head1 EXAMPLES | |
139 | ||
140 | The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid | |
141 | time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests | |
142 | and at port 8443 for HTTPS requests, the TSA service is available at the /tsa | |
143 | absolute path. | |
144 | ||
1bc74519 | 145 | Get a time stamp response for file1.tsq over HTTP, output is written to |
c7235be6 | 146 | file1.tsr: |
6084c797 | 147 | |
c7235be6 UM |
148 | tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq |
149 | ||
150 | Get a time stamp response for file1.tsq and file2.tsq over HTTP showing | |
151 | progress, output is written to file1.reply and file2.reply respectively: | |
6084c797 | 152 | |
c7235be6 | 153 | tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ |
1bc74519 | 154 | file1.tsq file2.tsq |
c7235be6 UM |
155 | |
156 | Create a time stamp request, write it to file3.tsq, send it to the server and | |
157 | write the response to file3.tsr: | |
6084c797 | 158 | |
c7235be6 | 159 | openssl ts -query -data file3.txt -cert | tee file3.tsq \ |
1bc74519 RS |
160 | | tsget -h http://tsa.opentsa.org:8080/tsa \ |
161 | -o file3.tsr | |
c7235be6 UM |
162 | |
163 | Get a time stamp response for file1.tsq over HTTPS without client | |
164 | authentication: | |
6084c797 | 165 | |
c7235be6 | 166 | tsget -h https://tsa.opentsa.org:8443/tsa \ |
1bc74519 | 167 | -C cacerts.pem file1.tsq |
c7235be6 UM |
168 | |
169 | Get a time stamp response for file1.tsq over HTTPS with certificate-based | |
170 | client authentication (it will ask for the passphrase if client_key.pem is | |
171 | protected): | |
172 | ||
173 | tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ | |
1bc74519 | 174 | -k client_key.pem -c client_cert.pem file1.tsq |
c7235be6 UM |
175 | |
176 | You can shorten the previous command line if you make use of the B<TSGET> | |
177 | environment variable. The following commands do the same as the previous | |
178 | example: | |
179 | ||
180 | TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ | |
1bc74519 | 181 | -k client_key.pem -c client_cert.pem' |
c7235be6 UM |
182 | export TSGET |
183 | tsget file1.tsq | |
184 | ||
c7235be6 UM |
185 | =head1 SEE ALSO |
186 | ||
b275f3b6 RL |
187 | =for comment foreign manuals: curl(1) |
188 | ||
b6b66573 DMSP |
189 | L<openssl(1)>, |
190 | L<openssl-ts(1)>, | |
191 | L<openssl-curl(1)>, | |
c7235be6 UM |
192 | B<RFC 3161> |
193 | ||
e2f92610 RS |
194 | =head1 COPYRIGHT |
195 | ||
b6b66573 | 196 | Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 197 | |
449040b4 | 198 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
199 | this file except in compliance with the License. You can obtain a copy |
200 | in the file LICENSE in the source distribution or at | |
201 | L<https://www.openssl.org/source/license.html>. | |
202 | ||
203 | =cut |