OLD | NEW |
(Empty) | |
| 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 |
| 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 |
| 43 |
| 44 ...binary request specified by the user... |
| 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 |
| 127 requests are specifed only one request will be sent to the server and it will be |
| 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 |
| 145 Get a time stamp response for file1.tsq over HTTP, output is written to |
| 146 file1.tsr: |
| 147 |
| 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: |
| 152 |
| 153 tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ |
| 154 file1.tsq file2.tsq |
| 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: |
| 158 |
| 159 openssl ts -query -data file3.txt -cert | tee file3.tsq \ |
| 160 | tsget -h http://tsa.opentsa.org:8080/tsa \ |
| 161 -o file3.tsr |
| 162 |
| 163 Get a time stamp response for file1.tsq over HTTPS without client |
| 164 authentication: |
| 165 |
| 166 tsget -h https://tsa.opentsa.org:8443/tsa \ |
| 167 -C cacerts.pem file1.tsq |
| 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 \ |
| 174 -k client_key.pem -c client_cert.pem file1.tsq |
| 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 \ |
| 181 -k client_key.pem -c client_cert.pem' |
| 182 export TSGET |
| 183 tsget file1.tsq |
| 184 |
| 185 =head1 AUTHOR |
| 186 |
| 187 Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) |
| 188 |
| 189 =head1 SEE ALSO |
| 190 |
| 191 L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>, |
| 192 B<RFC 3161> |
| 193 |
| 194 =cut |
OLD | NEW |