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