diff options
author | Rich Salz <rsalz@akamai.com> | 2019-10-12 17:45:56 -0400 |
---|---|---|
committer | Tomas Mraz <tmraz@fedoraproject.org> | 2019-10-31 14:19:29 +0100 |
commit | 9fcb9702fba8aa135945f96aefddf050a6f4f11d (patch) | |
tree | 5fa0e0061ca70c9b0678636ee68c713653e7dba8 /doc/man1/openssl-s_time.pod.in | |
parent | fb1ecf85c9f732e5827771ff243d7a70e06ce112 (diff) |
Infrastructure for templated doc in POD files
Use new doc-build capabilities
Add -i flag to dofile.
Add doc/man1 to SUBDIRS for the new templated doc files
Rewrite commit a397aca (merged from PR 10118) to use the doc-template stuff.
Put template references in common place
Template options and text come at the end of command-specific options:
opt_x, opt_trust, opt_r (in that order).
Refactor xchain options.
Do doc-nits after building generated sources.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10159)
Diffstat (limited to 'doc/man1/openssl-s_time.pod.in')
-rw-r--r-- | doc/man1/openssl-s_time.pod.in | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/doc/man1/openssl-s_time.pod.in b/doc/man1/openssl-s_time.pod.in new file mode 100644 index 0000000000..737424da87 --- /dev/null +++ b/doc/man1/openssl-s_time.pod.in @@ -0,0 +1,207 @@ +=pod + +=begin comment +{- join("\n", @autowarntext) -} + +=end comment + +=head1 NAME + +openssl-s_time - SSL/TLS performance timing program + +=head1 SYNOPSIS + +B<openssl> B<s_time> +[B<-help>] +[B<-connect> I<host>:I<port>] +[B<-www> I<page>] +[B<-cert> I<filename>] +[B<-key> I<filename>] +[B<-reuse>] +[B<-new>] +[B<-verify> I<depth>] +[B<-nameopt> I<option>] +[B<-time> I<seconds>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-tls1_3>] +[B<-bugs>] +[B<-cipher> I<cipherlist>] +[B<-ciphersuites> I<val>] +{- $OpenSSL::safe::opt_trust_synopsis -} + +=for openssl ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 + +=head1 DESCRIPTION + +This command implements a generic SSL/TLS client which +connects to a remote host using SSL/TLS. It can request a page from the server +and includes the time to transfer the payload data in its timing measurements. +It measures the number of connections within a given timeframe, the amount of +data transferred (if any), and calculates the average time spent for one +connection. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-connect> I<host>:I<port> + +This specifies the host and optional port to connect to. + +=item B<-www> I<page> + +This specifies the page to GET from the server. A value of '/' gets the +F<index.html> page. If this parameter is not specified, then this command +will only perform the handshake to establish SSL connections but not transfer +any payload data. + +=item B<-cert> I<certname> + +The certificate to use, if one is requested by the server. The default is +not to use a certificate. The file is in PEM format. + +=item B<-key> I<keyfile> + +The private key to use. If not specified then the certificate file will +be used. The file is in PEM format. + +=item B<-verify> I<depth> + +The verify depth to use. This specifies the maximum length of the +server certificate chain and turns on server certificate verification. +Currently the verify operation continues after errors so all the problems +with a certificate chain can be seen. As a side effect the connection +will never fail due to a server certificate verify failure. + +=item B<-nameopt> I<option> + +Option which determines how the subject or issuer names are displayed. The +I<option> argument can be a single option or multiple options separated by +commas. Alternatively the B<-nameopt> switch may be used more than once to +set multiple options. See the L<openssl-x509(1)> manual page for details. + +=item B<-CApath> I<directory> + +The directory to use for server certificate verification. This directory +must be in "hash format", see L<openssl-verify(1)> for more information. +These are also used when building the client certificate chain. + +=item B<-new> + +Performs the timing test using a new session ID for each connection. +If neither B<-new> nor B<-reuse> are specified, they are both on by default +and executed in sequence. + +=item B<-reuse> + +Performs the timing test using the same session ID; this can be used as a test +that session caching is working. If neither B<-new> nor B<-reuse> are +specified, they are both on by default and executed in sequence. + +=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3> + +These options enable specific SSL or TLS protocol versions for the handshake +initiated by this command. +By default, it negotiates the highest mutually supported protocol +version. +Note that not all protocols and flags may be available, depending on how +OpenSSL was built. + +=item B<-bugs> + +There are several known bugs in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-cipher> I<cipherlist> + +This allows the TLSv1.2 and below cipher list sent by the client to be modified. +This list will be combined with any TLSv1.3 ciphersuites that have been +configured. Although the server determines which cipher suite is used it should +take the first supported cipher in the list sent by the client. See +L<openssl-ciphers(1)> for more information. + +=item B<-ciphersuites> I<val> + +This allows the TLSv1.3 ciphersuites sent by the client to be modified. This +list will be combined with any TLSv1.2 and below ciphersuites that have been +configured. Although the server determines which cipher suite is used it should +take the first supported cipher in the list sent by the client. See +L<openssl-ciphers(1)> for more information. The format for this list is a +simple colon (":") separated list of TLSv1.3 ciphersuite names. + +=item B<-time> I<length> + +Specifies how long (in seconds) this command should establish connections +and optionally transfer payload data from a server. Server and client +performance and the link speed determine how many connections it +can establish. + +{- $OpenSSL::safe::opt_trust_item -} + +=back + +=head1 NOTES + +This command can be used to measure the performance of an SSL connection. +To connect to an SSL HTTP server and get the default page the command + + openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3] + +would typically be used (https uses port 443). I<commoncipher> is a cipher to +which both client and server can agree, see the L<openssl-ciphers(1)> command +for details. + +If the handshake fails then there are several possible causes, if it is +nothing obvious like no client certificate then the B<-bugs> and +B<-ssl3> options can be tried +in case it is a buggy server. In particular you should play with these +options B<before> submitting a bug report to an OpenSSL mailing list. + +A frequent problem when attempting to get client certificates working +is that a web client complains it has no certificates or gives an empty +list to choose from. This is normally because the server is not sending +the clients certificate authority in its "acceptable CA list" when it +requests a certificate. By using L<openssl-s_client(1)> the CA list can be +viewed and checked. However some servers only request client authentication +after a specific URL is requested. To obtain the list in this case it +is necessary to use the B<-prexit> option of L<openssl-s_client(1)> and +send an HTTP request for an appropriate page. + +If a certificate is specified on the command line using the B<-cert> +option it will not be used unless the server specifically requests +a client certificate. Therefor merely including a client certificate +on the command line is no guarantee that the certificate works. + +=head1 BUGS + +Because this program does not have all the options of the +L<openssl-s_client(1)> program to turn protocols on and off, you may not +be able to measure the performance of all protocols with all servers. + +The B<-verify> option should really exit if the server verification +fails. + +=head1 SEE ALSO + +L<openssl(1)>, +L<openssl-s_client(1)>, +L<openssl-s_server(1)>, +L<openssl-ciphers(1)> + +=head1 COPYRIGHT + +Copyright 2004-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<https://www.openssl.org/source/license.html>. + +=cut |