From: Richard Levitte Date: Tue, 1 Oct 2019 19:26:16 +0000 (+0200) Subject: Command docs: rename openssl-tsget.pod to tsget.pod, and fix it X-Git-Tag: openssl-3.0.0-alpha1~1184 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=0503f08d6f6b94c5a985b47671acb124915c82f9;p=oweals%2Fopenssl.git Command docs: rename openssl-tsget.pod to tsget.pod, and fix it Make replacables italic, change '-rand' to '-r', fix links. Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10065) --- diff --git a/doc/man1/openssl-tsget.pod b/doc/man1/openssl-tsget.pod deleted file mode 100644 index 3ebe56b8a4..0000000000 --- a/doc/man1/openssl-tsget.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -tsget - Time Stamping HTTP/HTTPS client - -=head1 SYNOPSIS - -B -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] -[B - -=head1 DESCRIPTION - -This command can be used for sending a timestamp request, as specified -in B, to a timestamp server over HTTP or HTTPS and storing the -timestamp response in a file. It cannot be used for creating the requests -and verifying responses, you have to use L to do that. This -command can send several requests to the server without closing the TCP -connection if more than one requests are specified on the command line. - -This command sends the following HTTP request for each timestamp request: - - POST url HTTP/1.1 - User-Agent: OpenTSA tsget.pl/ - Host: : - Pragma: no-cache - Content-Type: application/timestamp-query - Accept: application/timestamp-reply - Content-Length: length of body - - ...binary request specified by the user... - -It 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 timestamp 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 timestamp response will be written to the given output file. '-' -means standard output. In case of multiple timestamp 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 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 - 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, -it will be prompted for. (Optional) - -=item B<-c> client_cert.pem - -(HTTPS) In case of certificate-based client authentication over HTTPS - 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 L. 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 B - -List of files containing B DER-encoded timestamp requests. If no -requests are specified 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 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 F and F contain valid -timestamp 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 timestamp response for F over HTTP, output is written to -F: - - tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq - -Get a timestamp response for F and F over HTTP showing -progress, output is written to F and F respectively: - - tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ - file1.tsq file2.tsq - -Create a timestamp request, write it to F, send it to the server and -write the response to F: - - openssl ts -query -data file3.txt -cert | tee file3.tsq \ - | tsget -h http://tsa.opentsa.org:8080/tsa \ - -o file3.tsr - -Get a timestamp response for F over HTTPS without client -authentication: - - tsget -h https://tsa.opentsa.org:8443/tsa \ - -C cacerts.pem file1.tsq - -Get a timestamp response for F over HTTPS with certificate-based -client authentication (it will ask for the passphrase if F 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 -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 SEE ALSO - -=for comment foreign manuals: curl(1) - -L, -L, -L, -B - -=head1 COPYRIGHT - -Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man1/tsget.pod b/doc/man1/tsget.pod new file mode 100644 index 0000000000..19c689ef6c --- /dev/null +++ b/doc/man1/tsget.pod @@ -0,0 +1,204 @@ +=pod + +=head1 NAME + +tsget - Time Stamping HTTP/HTTPS client + +=head1 SYNOPSIS + +B +B<-h> I +[B<-e> I] +[B<-o> I] +[B<-v>] +[B<-d>] +[B<-k> I] +[B<-p> I] +[B<-c> I] +[B<-C> I] +[B<-P> I] +[B<-r> I] +[B<-g> I] +[I ...] + +=head1 DESCRIPTION + +This command can be used for sending a timestamp request, as specified +in B, to a timestamp server over HTTP or HTTPS and storing the +timestamp response in a file. It cannot be used for creating the requests +and verifying responses, you have to use L to do that. This +command can send several requests to the server without closing the TCP +connection if more than one requests are specified on the command line. + +This command sends the following HTTP request for each timestamp request: + + POST url HTTP/1.1 + User-Agent: OpenTSA tsget.pl/ + Host: : + Pragma: no-cache + Content-Type: application/timestamp-query + Accept: application/timestamp-reply + Content-Length: length of body + + ...binary request specified by the user... + +It expects a response of type application/timestamp-reply, which is +written to a file without any interpretation. + +=head1 OPTIONS + +=over 4 + +=item B<-h> I + +The URL of the HTTP/HTTPS server listening for timestamp requests. + +=item B<-e> I + +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 F<.tsr>. (Optional) + +=item B<-o> I + +This option can be specified only when just one request is sent to the +server. The timestamp response will be written to the given output file. '-' +means standard output. In case of multiple timestamp 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> + +=for comment perlpodstyle(1) says to refer to modules without section + +Switches on verbose mode for the underlying perl module L. +You can see detailed debug messages for the connection. (Optional) + +=item B<-k> I + +(HTTPS) In case of certificate-based client authentication over HTTPS +I 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> I + +(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, +it will be prompted for. (Optional) + +=item B<-c> I + +(HTTPS) In case of certificate-based client authentication over HTTPS +I 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> I + +(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> I + +(HTTPS) The path containing the trusted CA certificates to verify the peer's +certificate. The directory must be prepared with L. Either +option B<-C> or option B<-P> must be given in case of HTTPS. (Optional) + +=item B<-r> I + +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> I + +The name of an EGD socket to get random data from. (Optional) + +=item I ... + +List of files containing B DER-encoded timestamp requests. If no +requests are specified 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 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 F and F contain valid +timestamp 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 timestamp response for F over HTTP, output is written to +F: + + tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq + +Get a timestamp response for F and F over HTTP showing +progress, output is written to F and F respectively: + + tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ + file1.tsq file2.tsq + +Create a timestamp request, write it to F, send it to the server and +write the response to F: + + openssl ts -query -data file3.txt -cert | tee file3.tsq \ + | tsget -h http://tsa.opentsa.org:8080/tsa \ + -o file3.tsr + +Get a timestamp response for F over HTTPS without client +authentication: + + tsget -h https://tsa.opentsa.org:8443/tsa \ + -C cacerts.pem file1.tsq + +Get a timestamp response for F over HTTPS with certificate-based +client authentication (it will ask for the passphrase if F 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 +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 SEE ALSO + +=for comment foreign manuals: WWW::Curl::Easy + +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut