openssl: Adjust manual pages for 1.0.1h.
[dragonfly.git] / secure / usr.bin / openssl / man / s_client.1
CommitLineData
11c7e1cd 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "S_CLIENT 1"
34240b21 127.TH S_CLIENT 1 "2014-06-05" "1.0.1h" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc 132.SH "NAME"
e3cdf75b 133s_client \- SSL/TLS client program
984263bc 134.SH "SYNOPSIS"
8b0cefbb
JR
135.IX Header "SYNOPSIS"
136\&\fBopenssl\fR \fBs_client\fR
e3cdf75b 137[\fB\-connect host:port\fR]
984263bc 138[\fB\-verify depth\fR]
11c7e1cd 139[\fB\-verify_return_error\fR]
984263bc 140[\fB\-cert filename\fR]
a561f9ff 141[\fB\-certform DER|PEM\fR]
984263bc 142[\fB\-key filename\fR]
a561f9ff
SS
143[\fB\-keyform DER|PEM\fR]
144[\fB\-pass arg\fR]
984263bc
MD
145[\fB\-CApath directory\fR]
146[\fB\-CAfile filename\fR]
147[\fB\-reconnect\fR]
148[\fB\-pause\fR]
149[\fB\-showcerts\fR]
150[\fB\-debug\fR]
151[\fB\-msg\fR]
152[\fB\-nbio_test\fR]
153[\fB\-state\fR]
154[\fB\-nbio\fR]
155[\fB\-crlf\fR]
156[\fB\-ign_eof\fR]
157[\fB\-quiet\fR]
158[\fB\-ssl2\fR]
159[\fB\-ssl3\fR]
160[\fB\-tls1\fR]
161[\fB\-no_ssl2\fR]
162[\fB\-no_ssl3\fR]
163[\fB\-no_tls1\fR]
164[\fB\-bugs\fR]
165[\fB\-cipher cipherlist\fR]
e3cdf75b 166[\fB\-starttls protocol\fR]
984263bc 167[\fB\-engine id\fR]
2c0715f4
PA
168[\fB\-tlsextdebug\fR]
169[\fB\-no_ticket\fR]
170[\fB\-sess_out filename\fR]
171[\fB\-sess_in filename\fR]
e3cdf75b 172[\fB\-rand file(s)\fR]
984263bc 173.SH "DESCRIPTION"
8b0cefbb
JR
174.IX Header "DESCRIPTION"
175The \fBs_client\fR command implements a generic \s-1SSL/TLS\s0 client which connects
176to a remote host using \s-1SSL/TLS\s0. It is a \fIvery\fR useful diagnostic tool for
177\&\s-1SSL\s0 servers.
984263bc 178.SH "OPTIONS"
8b0cefbb
JR
179.IX Header "OPTIONS"
180.IP "\fB\-connect host:port\fR" 4
181.IX Item "-connect host:port"
984263bc
MD
182This specifies the host and optional port to connect to. If not specified
183then an attempt is made to connect to the local host on port 4433.
8b0cefbb
JR
184.IP "\fB\-cert certname\fR" 4
185.IX Item "-cert certname"
984263bc
MD
186The certificate to use, if one is requested by the server. The default is
187not to use a certificate.
a561f9ff
SS
188.IP "\fB\-certform format\fR" 4
189.IX Item "-certform format"
190The certificate format to use: \s-1DER\s0 or \s-1PEM\s0. \s-1PEM\s0 is the default.
8b0cefbb
JR
191.IP "\fB\-key keyfile\fR" 4
192.IX Item "-key keyfile"
984263bc
MD
193The private key to use. If not specified then the certificate file will
194be used.
a561f9ff
SS
195.IP "\fB\-keyform format\fR" 4
196.IX Item "-keyform format"
197The private format to use: \s-1DER\s0 or \s-1PEM\s0. \s-1PEM\s0 is the default.
198.IP "\fB\-pass arg\fR" 4
199.IX Item "-pass arg"
200the private key password source. For more information about the format of \fBarg\fR
201see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
8b0cefbb
JR
202.IP "\fB\-verify depth\fR" 4
203.IX Item "-verify depth"
984263bc
MD
204The verify depth to use. This specifies the maximum length of the
205server certificate chain and turns on server certificate verification.
206Currently the verify operation continues after errors so all the problems
207with a certificate chain can be seen. As a side effect the connection
208will never fail due to a server certificate verify failure.
11c7e1cd
PA
209.IP "\fB\-verify_return_error\fR" 4
210.IX Item "-verify_return_error"
211Return verification errors instead of continuing. This will typically
212abort the handshake with a fatal error.
8b0cefbb
JR
213.IP "\fB\-CApath directory\fR" 4
214.IX Item "-CApath directory"
984263bc
MD
215The directory to use for server certificate verification. This directory
216must be in \*(L"hash format\*(R", see \fBverify\fR for more information. These are
217also used when building the client certificate chain.
8b0cefbb
JR
218.IP "\fB\-CAfile file\fR" 4
219.IX Item "-CAfile file"
984263bc
MD
220A file containing trusted certificates to use during server authentication
221and to use when attempting to build the client certificate chain.
01185282
PA
222.IP "\fB\-purpose, \-ignore_critical, \-issuer_checks, \-crl_check, \-crl_check_all, \-policy_check, \-extended_crl, \-x509_strict, \-policy \-check_ss_sig\fR" 4
223.IX Item "-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig"
224Set various certificate chain valiadition option. See the
225\&\fBverify\fR manual page for details.
8b0cefbb
JR
226.IP "\fB\-reconnect\fR" 4
227.IX Item "-reconnect"
984263bc
MD
228reconnects to the same server 5 times using the same session \s-1ID\s0, this can
229be used as a test that session caching is working.
8b0cefbb
JR
230.IP "\fB\-pause\fR" 4
231.IX Item "-pause"
984263bc 232pauses 1 second between each read and write call.
8b0cefbb
JR
233.IP "\fB\-showcerts\fR" 4
234.IX Item "-showcerts"
984263bc
MD
235display the whole server certificate chain: normally only the server
236certificate itself is displayed.
8b0cefbb
JR
237.IP "\fB\-prexit\fR" 4
238.IX Item "-prexit"
984263bc
MD
239print session information when the program exits. This will always attempt
240to print out information even if the connection fails. Normally information
241will only be printed out once if the connection succeeds. This option is useful
242because the cipher in use may be renegotiated or the connection may fail
243because a client certificate is required or is requested only after an
244attempt is made to access a certain \s-1URL\s0. Note: the output produced by this
245option is not always accurate because a connection might never have been
246established.
8b0cefbb
JR
247.IP "\fB\-state\fR" 4
248.IX Item "-state"
984263bc 249prints out the \s-1SSL\s0 session states.
8b0cefbb
JR
250.IP "\fB\-debug\fR" 4
251.IX Item "-debug"
984263bc 252print extensive debugging information including a hex dump of all traffic.
8b0cefbb
JR
253.IP "\fB\-msg\fR" 4
254.IX Item "-msg"
984263bc 255show all protocol messages with hex dump.
8b0cefbb
JR
256.IP "\fB\-nbio_test\fR" 4
257.IX Item "-nbio_test"
984263bc 258tests non-blocking I/O
8b0cefbb
JR
259.IP "\fB\-nbio\fR" 4
260.IX Item "-nbio"
984263bc 261turns on non-blocking I/O
8b0cefbb
JR
262.IP "\fB\-crlf\fR" 4
263.IX Item "-crlf"
984263bc
MD
264this option translated a line feed from the terminal into \s-1CR+LF\s0 as required
265by some servers.
8b0cefbb
JR
266.IP "\fB\-ign_eof\fR" 4
267.IX Item "-ign_eof"
984263bc
MD
268inhibit shutting down the connection when end of file is reached in the
269input.
8b0cefbb
JR
270.IP "\fB\-quiet\fR" 4
271.IX Item "-quiet"
984263bc
MD
272inhibit printing of session and certificate information. This implicitly
273turns on \fB\-ign_eof\fR as well.
01185282
PA
274.IP "\fB\-psk_identity identity\fR" 4
275.IX Item "-psk_identity identity"
276Use the \s-1PSK\s0 identity \fBidentity\fR when using a \s-1PSK\s0 cipher suite.
277.IP "\fB\-psk key\fR" 4
278.IX Item "-psk key"
279Use the \s-1PSK\s0 key \fBkey\fR when using a \s-1PSK\s0 cipher suite. The key is
280given as a hexadecimal number without leading 0x, for example \-psk
2811a2b3c4d.
8b0cefbb
JR
282.IP "\fB\-ssl2\fR, \fB\-ssl3\fR, \fB\-tls1\fR, \fB\-no_ssl2\fR, \fB\-no_ssl3\fR, \fB\-no_tls1\fR" 4
283.IX Item "-ssl2, -ssl3, -tls1, -no_ssl2, -no_ssl3, -no_tls1"
984263bc
MD
284these options disable the use of certain \s-1SSL\s0 or \s-1TLS\s0 protocols. By default
285the initial handshake uses a method which should be compatible with all
286servers and permit them to use \s-1SSL\s0 v3, \s-1SSL\s0 v2 or \s-1TLS\s0 as appropriate.
287.Sp
288Unfortunately there are a lot of ancient and broken servers in use which
289cannot handle this technique and will fail to connect. Some servers only
290work if \s-1TLS\s0 is turned off with the \fB\-no_tls\fR option others will only
291support \s-1SSL\s0 v2 and may need the \fB\-ssl2\fR option.
8b0cefbb
JR
292.IP "\fB\-bugs\fR" 4
293.IX Item "-bugs"
984263bc
MD
294there are several known bug in \s-1SSL\s0 and \s-1TLS\s0 implementations. Adding this
295option enables various workarounds.
8b0cefbb
JR
296.IP "\fB\-cipher cipherlist\fR" 4
297.IX Item "-cipher cipherlist"
984263bc
MD
298this allows the cipher list sent by the client to be modified. Although
299the server determines which cipher suite is used it should take the first
300supported cipher in the list sent by the client. See the \fBciphers\fR
301command for more information.
8b0cefbb
JR
302.IP "\fB\-starttls protocol\fR" 4
303.IX Item "-starttls protocol"
304send the protocol-specific message(s) to switch to \s-1TLS\s0 for communication.
305\&\fBprotocol\fR is a keyword for the intended protocol. Currently, the only
edae4a78 306supported keywords are \*(L"smtp\*(R", \*(L"pop3\*(R", \*(L"imap\*(R", and \*(L"ftp\*(R".
2c0715f4
PA
307.IP "\fB\-tlsextdebug\fR" 4
308.IX Item "-tlsextdebug"
01185282 309print out a hex dump of any \s-1TLS\s0 extensions received from the server.
2c0715f4
PA
310.IP "\fB\-no_ticket\fR" 4
311.IX Item "-no_ticket"
01185282 312disable RFC4507bis session ticket support.
2c0715f4
PA
313.IP "\fB\-sess_out filename\fR" 4
314.IX Item "-sess_out filename"
315output \s-1SSL\s0 session to \fBfilename\fR
316.IP "\fB\-sess_in sess.pem\fR" 4
317.IX Item "-sess_in sess.pem"
318load \s-1SSL\s0 session from \fBfilename\fR. The client will attempt to resume a
319connection from this session.
8b0cefbb
JR
320.IP "\fB\-engine id\fR" 4
321.IX Item "-engine id"
01185282 322specifying an engine (by its unique \fBid\fR string) will cause \fBs_client\fR
984263bc
MD
323to attempt to obtain a functional reference to the specified engine,
324thus initialising it if needed. The engine will then be set as the default
325for all available algorithms.
8b0cefbb
JR
326.IP "\fB\-rand file(s)\fR" 4
327.IX Item "-rand file(s)"
984263bc 328a file or files containing random data used to seed the random number
8b0cefbb
JR
329generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)).
330Multiple files can be specified separated by a OS-dependent character.
e257b235 331The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for
984263bc
MD
332all others.
333.SH "CONNECTED COMMANDS"
8b0cefbb
JR
334.IX Header "CONNECTED COMMANDS"
335If a connection is established with an \s-1SSL\s0 server then any data received
984263bc
MD
336from the server is displayed and any key presses will be sent to the
337server. When used interactively (which means neither \fB\-quiet\fR nor \fB\-ign_eof\fR
338have been given), the session will be renegotiated if the line begins with an
8b0cefbb 339\&\fBR\fR, and if the line begins with a \fBQ\fR or if end of file is reached, the
984263bc
MD
340connection will be closed down.
341.SH "NOTES"
8b0cefbb
JR
342.IX Header "NOTES"
343\&\fBs_client\fR can be used to debug \s-1SSL\s0 servers. To connect to an \s-1SSL\s0 \s-1HTTP\s0
984263bc
MD
344server the command:
345.PP
346.Vb 1
e257b235 347\& openssl s_client \-connect servername:443
984263bc 348.Ve
8b0cefbb 349.PP
984263bc 350would typically be used (https uses port 443). If the connection succeeds
8b0cefbb 351then an \s-1HTTP\s0 command can be given such as \*(L"\s-1GET\s0 /\*(R" to retrieve a web page.
984263bc
MD
352.PP
353If the handshake fails then there are several possible causes, if it is
354nothing obvious like no client certificate then the \fB\-bugs\fR, \fB\-ssl2\fR,
8b0cefbb 355\&\fB\-ssl3\fR, \fB\-tls1\fR, \fB\-no_ssl2\fR, \fB\-no_ssl3\fR, \fB\-no_tls1\fR options can be tried
984263bc
MD
356in case it is a buggy server. In particular you should play with these
357options \fBbefore\fR submitting a bug report to an OpenSSL mailing list.
358.PP
359A frequent problem when attempting to get client certificates working
360is that a web client complains it has no certificates or gives an empty
361list to choose from. This is normally because the server is not sending
8b0cefbb
JR
362the clients certificate authority in its \*(L"acceptable \s-1CA\s0 list\*(R" when it
363requests a certificate. By using \fBs_client\fR the \s-1CA\s0 list can be viewed
984263bc 364and checked. However some servers only request client authentication
8b0cefbb
JR
365after a specific \s-1URL\s0 is requested. To obtain the list in this case it
366is necessary to use the \fB\-prexit\fR option and send an \s-1HTTP\s0 request
984263bc
MD
367for an appropriate page.
368.PP
369If a certificate is specified on the command line using the \fB\-cert\fR
370option it will not be used unless the server specifically requests
371a client certificate. Therefor merely including a client certificate
372on the command line is no guarantee that the certificate works.
373.PP
374If there are problems verifying a server certificate then the
8b0cefbb 375\&\fB\-showcerts\fR option can be used to show the whole chain.
2c0715f4
PA
376.PP
377Since the SSLv23 client hello cannot include compression methods or extensions
378these will only be supported if its use is disabled, for example by using the
379\&\fB\-no_sslv2\fR option.
11c7e1cd
PA
380.PP
381The \fBs_client\fR utility is a test tool and is designed to continue the
382handshake after any certificate verification errors. As a result it will
383accept any certificate chain (trusted or not) sent by the peer. None test
384applications should \fBnot\fR do this as it makes them vulnerable to a \s-1MITM\s0
385attack. This behaviour can be changed by with the \fB\-verify_return_error\fR
386option: any verify errors are then returned aborting the handshake.
984263bc 387.SH "BUGS"
8b0cefbb 388.IX Header "BUGS"
984263bc
MD
389Because this program has a lot of options and also because some of
390the techniques used are rather old, the C source of s_client is rather
391hard to read and not a model of how things should be done. A typical
8b0cefbb 392\&\s-1SSL\s0 client program would be much simpler.
984263bc 393.PP
984263bc
MD
394The \fB\-prexit\fR option is a bit of a hack. We should really report
395information whenever a session is renegotiated.
396.SH "SEE ALSO"
e3cdf75b 397.IX Header "SEE ALSO"
8b0cefbb 398\&\fIsess_id\fR\|(1), \fIs_server\fR\|(1), \fIciphers\fR\|(1)