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