1=pod 2 3=head1 NAME 4 5tsget - Time Stamping HTTP/HTTPS client 6 7=head1 SYNOPSIS 8 9B<tsget> 10B<-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 26The B<tsget> command can be used for sending a time stamp request, as 27specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing 28the time stamp response in a file. This tool cannot be used for creating the 29requests and verifying responses, you can use the OpenSSL B<ts(1)> command to 30do that. B<tsget> can send several requests to the server without closing 31the TCP connection if more than one requests are specified on the command 32line. 33 34The 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 46B<tsget> expects a response of type application/timestamp-reply, which is 47written to a file without any interpretation. 48 49=head1 OPTIONS 50 51=over 4 52 53=item B<-h> server_url 54 55The URL of the HTTP/HTTPS server listening for time stamp requests. 56 57=item B<-e> extension 58 59If the B<-o> option is not given this argument specifies the extension of the 60output files. The base name of the output file will be the same as those of 61the input files. Default extension is '.tsr'. (Optional) 62 63=item B<-o> output 64 65This option can be specified only when just one request is sent to the 66server. The time stamp response will be written to the given output file. '-' 67means standard output. In case of multiple time stamp requests or the absence 68of this argument the names of the output files will be derived from the names 69of the input files and the default or specified extension argument. (Optional) 70 71=item B<-v> 72 73The name of the currently processed request is printed on standard 74error. (Optional) 75 76=item B<-d> 77 78Switches on verbose mode for the underlying B<curl> library. You can see 79detailed 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 85file can optionally be protected by a passphrase. The B<-c> option must also 86be specified. (Optional) 87 88=item B<-p> key_password 89 90(HTTPS) Specifies the passphrase for the private key specified by the B<-k> 91argument. If this option is omitted and the key is passphrase protected B<tsget> 92will 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> 98option must also be specified. If this option is not specified no 99certificate-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 104certificate must include one of the CA certificates specified in this file. 105Either 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 110certificate. The directory must be prepared with the B<c_rehash> 111OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of 112HTTPS. (Optional) 113 114=item B<-rand> file:file... 115 116The files containing random data for seeding the random number 117generator. Multiple files can be specified, the separator is B<;> for 118MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) 119 120=item B<-g> EGD_socket 121 122The name of an EGD socket to get random data from. (Optional) 123 124=item [request]... 125 126List of files containing B<RFC 3161> DER-encoded time stamp requests. If no 127requests are specified only one request will be sent to the server and it will be 128read from the standard input. (Optional) 129 130=back 131 132=head1 ENVIRONMENT VARIABLES 133 134The B<TSGET> environment variable can optionally contain default 135arguments. The content of this variable is added to the list of command line 136arguments. 137 138=head1 EXAMPLES 139 140The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid 141time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests 142and at port 8443 for HTTPS requests, the TSA service is available at the /tsa 143absolute path. 144 145Get a time stamp response for file1.tsq over HTTP, output is written to 146file1.tsr: 147 148 tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq 149 150Get a time stamp response for file1.tsq and file2.tsq over HTTP showing 151progress, 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 156Create a time stamp request, write it to file3.tsq, send it to the server and 157write 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 163Get a time stamp response for file1.tsq over HTTPS without client 164authentication: 165 166 tsget -h https://tsa.opentsa.org:8443/tsa \ 167 -C cacerts.pem file1.tsq 168 169Get a time stamp response for file1.tsq over HTTPS with certificate-based 170client authentication (it will ask for the passphrase if client_key.pem is 171protected): 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 176You can shorten the previous command line if you make use of the B<TSGET> 177environment variable. The following commands do the same as the previous 178example: 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 187Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) 188 189=head1 SEE ALSO 190 191L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>, 192B<RFC 3161> 193 194=cut 195