X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fs_client.pod;h=e91b9f1334a5e95310a793fc0f7fc55aca7ec8b6;hp=cd9093eaba25cf9045e7db6d6ea5ff37bea44a32;hb=898ea7b855541b5809e25944c8dada7b50775fd3;hpb=dd46d58f65bd3a342bbcd8586680942be643fc7d diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod index cd9093eaba..e91b9f1334 100644 --- a/doc/apps/s_client.pod +++ b/doc/apps/s_client.pod @@ -8,29 +8,78 @@ s_client - SSL/TLS client program =head1 SYNOPSIS B B -[B<-connect> host:port>] +[B<-connect host:port>] +[B<-proxy host:port>] +[B<-servername name>] [B<-verify depth>] +[B<-verify_return_error>] [B<-cert filename>] +[B<-certform DER|PEM>] [B<-key filename>] +[B<-keyform DER|PEM>] +[B<-pass arg>] [B<-CApath directory>] [B<-CAfile filename>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-issuer_checks>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] [B<-reconnect>] [B<-pause>] [B<-showcerts>] [B<-debug>] +[B<-msg>] [B<-nbio_test>] [B<-state>] [B<-nbio>] [B<-crlf>] +[B<-ign_eof>] +[B<-no_ign_eof>] [B<-quiet>] -[B<-ssl2>] [B<-ssl3>] [B<-tls1>] -[B<-no_ssl2>] [B<-no_ssl3>] [B<-no_tls1>] +[B<-no_tls1_1>] +[B<-no_tls1_2>] +[B<-fallback_scsv>] [B<-bugs>] [B<-cipher cipherlist>] +[B<-serverpref>] +[B<-starttls protocol>] +[B<-xmpphost hostname>] +[B<-engine id>] +[B<-tlsextdebug>] +[B<-no_ticket>] +[B<-sess_out filename>] +[B<-sess_in filename>] +[B<-rand file(s)>] +[B<-serverinfo types>] +[B<-status>] +[B<-nextprotoneg protocols>] =head1 DESCRIPTION @@ -40,6 +89,11 @@ SSL servers. =head1 OPTIONS +In addition to the options below the B utility also supports the +common and client only options documented in the +in the L +manual page. + =over 4 =item B<-connect host:port> @@ -47,16 +101,39 @@ SSL servers. This specifies the host and optional port to connect to. If not specified then an attempt is made to connect to the local host on port 4433. +=item B<-proxy host:port> + +When used with the B<-connect> flag, the program uses the host and port +specified with this flag and issues an HTTP CONNECT command to connect +to the desired server. + +=item B<-servername name> + +Set the TLS SNI (Server Name Indication) extension in the ClientHello message. + =item B<-cert certname> The certificate to use, if one is requested by the server. The default is not to use a certificate. +=item B<-certform format> + +The certificate format to use: DER or PEM. PEM is the default. + =item B<-key keyfile> The private key to use. If not specified then the certificate file will be used. +=item B<-keyform format> + +The private format to use: DER or PEM. PEM is the default. + +=item B<-pass arg> + +the private key password source. For more information about the format of B +see the B section in L. + =item B<-verify depth> The verify depth to use. This specifies the maximum length of the @@ -65,6 +142,11 @@ 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<-verify_return_error> + +Return verification errors instead of continuing. This will typically +abort the handshake with a fatal error. + =item B<-CApath directory> The directory to use for server certificate verification. This directory @@ -76,6 +158,17 @@ also used when building the client certificate chain. A file containing trusted certificates to use during server authentication and to use when attempting to build the client certificate chain. +=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-issuer_checks>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-no_alt_chains>, +B<-use_deltas>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set various certificate chain validation options. See the +L|verify(1)> manual page for details. + =item B<-reconnect> reconnects to the same server 5 times using the same session ID, this can @@ -109,43 +202,156 @@ prints out the SSL session states. print extensive debugging information including a hex dump of all traffic. +=item B<-msg> + +show all protocol messages with hex dump. + +=item B<-trace> + +show verbose trace output of protocol messages. OpenSSL needs to be compiled +with B for this option to work. + +=item B<-msgfile> + +file to send output of B<-msg> or B<-trace> to, default standard output. + =item B<-nbio_test> -tests non blocking I/O +tests non-blocking I/O =item B<-nbio> -turns on non blocking I/O +turns on non-blocking I/O =item B<-crlf> this option translated a line feed from the terminal into CR+LF as required by some servers. +=item B<-ign_eof> + +inhibit shutting down the connection when end of file is reached in the +input. + =item B<-quiet> -inhibit printing of session and certificate information. +inhibit printing of session and certificate information. This implicitly +turns on B<-ign_eof> as well. -=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> +=item B<-no_ign_eof> + +shut down the connection when end of file is reached in the input. +Can be used to override the implicit B<-ign_eof> after B<-quiet>. + +=item B<-psk_identity identity> + +Use the PSK identity B when using a PSK cipher suite. + +=item B<-psk key> + +Use the PSK key B when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. + +=item B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> 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. +servers and permit them to use SSL v3 or TLS as appropriate. -Unfortunately there are a lot of ancient and broken servers in use which +Unfortunately there are still 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<-no_tls> option others will only -support SSL v2 and may need the B<-ssl2> option. +work if TLS is turned off. + +=item B<-fallback_scsv> + +Send TLS_FALLBACK_SCSV in the ClientHello. =item B<-bugs> there are several known bug in SSL and TLS implementations. Adding this option enables various workarounds. +=item B<-brief> + +only provide a brief summary of connection parameters instead of the +normal verbose output. + =item B<-cipher cipherlist> -this allows the cipher list sent by the client to be modified. See the -B command for more information. +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 B +command for more information. + +=item B<-starttls protocol> + +send the protocol-specific message(s) to switch to TLS for communication. +B is a keyword for the intended protocol. Currently, the only +supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", +and "xmpp-server". + +=item B<-xmpphost hostname> + +This option, when used with "-starttls xmpp" or "-starttls xmpp-server", +specifies the host for the "to" attribute of the stream element. +If this option is not specified, then the host specified with "-connect" +will be used. + +=item B<-tlsextdebug> + +print out a hex dump of any TLS extensions received from the server. + +=item B<-no_ticket> + +disable RFC4507bis session ticket support. + +=item B<-sess_out filename> + +output SSL session to B + +=item B<-sess_in sess.pem> + +load SSL session from B. The client will attempt to resume a +connection from this session. + +=item B<-engine id> + +specifying an engine (by its unique B string) will cause B +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L). +Multiple files can be specified separated by a OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-serverinfo types> + +a list of comma-separated TLS Extension Types (numbers between 0 and +65535). Each type will be sent as an empty ClientHello TLS Extension. +The server's response (if any) will be encoded and displayed as a PEM +file. + +=item B<-status> + +sends a certificate status request to the server (OCSP stapling). The server +response (if any) is printed out. + +=item B<-nextprotoneg protocols> + +enable Next Protocol Negotiation TLS extension and provide a list of +comma-separated protocol names that the client should advertise +support for. The list should contain most wanted protocols first. +Protocol names are printable ASCII strings, for example "http/1.1" or +"spdy/3". +Empty list of protocols is treated specially and will cause the client to +advertise support for the TLS extension but disconnect just after +receiving ServerHello with a list of server supported protocols. =back @@ -153,9 +359,10 @@ B command for more information. If a connection is established with an SSL server then any data received from the server is displayed and any key presses will be sent to the -server. If the line begins with an B then the session will be -renegotiated. If the line begins with a B the connection will be closed -down. +server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> +have been given), the session will be renegotiated if the line begins with an +B, and if the line begins with a B or if end of file is reached, the +connection will be closed down. =head1 NOTES @@ -168,8 +375,8 @@ would typically be used (https uses port 443). If the connection succeeds 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 +nothing obvious like no client certificate then the B<-bugs>, +B<-ssl3>, B<-tls1>, 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 submitting a bug report to an OpenSSL mailing list. @@ -180,7 +387,7 @@ the clients certificate authority in its "acceptable CA list" when it requests a certificate. By using B 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> @@ -191,6 +398,13 @@ on the command line is no guarantee that the certificate works. If there are problems verifying a server certificate then the B<-showcerts> option can be used to show the whole chain. +The B utility is a test tool and is designed to continue the +handshake after any certificate verification errors. As a result it will +accept any certificate chain (trusted or not) sent by the peer. None test +applications should B do this as it makes them vulnerable to a MITM +attack. This behaviour can be changed by with the B<-verify_return_error> +option: any verify errors are then returned aborting the handshake. + =head1 BUGS Because this program has a lot of options and also because some of @@ -198,14 +412,15 @@ the techniques used are rather old, the C source of s_client is rather hard to read and not a model of how things should be done. A typical SSL client program would be much simpler. -The B<-verify> option should really exit if the server verification -fails. - The B<-prexit> option is a bit of a hack. We should really report information whenever a session is renegotiated. =head1 SEE ALSO -sess_id(1), s_server(1), ciphers(1) +L, L, L + +=head1 HISTORY + +The -no_alt_chains options was first added to OpenSSL 1.1.0. =cut