]>
Commit | Line | Data |
---|---|---|
c3ed3b6e DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
3f2181e6 | 5 | openssl-s_client, |
c3ed3b6e DSH |
6 | s_client - SSL/TLS client program |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<s_client> | |
169394d4 | 11 | [B<-help>] |
a32fc687 | 12 | [B<-connect host:port>] |
552bf8ec | 13 | [B<-proxy host:port>] |
a22f9c84 E |
14 | [B<-unix path>] |
15 | [B<-4>] | |
16 | [B<-6>] | |
fc1d88f0 | 17 | [B<-servername name>] |
11ba87f2 | 18 | [B<-noservername>] |
b46c3e9b | 19 | [B<-verify depth>] |
4e6c12f3 | 20 | [B<-verify_return_error>] |
c3ed3b6e | 21 | [B<-cert filename>] |
826a42a0 | 22 | [B<-certform DER|PEM>] |
c3ed3b6e | 23 | [B<-key filename>] |
826a42a0 DSH |
24 | [B<-keyform DER|PEM>] |
25 | [B<-pass arg>] | |
c3ed3b6e DSH |
26 | [B<-CApath directory>] |
27 | [B<-CAfile filename>] | |
40e2d76b MC |
28 | [B<-no-CAfile>] |
29 | [B<-no-CApath>] | |
5a185729 | 30 | [B<-requestCAfile filename>] |
cddd424a VD |
31 | [B<-dane_tlsa_domain domain>] |
32 | [B<-dane_tlsa_rrdata rrdata>] | |
c4fbed6c | 33 | [B<-dane_ee_no_namechecks>] |
e42d84be HK |
34 | [B<-attime timestamp>] |
35 | [B<-check_ss_sig>] | |
36 | [B<-crl_check>] | |
37 | [B<-crl_check_all>] | |
38 | [B<-explicit_policy>] | |
39 | [B<-extended_crl>] | |
40 | [B<-ignore_critical>] | |
41 | [B<-inhibit_any>] | |
42 | [B<-inhibit_map>] | |
5a1f853b | 43 | [B<-no_check_time>] |
e42d84be HK |
44 | [B<-partial_chain>] |
45 | [B<-policy arg>] | |
46 | [B<-policy_check>] | |
47 | [B<-policy_print>] | |
48 | [B<-purpose purpose>] | |
49 | [B<-suiteB_128>] | |
50 | [B<-suiteB_128_only>] | |
51 | [B<-suiteB_192>] | |
52 | [B<-trusted_first>] | |
fa7b0111 | 53 | [B<-no_alt_chains>] |
e42d84be | 54 | [B<-use_deltas>] |
fbb82a60 | 55 | [B<-auth_level num>] |
a7c04f2b | 56 | [B<-nameopt option>] |
e42d84be HK |
57 | [B<-verify_depth num>] |
58 | [B<-verify_email email>] | |
59 | [B<-verify_hostname hostname>] | |
60 | [B<-verify_ip ip>] | |
61 | [B<-verify_name name>] | |
62 | [B<-x509_strict>] | |
c3ed3b6e | 63 | [B<-reconnect>] |
c3ed3b6e DSH |
64 | [B<-showcerts>] |
65 | [B<-debug>] | |
1d8634b1 | 66 | [B<-msg>] |
c3ed3b6e DSH |
67 | [B<-nbio_test>] |
68 | [B<-state>] | |
69 | [B<-nbio>] | |
70 | [B<-crlf>] | |
ce301b6b | 71 | [B<-ign_eof>] |
fc1d88f0 | 72 | [B<-no_ign_eof>] |
c3ed3b6e | 73 | [B<-quiet>] |
c3ed3b6e DSH |
74 | [B<-ssl3>] |
75 | [B<-tls1>] | |
8c73aeb6 VD |
76 | [B<-tls1_1>] |
77 | [B<-tls1_2>] | |
582a17d6 | 78 | [B<-tls1_3>] |
c3ed3b6e DSH |
79 | [B<-no_ssl3>] |
80 | [B<-no_tls1>] | |
fb0e87fb BM |
81 | [B<-no_tls1_1>] |
82 | [B<-no_tls1_2>] | |
582a17d6 | 83 | [B<-no_tls1_3>] |
8c73aeb6 VD |
84 | [B<-dtls>] |
85 | [B<-dtls1>] | |
86 | [B<-dtls1_2>] | |
19044d3c | 87 | [B<-sctp>] |
fb0e87fb | 88 | [B<-fallback_scsv>] |
bc8857bf | 89 | [B<-async>] |
28e5ea88 | 90 | [B<-max_send_frag>] |
0df80881 MC |
91 | [B<-split_send_frag>] |
92 | [B<-max_pipelines>] | |
93 | [B<-read_buf>] | |
c3ed3b6e | 94 | [B<-bugs>] |
cc5a9ba4 VD |
95 | [B<-comp>] |
96 | [B<-no_comp>] | |
4e2bd9cb | 97 | [B<-allow_no_dhe_kex>] |
254b58fd SC |
98 | [B<-sigalgs sigalglist>] |
99 | [B<-curves curvelist>] | |
c3ed3b6e | 100 | [B<-cipher cipherlist>] |
fc1d88f0 | 101 | [B<-serverpref>] |
e986704d | 102 | [B<-starttls protocol>] |
b98af49d | 103 | [B<-xmpphost hostname>] |
8176431d | 104 | [B<-name hostname>] |
5270e702 | 105 | [B<-engine id>] |
d24a9c8f DSH |
106 | [B<-tlsextdebug>] |
107 | [B<-no_ticket>] | |
108 | [B<-sess_out filename>] | |
109 | [B<-sess_in filename>] | |
3ee1eac2 RS |
110 | [B<-rand file...>] |
111 | [B<-writerand file>] | |
9cd50f73 | 112 | [B<-serverinfo types>] |
cba3f1c7 | 113 | [B<-status>] |
776e15f9 | 114 | [B<-alpn protocols>] |
7efd0e77 | 115 | [B<-nextprotoneg protocols>] |
e75138ab RS |
116 | [B<-ct>] |
117 | [B<-noct>] | |
eb64a6c6 | 118 | [B<-ctlogfile>] |
6437b802 MC |
119 | [B<-keylogfile file>] |
120 | [B<-early_data file>] | |
9d75dce3 | 121 | [B<-force_pha>] |
729ef856 | 122 | [B<target>] |
c3ed3b6e DSH |
123 | |
124 | =head1 DESCRIPTION | |
125 | ||
126 | The B<s_client> command implements a generic SSL/TLS client which connects | |
127 | to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for | |
128 | SSL servers. | |
129 | ||
130 | =head1 OPTIONS | |
131 | ||
765b4137 DSH |
132 | In addition to the options below the B<s_client> utility also supports the |
133 | common and client only options documented in the | |
6f0ac0e2 | 134 | in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)> |
13cfb043 | 135 | manual page. |
765b4137 | 136 | |
c3ed3b6e DSH |
137 | =over 4 |
138 | ||
169394d4 MR |
139 | =item B<-help> |
140 | ||
141 | Print out a usage message. | |
142 | ||
c3ed3b6e DSH |
143 | =item B<-connect host:port> |
144 | ||
729ef856 CB |
145 | This specifies the host and optional port to connect to. It is possible to |
146 | select the host and port using the optional target positional argument instead. | |
147 | If neither this nor the target positonal argument are specified then an attempt | |
148 | is made to connect to the local host on port 4433. | |
c3ed3b6e | 149 | |
552bf8ec MT |
150 | =item B<-proxy host:port> |
151 | ||
152 | When used with the B<-connect> flag, the program uses the host and port | |
153 | specified with this flag and issues an HTTP CONNECT command to connect | |
154 | to the desired server. | |
155 | ||
a22f9c84 E |
156 | =item B<-unix path> |
157 | ||
158 | Connect over the specified Unix-domain socket. | |
159 | ||
160 | =item B<-4> | |
161 | ||
162 | Use IPv4 only. | |
163 | ||
164 | =item B<-6> | |
165 | ||
166 | Use IPv6 only. | |
167 | ||
fc1d88f0 RS |
168 | =item B<-servername name> |
169 | ||
11ba87f2 | 170 | Set the TLS SNI (Server Name Indication) extension in the ClientHello message to |
481afe2a PY |
171 | the given value. If both this option and the B<-noservername> are not given, the |
172 | TLS SNI extension is still set to the hostname provided to the B<-connect> option, | |
173 | or "localhost" if B<-connect> has not been supplied. This is default since OpenSSL | |
174 | 1.1.1. | |
175 | ||
176 | Even though SNI name should normally be a DNS name and not an IP address, this | |
177 | option will not make the distinction when parsing B<-connect> and will send | |
178 | IP address if one passed. | |
11ba87f2 MC |
179 | |
180 | =item B<-noservername> | |
181 | ||
182 | Suppresses sending of the SNI (Server Name Indication) extension in the | |
183 | ClientHello message. Cannot be used in conjunction with the B<-servername> or | |
481afe2a | 184 | <-dane_tlsa_domain> options. |
fc1d88f0 | 185 | |
c3ed3b6e DSH |
186 | =item B<-cert certname> |
187 | ||
188 | The certificate to use, if one is requested by the server. The default is | |
189 | not to use a certificate. | |
190 | ||
826a42a0 DSH |
191 | =item B<-certform format> |
192 | ||
193 | The certificate format to use: DER or PEM. PEM is the default. | |
194 | ||
c3ed3b6e DSH |
195 | =item B<-key keyfile> |
196 | ||
197 | The private key to use. If not specified then the certificate file will | |
198 | be used. | |
199 | ||
826a42a0 DSH |
200 | =item B<-keyform format> |
201 | ||
202 | The private format to use: DER or PEM. PEM is the default. | |
203 | ||
204 | =item B<-pass arg> | |
205 | ||
206 | the private key password source. For more information about the format of B<arg> | |
9b86974e | 207 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. |
826a42a0 | 208 | |
c3ed3b6e DSH |
209 | =item B<-verify depth> |
210 | ||
211 | The verify depth to use. This specifies the maximum length of the | |
212 | server certificate chain and turns on server certificate verification. | |
213 | Currently the verify operation continues after errors so all the problems | |
214 | with a certificate chain can be seen. As a side effect the connection | |
215 | will never fail due to a server certificate verify failure. | |
216 | ||
4e6c12f3 DSH |
217 | =item B<-verify_return_error> |
218 | ||
219 | Return verification errors instead of continuing. This will typically | |
220 | abort the handshake with a fatal error. | |
221 | ||
a7c04f2b DB |
222 | =item B<-nameopt option> |
223 | ||
c4de074e | 224 | Option which determines how the subject or issuer names are displayed. The |
a7c04f2b DB |
225 | B<option> argument can be a single option or multiple options separated by |
226 | commas. Alternatively the B<-nameopt> switch may be used more than once to | |
227 | set multiple options. See the L<x509(1)> manual page for details. | |
228 | ||
c3ed3b6e DSH |
229 | =item B<-CApath directory> |
230 | ||
231 | The directory to use for server certificate verification. This directory | |
232 | must be in "hash format", see B<verify> for more information. These are | |
233 | also used when building the client certificate chain. | |
234 | ||
235 | =item B<-CAfile file> | |
236 | ||
237 | A file containing trusted certificates to use during server authentication | |
238 | and to use when attempting to build the client certificate chain. | |
239 | ||
40e2d76b MC |
240 | =item B<-no-CAfile> |
241 | ||
242 | Do not load the trusted CA certificates from the default file location | |
243 | ||
244 | =item B<-no-CApath> | |
245 | ||
246 | Do not load the trusted CA certificates from the default directory location | |
247 | ||
5a185729 DSH |
248 | =item B<-requestCAfile file> |
249 | ||
250 | A file containing a list of certificates whose subject names will be sent | |
251 | to the server in the B<certificate_authorities> extension. Only supported | |
252 | for TLS 1.3 | |
253 | ||
cddd424a VD |
254 | =item B<-dane_tlsa_domain domain> |
255 | ||
256 | Enable RFC6698/RFC7671 DANE TLSA authentication and specify the | |
257 | TLSA base domain which becomes the default SNI hint and the primary | |
258 | reference identifier for hostname checks. This must be used in | |
259 | combination with at least one instance of the B<-dane_tlsa_rrdata> | |
260 | option below. | |
261 | ||
262 | When DANE authentication succeeds, the diagnostic output will include | |
263 | the lowest (closest to 0) depth at which a TLSA record authenticated | |
264 | a chain certificate. When that TLSA record is a "2 1 0" trust | |
265 | anchor public key that signed (rather than matched) the top-most | |
266 | certificate of the chain, the result is reported as "TA public key | |
267 | verified". Otherwise, either the TLSA record "matched TA certificate" | |
268 | at a positive depth or else "matched EE certificate" at depth 0. | |
269 | ||
270 | =item B<-dane_tlsa_rrdata rrdata> | |
271 | ||
272 | Use one or more times to specify the RRDATA fields of the DANE TLSA | |
273 | RRset associated with the target service. The B<rrdata> value is | |
274 | specied in "presentation form", that is four whitespace separated | |
275 | fields that specify the usage, selector, matching type and associated | |
276 | data, with the last of these encoded in hexadecimal. Optional | |
277 | whitespace is ignored in the associated data field. For example: | |
278 | ||
c0a445a9 VD |
279 | $ openssl s_client -brief -starttls smtp \ |
280 | -connect smtp.example.com:25 \ | |
cddd424a VD |
281 | -dane_tlsa_domain smtp.example.com \ |
282 | -dane_tlsa_rrdata "2 1 1 | |
283 | B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \ | |
284 | -dane_tlsa_rrdata "2 1 1 | |
285 | 60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18" | |
cddd424a | 286 | ... |
c0a445a9 | 287 | Verification: OK |
cddd424a | 288 | Verified peername: smtp.example.com |
c0a445a9 | 289 | DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1 |
cddd424a VD |
290 | ... |
291 | ||
c4fbed6c VD |
292 | =item B<-dane_ee_no_namechecks> |
293 | ||
294 | This disables server name checks when authenticating via DANE-EE(3) TLSA | |
295 | records. | |
296 | For some applications, primarily web browsers, it is not safe to disable name | |
297 | checks due to "unknown key share" attacks, in which a malicious server can | |
298 | convince a client that a connection to a victim server is instead a secure | |
299 | connection to the malicious server. | |
300 | The malicious server may then be able to violate cross-origin scripting | |
301 | restrictions. | |
302 | Thus, despite the text of RFC7671, name checks are by default enabled for | |
303 | DANE-EE(3) TLSA records, and can be disabled in applications where it is safe | |
304 | to do so. | |
305 | In particular, SMTP and XMPP clients should set this option as SRV and MX | |
306 | records already make it possible for a remote domain to redirect client | |
307 | connections to any server of its choice, and in any case SMTP and XMPP clients | |
308 | do not execute scripts downloaded from remote servers. | |
309 | ||
e42d84be | 310 | =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, |
d33def66 | 311 | B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, |
5a1f853b | 312 | B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, |
e42d84be | 313 | B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, |
d33def66 | 314 | B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, |
fbb82a60 VD |
315 | B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, |
316 | B<-verify_ip>, B<-verify_name>, B<-x509_strict> | |
e5fa864f | 317 | |
fa7b0111 | 318 | Set various certificate chain validation options. See the |
9b86974e | 319 | L<verify(1)> manual page for details. |
e5fa864f | 320 | |
c3ed3b6e DSH |
321 | =item B<-reconnect> |
322 | ||
c4de074e | 323 | Reconnects to the same server 5 times using the same session ID, this can |
c3ed3b6e DSH |
324 | be used as a test that session caching is working. |
325 | ||
c3ed3b6e DSH |
326 | =item B<-showcerts> |
327 | ||
c4de074e | 328 | Display the whole server certificate chain: normally only the server |
c3ed3b6e DSH |
329 | certificate itself is displayed. |
330 | ||
331 | =item B<-prexit> | |
332 | ||
c4de074e | 333 | Print session information when the program exits. This will always attempt |
c3ed3b6e DSH |
334 | to print out information even if the connection fails. Normally information |
335 | will only be printed out once if the connection succeeds. This option is useful | |
336 | because the cipher in use may be renegotiated or the connection may fail | |
337 | because a client certificate is required or is requested only after an | |
338 | attempt is made to access a certain URL. Note: the output produced by this | |
339 | option is not always accurate because a connection might never have been | |
340 | established. | |
341 | ||
342 | =item B<-state> | |
343 | ||
c4de074e | 344 | Prints out the SSL session states. |
c3ed3b6e DSH |
345 | |
346 | =item B<-debug> | |
347 | ||
c4de074e | 348 | Print extensive debugging information including a hex dump of all traffic. |
c3ed3b6e | 349 | |
1d8634b1 BM |
350 | =item B<-msg> |
351 | ||
c4de074e | 352 | Show all protocol messages with hex dump. |
1d8634b1 | 353 | |
8dbeb110 DSH |
354 | =item B<-trace> |
355 | ||
c4de074e | 356 | Show verbose trace output of protocol messages. OpenSSL needs to be compiled |
8dbeb110 DSH |
357 | with B<enable-ssl-trace> for this option to work. |
358 | ||
359 | =item B<-msgfile> | |
360 | ||
c4de074e | 361 | File to send output of B<-msg> or B<-trace> to, default standard output. |
8dbeb110 | 362 | |
c3ed3b6e DSH |
363 | =item B<-nbio_test> |
364 | ||
c4de074e | 365 | Tests non-blocking I/O |
c3ed3b6e DSH |
366 | |
367 | =item B<-nbio> | |
368 | ||
c4de074e | 369 | Turns on non-blocking I/O |
c3ed3b6e DSH |
370 | |
371 | =item B<-crlf> | |
372 | ||
c4de074e | 373 | This option translated a line feed from the terminal into CR+LF as required |
c3ed3b6e DSH |
374 | by some servers. |
375 | ||
ce301b6b RL |
376 | =item B<-ign_eof> |
377 | ||
c4de074e | 378 | Inhibit shutting down the connection when end of file is reached in the |
ce301b6b RL |
379 | input. |
380 | ||
c3ed3b6e DSH |
381 | =item B<-quiet> |
382 | ||
c4de074e | 383 | Inhibit printing of session and certificate information. This implicitly |
ce301b6b | 384 | turns on B<-ign_eof> as well. |
c3ed3b6e | 385 | |
fc1d88f0 RS |
386 | =item B<-no_ign_eof> |
387 | ||
c4de074e | 388 | Shut down the connection when end of file is reached in the input. |
fc1d88f0 RS |
389 | Can be used to override the implicit B<-ign_eof> after B<-quiet>. |
390 | ||
ddac1974 NL |
391 | =item B<-psk_identity identity> |
392 | ||
393 | Use the PSK identity B<identity> when using a PSK cipher suite. | |
9d772829 | 394 | The default value is "Client_identity" (without the quotes). |
ddac1974 NL |
395 | |
396 | =item B<-psk key> | |
397 | ||
398 | Use the PSK key B<key> when using a PSK cipher suite. The key is | |
399 | given as a hexadecimal number without leading 0x, for example -psk | |
400 | 1a2b3c4d. | |
9d772829 | 401 | This option must be provided in order to use a PSK cipher. |
ddac1974 | 402 | |
582a17d6 | 403 | =item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3> |
c3ed3b6e | 404 | |
8c73aeb6 VD |
405 | These options require or disable the use of the specified SSL or TLS protocols. |
406 | By default B<s_client> will negotiate the highest mutually supported protocol | |
407 | version. | |
408 | When a specific TLS version is required, only that version will be offered to | |
409 | and accepted from the server. | |
c3ed3b6e | 410 | |
8c73aeb6 VD |
411 | =item B<-dtls>, B<-dtls1>, B<-dtls1_2> |
412 | ||
413 | These options make B<s_client> use DTLS protocols instead of TLS. | |
60250017 | 414 | With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version, |
8c73aeb6 VD |
415 | whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2 |
416 | respectively. | |
fb0e87fb | 417 | |
19044d3c MC |
418 | =item B<-sctp> |
419 | ||
420 | Use SCTP for the transport protocol instead of UDP in DTLS. Must be used in | |
421 | conjunction with B<-dtls>, B<-dtls1> or B<-dtls1_2>. This option is only | |
422 | available where OpenSSL has support for SCTP enabled. | |
423 | ||
fb0e87fb BM |
424 | =item B<-fallback_scsv> |
425 | ||
426 | Send TLS_FALLBACK_SCSV in the ClientHello. | |
c3ed3b6e | 427 | |
bc8857bf MC |
428 | =item B<-async> |
429 | ||
c4de074e | 430 | Switch on asynchronous mode. Cryptographic operations will be performed |
bc8857bf MC |
431 | asynchronously. This will only have an effect if an asynchronous capable engine |
432 | is also used via the B<-engine> option. For test purposes the dummy async engine | |
433 | (dasync) can be used (if available). | |
434 | ||
28e5ea88 F |
435 | =item B<-max_send_frag int> |
436 | ||
437 | The maximum size of data fragment to send. | |
438 | See L<SSL_CTX_set_max_send_fragment(3)> for further information. | |
439 | ||
0df80881 MC |
440 | =item B<-split_send_frag int> |
441 | ||
442 | The size used to split data for encrypt pipelines. If more data is written in | |
443 | one go than this value then it will be split into multiple pipelines, up to the | |
444 | maximum number of pipelines defined by max_pipelines. This only has an effect if | |
c4de074e | 445 | a suitable cipher suite has been negotiated, an engine that supports pipelining |
0df80881 MC |
446 | has been loaded, and max_pipelines is greater than 1. See |
447 | L<SSL_CTX_set_split_send_fragment(3)> for further information. | |
448 | ||
449 | =item B<-max_pipelines int> | |
450 | ||
451 | The maximum number of encrypt/decrypt pipelines to be used. This will only have | |
452 | an effect if an engine has been loaded that supports pipelining (e.g. the dasync | |
c4de074e | 453 | engine) and a suitable cipher suite has been negotiated. The default value is 1. |
0df80881 MC |
454 | See L<SSL_CTX_set_max_pipelines(3)> for further information. |
455 | ||
456 | =item B<-read_buf int> | |
457 | ||
458 | The default read buffer size to be used for connections. This will only have an | |
459 | effect if the buffer size is larger than the size that would otherwise be used | |
460 | and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for | |
461 | further information). | |
462 | ||
c3ed3b6e DSH |
463 | =item B<-bugs> |
464 | ||
c4de074e | 465 | There are several known bug in SSL and TLS implementations. Adding this |
c3ed3b6e DSH |
466 | option enables various workarounds. |
467 | ||
cc5a9ba4 VD |
468 | =item B<-comp> |
469 | ||
470 | Enables support for SSL/TLS compression. | |
471 | This option was introduced in OpenSSL 1.1.0. | |
472 | TLS compression is not recommended and is off by default as of | |
473 | OpenSSL 1.1.0. | |
474 | ||
475 | =item B<-no_comp> | |
476 | ||
477 | Disables support for SSL/TLS compression. | |
478 | TLS compression is not recommended and is off by default as of | |
479 | OpenSSL 1.1.0. | |
480 | ||
765b4137 DSH |
481 | =item B<-brief> |
482 | ||
c4de074e | 483 | Only provide a brief summary of connection parameters instead of the |
765b4137 DSH |
484 | normal verbose output. |
485 | ||
254b58fd SC |
486 | =item B<-sigalgs sigalglist> |
487 | ||
488 | Specifies the list of signature algorithms that are sent by the client. | |
489 | The server selects one entry in the list based on its preferences. | |
490 | For example strings, see L<SSL_CTX_set1_sigalgs(3)> | |
491 | ||
492 | =item B<-curves curvelist> | |
493 | ||
494 | Specifies the list of supported curves to be sent by the client. The curve is | |
495 | is ultimately selected by the server. For a list of all curves, use: | |
496 | ||
497 | $ openssl ecparam -list_curves | |
498 | ||
c3ed3b6e DSH |
499 | =item B<-cipher cipherlist> |
500 | ||
c4de074e | 501 | This allows the cipher list sent by the client to be modified. Although |
fabce041 DSH |
502 | the server determines which cipher suite is used it should take the first |
503 | supported cipher in the list sent by the client. See the B<ciphers> | |
504 | command for more information. | |
c3ed3b6e | 505 | |
e986704d RL |
506 | =item B<-starttls protocol> |
507 | ||
c4de074e | 508 | Send the protocol-specific message(s) to switch to TLS for communication. |
e986704d | 509 | B<protocol> is a keyword for the intended protocol. Currently, the only |
cfb4f1ef | 510 | supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server", |
a2d9cfba | 511 | "irc", "postgres", "mysql", "lmtp", "nntp", "sieve" and "ldap". |
e986704d | 512 | |
b98af49d CALP |
513 | =item B<-xmpphost hostname> |
514 | ||
898ea7b8 KE |
515 | This option, when used with "-starttls xmpp" or "-starttls xmpp-server", |
516 | specifies the host for the "to" attribute of the stream element. | |
b98af49d CALP |
517 | If this option is not specified, then the host specified with "-connect" |
518 | will be used. | |
519 | ||
8176431d PY |
520 | This option is an alias of the B<-name> option for "xmpp" and "xmpp-server". |
521 | ||
522 | =item B<-name hostname> | |
523 | ||
524 | This option is used to specify hostname information for various protocols | |
525 | used with B<-starttls> option. Currently only "xmpp", "xmpp-server", | |
526 | "smtp" and "lmtp" can utilize this B<-name> option. | |
527 | ||
528 | If this option is used with "-starttls xmpp" or "-starttls xmpp-server", | |
529 | if specifies the host for the "to" attribute of the stream element. If this | |
530 | option is not specified, then the host specified with "-connect" will be used. | |
531 | ||
532 | If this option is used with "-starttls lmtp" or "-starttls smtp", it specifies | |
533 | the name to use in the "LMTP LHLO" or "SMTP EHLO" message, respectively. If | |
534 | this option is not specified, then "mail.example.com" will be used. | |
535 | ||
d24a9c8f DSH |
536 | =item B<-tlsextdebug> |
537 | ||
c4de074e | 538 | Print out a hex dump of any TLS extensions received from the server. |
d24a9c8f DSH |
539 | |
540 | =item B<-no_ticket> | |
541 | ||
c4de074e | 542 | Disable RFC4507bis session ticket support. |
d24a9c8f DSH |
543 | |
544 | =item B<-sess_out filename> | |
545 | ||
c4de074e | 546 | Output SSL session to B<filename>. |
d24a9c8f DSH |
547 | |
548 | =item B<-sess_in sess.pem> | |
549 | ||
c4de074e | 550 | Load SSL session from B<filename>. The client will attempt to resume a |
d24a9c8f DSH |
551 | connection from this session. |
552 | ||
5270e702 RL |
553 | =item B<-engine id> |
554 | ||
c4de074e | 555 | Specifying an engine (by its unique B<id> string) will cause B<s_client> |
5270e702 RL |
556 | to attempt to obtain a functional reference to the specified engine, |
557 | thus initialising it if needed. The engine will then be set as the default | |
558 | for all available algorithms. | |
559 | ||
3ee1eac2 | 560 | =item B<-rand file...> |
52b621db | 561 | |
c4de074e | 562 | A file or files containing random data used to seed the random number |
3ee1eac2 | 563 | generator. |
35ed393e | 564 | Multiple files can be specified separated by an OS-dependent character. |
52b621db LJ |
565 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for |
566 | all others. | |
567 | ||
3ee1eac2 RS |
568 | =item [B<-writerand file>] |
569 | ||
570 | Writes random data to the specified I<file> upon exit. | |
571 | This can be used with a subsequent B<-rand> flag. | |
572 | ||
9cd50f73 T |
573 | =item B<-serverinfo types> |
574 | ||
c4de074e | 575 | A list of comma-separated TLS Extension Types (numbers between 0 and |
9cd50f73 T |
576 | 65535). Each type will be sent as an empty ClientHello TLS Extension. |
577 | The server's response (if any) will be encoded and displayed as a PEM | |
578 | file. | |
579 | ||
cba3f1c7 DSH |
580 | =item B<-status> |
581 | ||
c4de074e | 582 | Sends a certificate status request to the server (OCSP stapling). The server |
cba3f1c7 DSH |
583 | response (if any) is printed out. |
584 | ||
776e15f9 | 585 | =item B<-alpn protocols>, B<-nextprotoneg protocols> |
7efd0e77 | 586 | |
c4de074e P |
587 | These flags enable the Enable the Application-Layer Protocol Negotiation |
588 | or Next Protocol Negotiation (NPN) extension, respectively. ALPN is the | |
589 | IETF standard and replaces NPN. | |
590 | The B<protocols> list is a comma-separated list of protocol names that | |
591 | the client should advertise support for. The list should contain the most | |
592 | desirable protocols first. Protocol names are printable ASCII strings, | |
593 | for example "http/1.1" or "spdy/3". | |
594 | An empty list of protocols is treated specially and will cause the | |
595 | client to advertise support for the TLS extension but disconnect just | |
596 | after receiving ServerHello with a list of server supported protocols. | |
837f87c2 | 597 | The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used. |
7efd0e77 | 598 | |
e75138ab | 599 | =item B<-ct>, B<-noct> |
eb64a6c6 | 600 | |
43341433 VD |
601 | Use one of these two options to control whether Certificate Transparency (CT) |
602 | is enabled (B<-ct>) or disabled (B<-noct>). | |
603 | If CT is enabled, signed certificate timestamps (SCTs) will be requested from | |
604 | the server and reported at handshake completion. | |
eb64a6c6 RP |
605 | |
606 | Enabling CT also enables OCSP stapling, as this is one possible delivery method | |
607 | for SCTs. | |
608 | ||
609 | =item B<-ctlogfile> | |
610 | ||
611 | A file containing a list of known Certificate Transparency logs. See | |
612 | L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format. | |
613 | ||
6437b802 | 614 | =item B<-keylogfile file> |
4bf73e9f PW |
615 | |
616 | Appends TLS secrets to the specified keylog file such that external programs | |
617 | (like Wireshark) can decrypt TLS connections. | |
618 | ||
6437b802 MC |
619 | =item B<-early_data file> |
620 | ||
621 | Reads the contents of the specified file and attempts to send it as early data | |
622 | to the server. This will only work with resumed sessions that support early | |
623 | data and when the server accepts the early data. | |
624 | ||
9d75dce3 TS |
625 | =item B<-force_pha> |
626 | ||
627 | For TLSv1.3 only, always send the Post-Handshake Authentication extension, | |
628 | whether or not a certificate has been provided via B<-cert>. | |
629 | ||
729ef856 CB |
630 | =item B<[target]> |
631 | ||
632 | Rather than providing B<-connect>, the target hostname and optional port may | |
633 | be provided as a single positional argument after all options. If neither this | |
634 | nor B<-connect> are provided, falls back to attempting to connect to localhost | |
635 | on port 4433. | |
636 | ||
efeca6aa UM |
637 | =back |
638 | ||
c3ed3b6e DSH |
639 | =head1 CONNECTED COMMANDS |
640 | ||
641 | If a connection is established with an SSL server then any data received | |
642 | from the server is displayed and any key presses will be sent to the | |
ce301b6b | 643 | server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> |
3b80e3aa | 644 | have been given), the session will be renegotiated if the line begins with an |
ce301b6b RL |
645 | B<R>, and if the line begins with a B<Q> or if end of file is reached, the |
646 | connection will be closed down. | |
c3ed3b6e DSH |
647 | |
648 | =head1 NOTES | |
649 | ||
650 | B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP | |
651 | server the command: | |
652 | ||
653 | openssl s_client -connect servername:443 | |
654 | ||
655 | would typically be used (https uses port 443). If the connection succeeds | |
656 | then an HTTP command can be given such as "GET /" to retrieve a web page. | |
657 | ||
658 | If the handshake fails then there are several possible causes, if it is | |
45f55f6a KR |
659 | nothing obvious like no client certificate then the B<-bugs>, |
660 | B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> options can be tried | |
c3ed3b6e DSH |
661 | in case it is a buggy server. In particular you should play with these |
662 | options B<before> submitting a bug report to an OpenSSL mailing list. | |
663 | ||
664 | A frequent problem when attempting to get client certificates working | |
665 | is that a web client complains it has no certificates or gives an empty | |
666 | list to choose from. This is normally because the server is not sending | |
667 | the clients certificate authority in its "acceptable CA list" when it | |
668 | requests a certificate. By using B<s_client> the CA list can be viewed | |
669 | and checked. However some servers only request client authentication | |
670 | after a specific URL is requested. To obtain the list in this case it | |
a32fc687 | 671 | is necessary to use the B<-prexit> option and send an HTTP request |
c3ed3b6e DSH |
672 | for an appropriate page. |
673 | ||
674 | If a certificate is specified on the command line using the B<-cert> | |
675 | option it will not be used unless the server specifically requests | |
676 | a client certificate. Therefor merely including a client certificate | |
677 | on the command line is no guarantee that the certificate works. | |
678 | ||
679 | If there are problems verifying a server certificate then the | |
680 | B<-showcerts> option can be used to show the whole chain. | |
681 | ||
4e6c12f3 DSH |
682 | The B<s_client> utility is a test tool and is designed to continue the |
683 | handshake after any certificate verification errors. As a result it will | |
684 | accept any certificate chain (trusted or not) sent by the peer. None test | |
685 | applications should B<not> do this as it makes them vulnerable to a MITM | |
686 | attack. This behaviour can be changed by with the B<-verify_return_error> | |
687 | option: any verify errors are then returned aborting the handshake. | |
688 | ||
c3ed3b6e DSH |
689 | =head1 BUGS |
690 | ||
8c73aeb6 VD |
691 | Because this program has a lot of options and also because some of the |
692 | techniques used are rather old, the C source of B<s_client> is rather hard to | |
693 | read and not a model of how things should be done. | |
694 | A typical SSL client program would be much simpler. | |
c3ed3b6e | 695 | |
c3ed3b6e DSH |
696 | The B<-prexit> option is a bit of a hack. We should really report |
697 | information whenever a session is renegotiated. | |
698 | ||
699 | =head1 SEE ALSO | |
700 | ||
28e5ea88 F |
701 | L<SSL_CONF_cmd(3)>, L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>, |
702 | L<SSL_CTX_set_max_send_fragment(3)>, L<SSL_CTX_set_split_send_fragment(3)> | |
729ef856 | 703 | L<SSL_CTX_set_max_pipelines(3)> |
c3ed3b6e | 704 | |
fa7b0111 MC |
705 | =head1 HISTORY |
706 | ||
8176431d PY |
707 | The B<-no_alt_chains> option was first added to OpenSSL 1.1.0. |
708 | The B<-name> option was added in OpenSSL 1.1.1. | |
fa7b0111 | 709 | |
e2f92610 RS |
710 | =head1 COPYRIGHT |
711 | ||
6738bf14 | 712 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
713 | |
714 | Licensed under the OpenSSL license (the "License"). You may not use | |
715 | this file except in compliance with the License. You can obtain a copy | |
716 | in the file LICENSE in the source distribution or at | |
717 | L<https://www.openssl.org/source/license.html>. | |
718 | ||
719 | =cut |