From e9b0dbb4a95dbc8e328f08d6df6654dcbe13db09 Mon Sep 17 00:00:00 2001
From: Ingela Anderton Andin <ingela@erlang.org>
Date: Wed, 22 Mar 2017 14:49:22 +0100
Subject: ssl: Add hostname check of server certificate

When the server_name_indication is sent automatize the
clients check of that the hostname is present in the
servers certificate. Currently server_name_indication shall
be on the dns_id format. If server_name_indication is disabled
it is up to the user to do its own check in the verify_fun.
---
 lib/ssl/doc/src/ssl.xml | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

(limited to 'lib/ssl/doc')

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 2c09122fe6..2940ccb1e7 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -127,7 +127,7 @@
       <item><p><c>hostname() | ipaddress()</c></p></item>
 
       <tag><c>hostname() =</c></tag>
-      <item><p><c>string()</c></p></item>
+      <item><p><c>string() - DNS hostname</c></p></item>
 
       <tag><c>ip_address() =</c></tag>
       <item><p><c>{N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
@@ -249,7 +249,7 @@
       be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, 
       ROOT-CA, and so on. The default value is 1.</p></item>
 
-      <tag><c>{verify_fun, {Verifyfun :: fun(), InitialUserState ::
+      <tag><marker id="verify_fun"/><c>{verify_fun, {Verifyfun :: fun(), InitialUserState ::
       term()}}</c></tag>
       <item><p>The verification fun is to be defined as follows:</p>
 
@@ -582,15 +582,23 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <item><p>Specifies the username and password to use to authenticate
       to the server.</p></item>
 
-      <tag><c>{server_name_indication, hostname()}</c></tag>
-      <item><p>Can be specified when upgrading a TCP socket to a TLS
-        socket to use the TLS Server Name Indication extension.</p></item>
+      <tag><c>{server_name_indication, HostName :: hostname()}</c></tag>
+      <item><p>Specify the hostname to be used in TLS Server Name Indication extension.
+      Is usefull when upgrading a TCP socket to a TLS socket or if the hostname can not be 
+      derived from the Host argument to <seealso marker="ssl#connect-3">ssl:connect/3</seealso>.
+      Will also cause the client to preform host name verification of the peer certificate
+      <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname(PeerCert, [{dns_id, HostName}])</seealso>
+      </p> during the x509-path validation. If the check fails the error {bad_cert, hostname_check_failiure} will be
+      propagated to the path validation fun <seealso marker="#verify_fun">verify_fun</seealso>
+      </item>
 
 	<tag><c>{server_name_indication, disable}</c></tag>
       <item>
         <p>When starting a TLS connection without upgrade, the Server Name
-        Indication extension is sent if possible. This option can be
-        used to disable that behavior.</p>
+        Indication extension is sent if possible that is can be derived from the Host argument 
+        to <seealso marker="ssl#connect-3">ssl:connect/3</seealso>.  
+	This option can be used to disable that behavior.</p>
+	<note><p> Note that this also disables the default host name verification check of the peer certificate.</p></note>
       </item>
       <tag><c>{fallback, boolean()}</c></tag>
       <item>
-- 
cgit v1.2.3