doc/apps/tsget.pod

   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