diff options
Diffstat (limited to 'secure/usr.bin/openssl/man/s_client.1')
| -rw-r--r-- | secure/usr.bin/openssl/man/s_client.1 | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/secure/usr.bin/openssl/man/s_client.1 b/secure/usr.bin/openssl/man/s_client.1 new file mode 100644 index 0000000..bfed887 --- /dev/null +++ b/secure/usr.bin/openssl/man/s_client.1 @@ -0,0 +1,452 @@ +.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{ +. if \nF \{ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "S_CLIENT 1" +.TH S_CLIENT 1 "2015-12-03" "1.0.2e" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +s_client \- SSL/TLS client program +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBopenssl\fR \fBs_client\fR +[\fB\-connect host:port\fR] +[\fB\-servername name\fR] +[\fB\-verify depth\fR] +[\fB\-verify_return_error\fR] +[\fB\-cert filename\fR] +[\fB\-certform DER|PEM\fR] +[\fB\-key filename\fR] +[\fB\-keyform DER|PEM\fR] +[\fB\-pass arg\fR] +[\fB\-CApath directory\fR] +[\fB\-CAfile filename\fR] +[\fB\-no_alt_chains\fR] +[\fB\-reconnect\fR] +[\fB\-pause\fR] +[\fB\-showcerts\fR] +[\fB\-debug\fR] +[\fB\-msg\fR] +[\fB\-nbio_test\fR] +[\fB\-state\fR] +[\fB\-nbio\fR] +[\fB\-crlf\fR] +[\fB\-ign_eof\fR] +[\fB\-no_ign_eof\fR] +[\fB\-quiet\fR] +[\fB\-ssl2\fR] +[\fB\-ssl3\fR] +[\fB\-tls1\fR] +[\fB\-no_ssl2\fR] +[\fB\-no_ssl3\fR] +[\fB\-no_tls1\fR] +[\fB\-no_tls1_1\fR] +[\fB\-no_tls1_2\fR] +[\fB\-fallback_scsv\fR] +[\fB\-bugs\fR] +[\fB\-cipher cipherlist\fR] +[\fB\-serverpref\fR] +[\fB\-starttls protocol\fR] +[\fB\-engine id\fR] +[\fB\-tlsextdebug\fR] +[\fB\-no_ticket\fR] +[\fB\-sess_out filename\fR] +[\fB\-sess_in filename\fR] +[\fB\-rand file(s)\fR] +[\fB\-serverinfo types\fR] +[\fB\-status\fR] +[\fB\-nextprotoneg protocols\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBs_client\fR command implements a generic \s-1SSL/TLS\s0 client which connects +to a remote host using \s-1SSL/TLS.\s0 It is a \fIvery\fR useful diagnostic tool for +\&\s-1SSL\s0 servers. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-connect host:port\fR" 4 +.IX Item "-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. +.IP "\fB\-servername name\fR" 4 +.IX Item "-servername name" +Set the \s-1TLS SNI \s0(Server Name Indication) extension in the ClientHello message. +.IP "\fB\-cert certname\fR" 4 +.IX Item "-cert certname" +The certificate to use, if one is requested by the server. The default is +not to use a certificate. +.IP "\fB\-certform format\fR" 4 +.IX Item "-certform format" +The certificate format to use: \s-1DER\s0 or \s-1PEM. PEM\s0 is the default. +.IP "\fB\-key keyfile\fR" 4 +.IX Item "-key keyfile" +The private key to use. If not specified then the certificate file will +be used. +.IP "\fB\-keyform format\fR" 4 +.IX Item "-keyform format" +The private format to use: \s-1DER\s0 or \s-1PEM. PEM\s0 is the default. +.IP "\fB\-pass arg\fR" 4 +.IX Item "-pass arg" +the private key password source. For more information about the format of \fBarg\fR +see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1). +.IP "\fB\-verify depth\fR" 4 +.IX Item "-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. +.IP "\fB\-verify_return_error\fR" 4 +.IX Item "-verify_return_error" +Return verification errors instead of continuing. This will typically +abort the handshake with a fatal error. +.IP "\fB\-CApath directory\fR" 4 +.IX Item "-CApath directory" +The directory to use for server certificate verification. This directory +must be in \*(L"hash format\*(R", see \fBverify\fR for more information. These are +also used when building the client certificate chain. +.IP "\fB\-CAfile file\fR" 4 +.IX Item "-CAfile file" +A file containing trusted certificates to use during server authentication +and to use when attempting to build the client certificate chain. +.IP "\fB\-purpose, \-ignore_critical, \-issuer_checks, \-crl_check, \-crl_check_all, \-policy_check, \-extended_crl, \-x509_strict, \-policy \-check_ss_sig \-no_alt_chains\fR" 4 +.IX Item "-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains" +Set various certificate chain valiadition option. See the +\&\fBverify\fR manual page for details. +.IP "\fB\-reconnect\fR" 4 +.IX Item "-reconnect" +reconnects to the same server 5 times using the same session \s-1ID,\s0 this can +be used as a test that session caching is working. +.IP "\fB\-pause\fR" 4 +.IX Item "-pause" +pauses 1 second between each read and write call. +.IP "\fB\-showcerts\fR" 4 +.IX Item "-showcerts" +display the whole server certificate chain: normally only the server +certificate itself is displayed. +.IP "\fB\-prexit\fR" 4 +.IX Item "-prexit" +print session information when the program exits. This will always attempt +to print out information even if the connection fails. Normally information +will only be printed out once if the connection succeeds. This option is useful +because the cipher in use may be renegotiated or the connection may fail +because a client certificate is required or is requested only after an +attempt is made to access a certain \s-1URL.\s0 Note: the output produced by this +option is not always accurate because a connection might never have been +established. +.IP "\fB\-state\fR" 4 +.IX Item "-state" +prints out the \s-1SSL\s0 session states. +.IP "\fB\-debug\fR" 4 +.IX Item "-debug" +print extensive debugging information including a hex dump of all traffic. +.IP "\fB\-msg\fR" 4 +.IX Item "-msg" +show all protocol messages with hex dump. +.IP "\fB\-nbio_test\fR" 4 +.IX Item "-nbio_test" +tests non-blocking I/O +.IP "\fB\-nbio\fR" 4 +.IX Item "-nbio" +turns on non-blocking I/O +.IP "\fB\-crlf\fR" 4 +.IX Item "-crlf" +this option translated a line feed from the terminal into \s-1CR+LF\s0 as required +by some servers. +.IP "\fB\-ign_eof\fR" 4 +.IX Item "-ign_eof" +inhibit shutting down the connection when end of file is reached in the +input. +.IP "\fB\-quiet\fR" 4 +.IX Item "-quiet" +inhibit printing of session and certificate information. This implicitly +turns on \fB\-ign_eof\fR as well. +.IP "\fB\-no_ign_eof\fR" 4 +.IX Item "-no_ign_eof" +shut down the connection when end of file is reached in the input. +Can be used to override the implicit \fB\-ign_eof\fR after \fB\-quiet\fR. +.IP "\fB\-psk_identity identity\fR" 4 +.IX Item "-psk_identity identity" +Use the \s-1PSK\s0 identity \fBidentity\fR when using a \s-1PSK\s0 cipher suite. +.IP "\fB\-psk key\fR" 4 +.IX Item "-psk key" +Use the \s-1PSK\s0 key \fBkey\fR when using a \s-1PSK\s0 cipher suite. The key is +given as a hexadecimal number without leading 0x, for example \-psk +1a2b3c4d. +.IP "\fB\-ssl2\fR, \fB\-ssl3\fR, \fB\-tls1\fR, \fB\-no_ssl2\fR, \fB\-no_ssl3\fR, \fB\-no_tls1\fR, \fB\-no_tls1_1\fR, \fB\-no_tls1_2\fR" 4 +.IX Item "-ssl2, -ssl3, -tls1, -no_ssl2, -no_ssl3, -no_tls1, -no_tls1_1, -no_tls1_2" +these options disable the use of certain \s-1SSL\s0 or \s-1TLS\s0 protocols. By default +the initial handshake uses a method which should be compatible with all +servers and permit them to use \s-1SSL\s0 v3, \s-1SSL\s0 v2 or \s-1TLS\s0 as appropriate. +.Sp +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 \s-1TLS\s0 is turned off. +.IP "\fB\-fallback_scsv\fR" 4 +.IX Item "-fallback_scsv" +Send \s-1TLS_FALLBACK_SCSV\s0 in the ClientHello. +.IP "\fB\-bugs\fR" 4 +.IX Item "-bugs" +there are several known bug in \s-1SSL\s0 and \s-1TLS\s0 implementations. Adding this +option enables various workarounds. +.IP "\fB\-cipher cipherlist\fR" 4 +.IX Item "-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 \fBciphers\fR +command for more information. +.IP "\fB\-serverpref\fR" 4 +.IX Item "-serverpref" +use the server's cipher preferences; only used for \s-1SSLV2.\s0 +.IP "\fB\-starttls protocol\fR" 4 +.IX Item "-starttls protocol" +send the protocol-specific message(s) to switch to \s-1TLS\s0 for communication. +\&\fBprotocol\fR is a keyword for the intended protocol. Currently, the only +supported keywords are \*(L"smtp\*(R", \*(L"pop3\*(R", \*(L"imap\*(R", and \*(L"ftp\*(R". +.IP "\fB\-tlsextdebug\fR" 4 +.IX Item "-tlsextdebug" +print out a hex dump of any \s-1TLS\s0 extensions received from the server. +.IP "\fB\-no_ticket\fR" 4 +.IX Item "-no_ticket" +disable RFC4507bis session ticket support. +.IP "\fB\-sess_out filename\fR" 4 +.IX Item "-sess_out filename" +output \s-1SSL\s0 session to \fBfilename\fR +.IP "\fB\-sess_in sess.pem\fR" 4 +.IX Item "-sess_in sess.pem" +load \s-1SSL\s0 session from \fBfilename\fR. The client will attempt to resume a +connection from this session. +.IP "\fB\-engine id\fR" 4 +.IX Item "-engine id" +specifying an engine (by its unique \fBid\fR string) will cause \fBs_client\fR +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. +.IP "\fB\-rand file(s)\fR" 4 +.IX Item "-rand file(s)" +a file or files containing random data used to seed the random number +generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)). +Multiple files can be specified separated by a OS-dependent character. +The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for +all others. +.IP "\fB\-serverinfo types\fR" 4 +.IX Item "-serverinfo types" +a list of comma-separated \s-1TLS\s0 Extension Types (numbers between 0 and +65535). Each type will be sent as an empty ClientHello \s-1TLS\s0 Extension. +The server's response (if any) will be encoded and displayed as a \s-1PEM\s0 +file. +.IP "\fB\-status\fR" 4 +.IX Item "-status" +sends a certificate status request to the server (\s-1OCSP\s0 stapling). The server +response (if any) is printed out. +.IP "\fB\-nextprotoneg protocols\fR" 4 +.IX Item "-nextprotoneg protocols" +enable Next Protocol Negotiation \s-1TLS\s0 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 \s-1ASCII\s0 strings, for example \*(L"http/1.1\*(R" or +\&\*(L"spdy/3\*(R". +Empty list of protocols is treated specially and will cause the client to +advertise support for the \s-1TLS\s0 extension but disconnect just after +reciving ServerHello with a list of server supported protocols. +.SH "CONNECTED COMMANDS" +.IX Header "CONNECTED COMMANDS" +If a connection is established with an \s-1SSL\s0 server then any data received +from the server is displayed and any key presses will be sent to the +server. When used interactively (which means neither \fB\-quiet\fR nor \fB\-ign_eof\fR +have been given), the session will be renegotiated if the line begins with an +\&\fBR\fR, and if the line begins with a \fBQ\fR or if end of file is reached, the +connection will be closed down. +.SH "NOTES" +.IX Header "NOTES" +\&\fBs_client\fR can be used to debug \s-1SSL\s0 servers. To connect to an \s-1SSL HTTP\s0 +server the command: +.PP +.Vb 1 +\& openssl s_client \-connect servername:443 +.Ve +.PP +would typically be used (https uses port 443). If the connection succeeds +then an \s-1HTTP\s0 command can be given such as \*(L"\s-1GET /\*(R"\s0 to retrieve a web page. +.PP +If the handshake fails then there are several possible causes, if it is +nothing obvious like no client certificate then the \fB\-bugs\fR, \fB\-ssl2\fR, +\&\fB\-ssl3\fR, \fB\-tls1\fR, \fB\-no_ssl2\fR, \fB\-no_ssl3\fR, \fB\-no_tls1\fR options can be tried +in case it is a buggy server. In particular you should play with these +options \fBbefore\fR submitting a bug report to an OpenSSL mailing list. +.PP +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 \*(L"acceptable \s-1CA\s0 list\*(R" when it +requests a certificate. By using \fBs_client\fR the \s-1CA\s0 list can be viewed +and checked. However some servers only request client authentication +after a specific \s-1URL\s0 is requested. To obtain the list in this case it +is necessary to use the \fB\-prexit\fR option and send an \s-1HTTP\s0 request +for an appropriate page. +.PP +If a certificate is specified on the command line using the \fB\-cert\fR +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. +.PP +If there are problems verifying a server certificate then the +\&\fB\-showcerts\fR option can be used to show the whole chain. +.PP +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 +\&\fB\-no_sslv2\fR option. +.PP +The \fBs_client\fR 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 \fBnot\fR do this as it makes them vulnerable to a \s-1MITM\s0 +attack. This behaviour can be changed by with the \fB\-verify_return_error\fR +option: any verify errors are then returned aborting the handshake. +.SH "BUGS" +.IX Header "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 +\&\s-1SSL\s0 client program would be much simpler. +.PP +The \fB\-prexit\fR option is a bit of a hack. We should really report +information whenever a session is renegotiated. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIsess_id\fR\|(1), \fIs_server\fR\|(1), \fIciphers\fR\|(1) +.SH "HISTORY" +.IX Header "HISTORY" +The \-no_alt_chains options was first added to OpenSSL 1.0.2b. |
