DANE s_client support

[openssl.git] / doc / apps / s_client.pod

diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod
index e91b9f1334a5e95310a793fc0f7fc55aca7ec8b6..e69c730329747963ce122bea044dc1a60cb78df2 100644 (file)
--- a/doc/apps/s_client.pod
+++ b/doc/apps/s_client.pod
@@ -20,6 +20,10 @@ B<openssl> B<s_client>
 [B<-pass arg>]
 [B<-CApath directory>]
 [B<-CAfile filename>]
+[B<-no-CAfile>]
+[B<-no-CApath>]
+[B<-dane_tlsa_domain domain>]
+[B<-dane_tlsa_rrdata rrdata>]
 [B<-attime timestamp>]
 [B<-check_ss_sig>]
 [B<-crl_check>]
@@ -66,6 +70,7 @@ B<openssl> B<s_client>
 [B<-no_tls1_1>]
 [B<-no_tls1_2>]
 [B<-fallback_scsv>]
+[B<-async>]
 [B<-bugs>]
 [B<-cipher cipherlist>]
 [B<-serverpref>]
@@ -132,7 +137,7 @@ The private format to use: DER or PEM. PEM is the default.
 =item B<-pass arg>
 
 the private key password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 
 =item B<-verify depth>
 
@@ -158,6 +163,53 @@ also used when building the client certificate chain.
 A file containing trusted certificates to use during server authentication
 and to use when attempting to build the client certificate chain.
 
+=item B<-no-CAfile>
+
+Do not load the trusted CA certificates from the default file location
+
+=item B<-no-CApath>
+
+Do not load the trusted CA certificates from the default directory location
+
+=item B<-dane_tlsa_domain domain>
+
+Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
+TLSA base domain which becomes the default SNI hint and the primary
+reference identifier for hostname checks.  This must be used in
+combination with at least one instance of the B<-dane_tlsa_rrdata>
+option below.
+
+When DANE authentication succeeds, the diagnostic output will include
+the lowest (closest to 0) depth at which a TLSA record authenticated
+a chain certificate.  When that TLSA record is a "2 1 0" trust
+anchor public key that signed (rather than matched) the top-most
+certificate of the chain, the result is reported as "TA public key
+verified".  Otherwise, either the TLSA record "matched TA certificate"
+at a positive depth or else "matched EE certificate" at depth 0.
+
+=item B<-dane_tlsa_rrdata rrdata>
+
+Use one or more times to specify the RRDATA fields of the DANE TLSA
+RRset associated with the target service.  The B<rrdata> value is
+specied in "presentation form", that is four whitespace separated
+fields that specify the usage, selector, matching type and associated
+data, with the last of these encoded in hexadecimal.  Optional
+whitespace is ignored in the associated data field.  For example:
+
+  $ openssl s_client -starttls smtp -connect smtp.example.com:25 \
+    -dane_tlsa_domain smtp.example.com \
+    -dane_tlsa_rrdata "2 1 1
+      B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
+    -dane_tlsa_rrdata "2 1 1
+      60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
+  CONNECTED(00000003)
+  ...
+  DANE TLSA 2 1 1 matched TA certificate at depth 1
+  Verified peername: smtp.example.com
+  ...
+      Verify return code: 0 (ok)
+  ...
+
 =item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
 B<explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
 B<-inhibit_map>, B<-issuer_checks>, B<-partial_chain>, B<-policy>,
@@ -167,7 +219,7 @@ B<-use_deltas>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
 B<-verify_ip>, B<-verify_name>, B<-x509_strict>
 
 Set various certificate chain validation options. See the
-L<B<verify>|verify(1)> manual page for details.
+L<verify(1)> manual page for details.
 
 =item B<-reconnect>
 
@@ -267,6 +319,13 @@ work if TLS is turned off.
 
 Send TLS_FALLBACK_SCSV in the ClientHello.
 
+=item B<-async>
+
+switch on asynchronous mode. Cryptographic operations will be performed
+asynchronously. This will only have an effect if an asynchronous capable engine
+is also used via the B<-engine> option. For test purposes the dummy async engine
+(dasync) can be used (if available).
+
 =item B<-bugs>
 
 there are several known bug in SSL and TLS implementations. Adding this
@@ -288,8 +347,8 @@ command for more information.
 
 send the protocol-specific message(s) to switch to TLS for communication.
 B<protocol> is a keyword for the intended protocol.  Currently, the only
-supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp",
-and "xmpp-server".
+supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
+and "irc."
 
 =item B<-xmpphost hostname>
 
@@ -325,7 +384,7 @@ for all available algorithms.
 =item B<-rand file(s)>
 
 a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+generator, or an EGD socket (see L<RAND_egd(3)>).
 Multiple files can be specified separated by a OS-dependent character.
 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 all others.
@@ -417,7 +476,7 @@ information whenever a session is renegotiated.
 
 =head1 SEE ALSO
 
-L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
+L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>
 
 =head1 HISTORY