svn merge -r514:HEAD ^/branches/released .

1 files changed, 194 insertions, 0 deletions

diff --git a/openssl/doc/apps/tsget.pod b/openssl/doc/apps/tsget.pod
new file mode 100644
index 000000000..b05957bee
--- /dev/null
+++ b/openssl/doc/apps/tsget.pod
@@ -0,0 +1,194 @@
+=pod
+
+=head1 NAME
+
+tsget - Time Stamping HTTP/HTTPS client
+
+=head1 SYNOPSIS
+
+B<tsget>
+B<-h> server_url
+[B<-e> extension]
+[B<-o> output]
+[B<-v>]
+[B<-d>]
+[B<-k> private_key.pem]
+[B<-p> key_password]
+[B<-c> client_cert.pem]
+[B<-C> CA_certs.pem]
+[B<-P> CA_path]
+[B<-r> file:file...]
+[B<-g> EGD_socket]
+[request]...
+
+=head1 DESCRIPTION
+
+The B<tsget> command can be used for sending a time stamp request, as
+specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing
+the time stamp response in a file. This tool cannot be used for creating the
+requests and verifying responses, you can use the OpenSSL B<ts(1)> command to
+do that. B<tsget> can send several requests to the server without closing
+the TCP connection if more than one requests are specified on the command
+line.
+
+The tool sends the following HTTP request for each time stamp request:
+
+	POST url HTTP/1.1
+	User-Agent: OpenTSA tsget.pl/<version>
+	Host: <host>:<port>
+	Pragma: no-cache
+	Content-Type: application/timestamp-query
+	Accept: application/timestamp-reply
+	Content-Length: length of body
+
+	...binary request specified by the user...
+
+B<tsget> expects a response of type application/timestamp-reply, which is
+written to a file without any interpretation.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h> server_url
+
+The URL of the HTTP/HTTPS server listening for time stamp requests.
+
+=item B<-e> extension
+
+If the B<-o> option is not given this argument specifies the extension of the
+output files. The base name of the output file will be the same as those of
+the input files. Default extension is '.tsr'. (Optional)
+
+=item B<-o> output
+
+This option can be specified only when just one request is sent to the
+server. The time stamp response will be written to the given output file. '-'
+means standard output. In case of multiple time stamp requests or the absence
+of this argument the names of the output files will be derived from the names
+of the input files and the default or specified extension argument. (Optional)
+
+=item B<-v>
+
+The name of the currently processed request is printed on standard
+error. (Optional)
+
+=item B<-d>
+
+Switches on verbose mode for the underlying B<curl> library. You can see
+detailed debug messages for the connection. (Optional)
+
+=item B<-k> private_key.pem
+
+(HTTPS) In case of certificate-based client authentication over HTTPS
+<private_key.pem> must contain the private key of the user. The private key
+file can optionally be protected by a passphrase. The B<-c> option must also
+be specified. (Optional)
+
+=item B<-p> key_password
+
+(HTTPS) Specifies the passphrase for the private key specified by the B<-k>
+argument. If this option is omitted and the key is passphrase protected B<tsget>
+will ask for it. (Optional)
+
+=item B<-c> client_cert.pem
+
+(HTTPS) In case of certificate-based client authentication over HTTPS
+<client_cert.pem> must contain the X.509 certificate of the user.  The B<-k>
+option must also be specified. If this option is not specified no
+certificate-based client authentication will take place. (Optional)
+
+=item B<-C> CA_certs.pem
+
+(HTTPS) The trusted CA certificate store. The certificate chain of the peer's
+certificate must include one of the CA certificates specified in this file.
+Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
+
+=item B<-P> CA_path
+
+(HTTPS) The path containing the trusted CA certificates to verify the peer's
+certificate. The directory must be prepared with the B<c_rehash>
+OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of
+HTTPS. (Optional)
+
+=item B<-rand> file:file...
+
+The files containing random data for seeding the random number
+generator. Multiple files can be specified, the separator is B<;> for
+MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
+
+=item B<-g> EGD_socket
+
+The name of an EGD socket to get random data from. (Optional)
+
+=item [request]...
+
+List of files containing B<RFC 3161> DER-encoded time stamp requests. If no
+requests are specifed only one request will be sent to the server and it will be
+read from the standard input. (Optional)
+
+=back
+
+=head1 ENVIRONMENT VARIABLES
+
+The B<TSGET> environment variable can optionally contain default
+arguments. The content of this variable is added to the list of command line
+arguments.
+
+=head1 EXAMPLES
+
+The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid
+time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
+and at port 8443 for HTTPS requests, the TSA service is available at the /tsa
+absolute path.
+
+Get a time stamp response for file1.tsq over HTTP, output is written to 
+file1.tsr:
+
+  tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
+
+Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
+progress, output is written to file1.reply and file2.reply respectively:
+
+  tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \
+	file1.tsq file2.tsq
+
+Create a time stamp request, write it to file3.tsq, send it to the server and
+write the response to file3.tsr:
+
+  openssl ts -query -data file3.txt -cert | tee file3.tsq \
+	| tsget -h http://tsa.opentsa.org:8080/tsa \
+	-o file3.tsr
+
+Get a time stamp response for file1.tsq over HTTPS without client
+authentication:
+
+  tsget -h https://tsa.opentsa.org:8443/tsa \
+	-C cacerts.pem file1.tsq
+
+Get a time stamp response for file1.tsq over HTTPS with certificate-based
+client authentication (it will ask for the passphrase if client_key.pem is
+protected):
+
+  tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
+	-k client_key.pem -c client_cert.pem file1.tsq
+
+You can shorten the previous command line if you make use of the B<TSGET>
+environment variable. The following commands do the same as the previous
+example:
+
+  TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
+	-k client_key.pem -c client_cert.pem'
+  export TSGET
+  tsget file1.tsq
+
+=head1 AUTHOR
+
+Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
+
+=head1 SEE ALSO
+
+L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>, 
+B<RFC 3161>
+
+=cut