-
=pod
=head1 NAME
=head1 SYNOPSIS
B<openssl> B<s_client>
-[B<-connect> host:port>]
+[B<-help>]
+[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<-no-CAfile>]
+[B<-no-CApath>]
+[B<-dane_tlsa_domain domain>]
+[B<-dane_tlsa_rrdata rrdata>]
+[B<-dane_ee_no_namechecks>]
+[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<-no_check_time>]
+[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<-auth_level num>]
+[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>]
[B<-crlf>]
[B<-ign_eof>]
+[B<-no_ign_eof>]
[B<-quiet>]
-[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
-[B<-no_ssl2>]
+[B<-tls1_1>]
+[B<-tls1_2>]
[B<-no_ssl3>]
[B<-no_tls1>]
+[B<-no_tls1_1>]
+[B<-no_tls1_2>]
+[B<-dtls>]
+[B<-dtls1>]
+[B<-dtls1_2>]
+[B<-fallback_scsv>]
+[B<-async>]
+[B<-split_send_frag>]
+[B<-max_pipelines>]
+[B<-read_buf>]
[B<-bugs>]
+[B<-comp>]
+[B<-no_comp>]
[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>]
+[B<-ct|noct>]
+[B<-ctlogfile>]
=head1 DESCRIPTION
=head1 OPTIONS
+In addition to the options below the B<s_client> utility also supports the
+common and client only options documented in the
+in the L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)/SUPPORTED COMMAND LINE COMMANDS>
+manual page.
+
=over 4
+=item B<-help>
+
+Print out a usage message.
+
=item B<-connect host:port>
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<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
+
=item B<-verify depth>
The verify depth to use. This specifies the maximum length of the
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
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-dane_tlsa_domain domain>
+
+Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
+TLSA base domain which becomes the default SNI hint and the primary
+reference identifier for hostname checks. This must be used in
+combination with at least one instance of the B<-dane_tlsa_rrdata>
+option below.
+
+When DANE authentication succeeds, the diagnostic output will include
+the lowest (closest to 0) depth at which a TLSA record authenticated
+a chain certificate. When that TLSA record is a "2 1 0" trust
+anchor public key that signed (rather than matched) the top-most
+certificate of the chain, the result is reported as "TA public key
+verified". Otherwise, either the TLSA record "matched TA certificate"
+at a positive depth or else "matched EE certificate" at depth 0.
+
+=item B<-dane_tlsa_rrdata rrdata>
+
+Use one or more times to specify the RRDATA fields of the DANE TLSA
+RRset associated with the target service. The B<rrdata> value is
+specied in "presentation form", that is four whitespace separated
+fields that specify the usage, selector, matching type and associated
+data, with the last of these encoded in hexadecimal. Optional
+whitespace is ignored in the associated data field. For example:
+
+ $ openssl s_client -brief -starttls smtp \
+ -connect smtp.example.com:25 \
+ -dane_tlsa_domain smtp.example.com \
+ -dane_tlsa_rrdata "2 1 1
+ B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
+ -dane_tlsa_rrdata "2 1 1
+ 60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
+ ...
+ Verification: OK
+ Verified peername: smtp.example.com
+ DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1
+ ...
+
+=item B<-dane_ee_no_namechecks>
+
+This disables server name checks when authenticating via DANE-EE(3) TLSA
+records.
+For some applications, primarily web browsers, it is not safe to disable name
+checks due to "unknown key share" attacks, in which a malicious server can
+convince a client that a connection to a victim server is instead a secure
+connection to the malicious server.
+The malicious server may then be able to violate cross-origin scripting
+restrictions.
+Thus, despite the text of RFC7671, name checks are by default enabled for
+DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
+to do so.
+In particular, SMTP and XMPP clients should set this option as SRV and MX
+records already make it possible for a remote domain to redirect client
+connections to any server of its choice, and in any case SMTP and XMPP clients
+do not execute scripts downloaded from remote servers.
+
+=item B<-attime>, 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<-no_alt_chains>, B<-no_check_time>, 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<-use_deltas>,
+B<-auth_level>, 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
be used as a test that session caching is working.
-=item B<-pause>
-
-pauses 1 second between each read and write call.
-
=item B<-showcerts>
display the whole server certificate chain: normally only the server
show all protocol messages with hex dump.
+=item B<-trace>
+
+show verbose trace output of protocol messages. OpenSSL needs to be compiled
+with B<enable-ssl-trace> 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
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<identity> when using a PSK cipher suite.
+
+=item B<-psk key>
+
+Use the PSK key B<key> 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<-tls1_1>, B<-tls1_2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
+
+These options require or disable the use of the specified SSL or TLS protocols.
+By default B<s_client> will negotiate the highest mutually supported protocol
+version.
+When a specific TLS version is required, only that version will be offered to
+and accepted from the server.
+
+=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
+
+These options make B<s_client> use DTLS protocols instead of TLS.
+With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version,
+whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2
+respectively.
+
+=item B<-fallback_scsv>
+
+Send TLS_FALLBACK_SCSV in the ClientHello.
+
+=item B<-async>
+
+switch on asynchronous mode. Cryptographic operations will be performed
+asynchronously. This will only have an effect if an asynchronous capable engine
+is also used via the B<-engine> option. For test purposes the dummy async engine
+(dasync) can be used (if available).
+
+=item B<-split_send_frag int>
-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 size used to split data for encrypt pipelines. If more data is written in
+one go than this value then it will be split into multiple pipelines, up to the
+maximum number of pipelines defined by max_pipelines. This only has an effect if
+a suitable ciphersuite has been negotiated, an engine that supports pipelining
+has been loaded, and max_pipelines is greater than 1. See
+L<SSL_CTX_set_split_send_fragment(3)> for further information.
-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<-no_tls> option others will only
-support SSL v2 and may need the B<-ssl2> option.
+=item B<-max_pipelines int>
+
+The maximum number of encrypt/decrypt pipelines to be used. This will only have
+an effect if an engine has been loaded that supports pipelining (e.g. the dasync
+engine) and a suitable ciphersuite has been negotiated. The default value is 1.
+See L<SSL_CTX_set_max_pipelines(3)> for further information.
+
+=item B<-read_buf int>
+
+The default read buffer size to be used for connections. This will only have an
+effect if the buffer size is larger than the size that would otherwise be used
+and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
+further information).
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
+=item B<-comp>
+
+Enables support for SSL/TLS compression.
+This option was introduced in OpenSSL 1.1.0.
+TLS compression is not recommended and is off by default as of
+OpenSSL 1.1.0.
+
+=item B<-no_comp>
+
+Disables support for SSL/TLS compression.
+TLS compression is not recommended and is off by default as of
+OpenSSL 1.1.0.
+
+=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. Although
send the protocol-specific message(s) to switch to TLS for communication.
B<protocol> is a keyword for the intended protocol. Currently, the only
-supported keywords are "smtp" and "pop3".
+supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
+and "irc."
+
+=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<filename>
+
+=item B<-sess_in sess.pem>
+
+load SSL session from B<filename>. The client will attempt to resume a
+connection from this session.
=item B<-engine id>
-specifying an engine (by it's unique B<id> string) will cause B<s_client>
+specifying an engine (by its unique B<id> string) will cause B<s_client>
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<RAND_egd(3)|RAND_egd(3)>).
-Multiple files can be specified separated by a OS-dependent character.
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an 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.
+
+=item B<-ct|noct>
+
+Use one of these two options to control whether Certificate Transparency (CT)
+is enabled (B<-ct>) or disabled (B<-noct>).
+If CT is enabled, signed certificate timestamps (SCTs) will be requested from
+the server and reported at handshake completion.
+
+Enabling CT also enables OCSP stapling, as this is one possible delivery method
+for SCTs.
+
+=item B<-ctlogfile>
+
+A file containing a list of known Certificate Transparency logs. See
+L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format.
+
=back
=head1 CONNECTED COMMANDS
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<before> submitting a bug report to an OpenSSL mailing list.
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>
If there are problems verifying a server certificate then the
B<-showcerts> option can be used to show the whole chain.
-=head1 BUGS
+The B<s_client> 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<not> 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.
-Because this program has a lot of options and also because some of
-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.
+=head1 BUGS
-The B<-verify> option should really exit if the server verification
-fails.
+Because this program has a lot of options and also because some of the
+techniques used are rather old, the C source of B<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<-prexit> option is a bit of a hack. We should really report
information whenever a session is renegotiated.
=head1 SEE ALSO
-L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
+L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>
+
+=head1 HISTORY
+
+The -no_alt_chains options was first added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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
projects / openssl.git / blobdiff