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