X-Git-Url: https://code.wpia.club/?a=blobdiff_plain;f=lib%2Fopenssl%2Fdoc%2Fapps%2Fs_client.pod;fp=lib%2Fopenssl%2Fdoc%2Fapps%2Fs_client.pod;h=7ad981111890f30902eb27ba863fdeb8bdc18e93;hb=02ed66432c92de70694700164f986190aad3cbc5;hp=b021c730c02ac70752a017be1f24baf722f8a25b;hpb=89016837dcbf2775cd15dc8cbaba00dc6379f86e;p=cassiopeia.git diff --git a/lib/openssl/doc/apps/s_client.pod b/lib/openssl/doc/apps/s_client.pod index b021c73..7ad9811 100644 --- a/lib/openssl/doc/apps/s_client.pod +++ b/lib/openssl/doc/apps/s_client.pod @@ -1,4 +1,3 @@ - =pod =head1 NAME @@ -8,7 +7,9 @@ s_client - SSL/TLS client program =head1 SYNOPSIS B B +[B<-help>] [B<-connect host:port>] +[B<-proxy host:port>] [B<-servername name>] [B<-verify depth>] [B<-verify_return_error>] @@ -19,8 +20,40 @@ B B [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>] @@ -31,24 +64,41 @@ B B [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<-alpn protocols>] [B<-nextprotoneg protocols>] +[B<-ct|noct>] +[B<-ctlogfile>] =head1 DESCRIPTION @@ -58,13 +108,28 @@ 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 "Supported Command Line Commands" section of the L +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. @@ -90,7 +155,7 @@ 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. +see the B section in L. =item B<-verify depth> @@ -116,20 +181,86 @@ 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<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig> - -Set various certificate chain valiadition option. See the -L|verify(1)> manual page for details. +=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 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 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 @@ -158,6 +289,15 @@ print extensive debugging information including a hex dump of all traffic. 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 @@ -196,22 +336,78 @@ 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<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> +=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 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 use DTLS protocols instead of TLS. +With B<-dtls>, B 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> + +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 for further information. + +=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 for further information. -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. +=item B<-read_buf int> -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. +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 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 @@ -219,15 +415,19 @@ 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<-serverpref> - -use the server's cipher preferences; only used for SSLV2. - =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", and "ftp". +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> @@ -235,7 +435,7 @@ print out a hex dump of any TLS extensions received from the server. =item B<-no_ticket> -disable RFC4507bis session ticket support. +disable RFC4507bis session ticket support. =item B<-sess_out filename> @@ -256,26 +456,52 @@ 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. +generator, or an EGD socket (see L). +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> +=item B<-alpn protocols>, B<-nextprotoneg protocols> -enable Next Protocol Negotiation TLS extension and provide a list of +these flags enable the +Enable the Application-Layer Protocol Negotiation or Next Protocol +Negotiation extension, respectively. ALPN is the IETF standard and +replaces NPN. +The B list is a 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 -reciving ServerHello with a list of server supported protocols. +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 for the expected file format. =back @@ -299,8 +525,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> options 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. @@ -322,10 +548,6 @@ 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. -Since the SSLv23 client hello cannot include compression methods or extensions -these will only be supported if its use is disabled, for example by using the -B<-no_sslv2> option. - 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 @@ -335,16 +557,30 @@ 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 -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. +Because this program has a lot of options and also because some of the +techniques used are rather old, the C source of B 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, L, L +L, +L, L, L + +=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. =cut