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