diff options
Diffstat (limited to 'doc/apps')
-rw-r--r-- | doc/apps/openssl.pod | 3 | ||||
-rw-r--r-- | doc/apps/s_client.pod | 6 | ||||
-rw-r--r-- | doc/apps/s_time.pod | 167 |
3 files changed, 172 insertions, 4 deletions
diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index 07dd80eabe..dc0f49ddca 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -329,7 +329,8 @@ L<passwd(1)|passwd(1)>, L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>, L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>, -L<s_server(1)|s_server(1)>, L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>, +L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>, +L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>, L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>, L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)> diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod index d061326c1f..8d19079973 100644 --- a/doc/apps/s_client.pod +++ b/doc/apps/s_client.pod @@ -8,7 +8,7 @@ s_client - SSL/TLS client program =head1 SYNOPSIS B<openssl> B<s_client> -[B<-connect> host:port>] +[B<-connect host:port>] [B<-verify depth>] [B<-cert filename>] [B<-key filename>] @@ -208,7 +208,7 @@ then an HTTP command can be given such as "GET /" to retrieve a web page. If the handshake fails then there are several possible causes, if it is nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>, -B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> can be tried +B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> 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. @@ -219,7 +219,7 @@ the clients certificate authority in its "acceptable CA list" when it requests a certificate. By using B<s_client> 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> command and send an HTTP request +is necessary to use the B<-prexit> option and send an HTTP request for an appropriate page. If a certificate is specified on the command line using the B<-cert> diff --git a/doc/apps/s_time.pod b/doc/apps/s_time.pod new file mode 100644 index 0000000000..a7e3c3e5bc --- /dev/null +++ b/doc/apps/s_time.pod @@ -0,0 +1,167 @@ + +=pod + +=head1 NAME + +s_time - SSL/TLS performance timing program + +=head1 SYNOPSIS + +B<openssl> B<s_time> +[B<-connect host:port>] +[B<-www page>] +[B<-cert filename>] +[B<-key filename>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-reuse>] +[B<-new>] +[B<-verify depth>] +[B<-nbio>] +[B<-time seconds>] +[B<-ssl2>] +[B<-ssl3>] +[B<-bugs>] +[B<-cipher cipherlist>] + +=head1 DESCRIPTION + +The B<s_client> 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<-connect host:port> + +This specifies the host and optional port to connect to. + +=item B<-www page> + +This specifies the page to GET from the server. A value of '/' gets the +index.htm[l] page. If this parameter is not specified, then B<s_time> will only +perform the handshake to establish SSL connections but not transfer any +payload data. + +=item B<-cert 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 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 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<-CApath directory> + +The directory to use for server certificate verification. This directory +must be in "hash format", see B<verify> for more information. These are +also used when building the client certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during server authentication +and to use when attempting to build 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<-nbio> + +turns on non-blocking I/O. + +=item B<-ssl2>, B<-ssl3> + +these options disable the use of certain SSL or TLS protocols. By default +the initial handshake uses a method which should be compatible with all +servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. +The timing program is not as rich in options to turn protocols on and off as +the L<s_client(1)|s_client(1)> program and may not connect to all servers. + +Unfortunately there are a lot of ancient and broken servers in use which +cannot handle this technique and will fail to connect. Some servers only +work if TLS is turned off with the B<-ssl3> option; others +will only support SSL v2 and may need the B<-ssl2> option. + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-cipher cipherlist> + +this allows the cipher list sent by the client to be modified. Although +the server determines which cipher suite is used it should take the first +supported cipher in the list sent by the client. +See the L<ciphers(1)|ciphers(1)> command for more information. + +=back + +=head1 NOTES + +B<s_client> 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). 'commoncipher' is a cipher to +which both client and server can agree, see the L<cipher(1)|cipher(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>, B<-ssl2>, +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<s_client(1)|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<s_client(1)|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<s_client(1)|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<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> + +=cut |