From 58f7f2046ec48927c9f41d8e82510959c4c4ae3b Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Thu, 7 Jun 2018 14:52:59 +0200
Subject: public_key: Clearify pkix_verify_hostname documentation

---
 lib/public_key/doc/src/public_key.xml       | 57 +++++++++++++++++++++++++----
 lib/public_key/doc/src/using_public_key.xml |  4 +-
 2 files changed, 52 insertions(+), 9 deletions(-)

(limited to 'lib/public_key')

diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml
index 5d57109140..30ec70aa9b 100644
--- a/lib/public_key/doc/src/public_key.xml
+++ b/lib/public_key/doc/src/public_key.xml
@@ -969,35 +969,76 @@ fun(#'DistributionPoint'{}, #'CertificateList'{},
     </type>
     <desc>
       <p>This function checks that the <i>Presented Identifier</i> (e.g hostname) in a peer certificate
-      is in agreement with the <i>Reference Identifier</i> that the client expects to be connected to.
+      is in agreement with at least one of the <i>Reference Identifier</i> that the client expects to be connected to.
       The function is intended to be added as an extra client check of the peer certificate when performing
       <seealso marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
       </p>
       <p>See <url href="https://tools.ietf.org/html/rfc6125">RFC 6125</url>
       for detailed information about hostname verification.
-      The <seealso marker="using_public_key#verify_hostname">User's Manual</seealso>
+      The <seealso marker="using_public_key#verify_hostname">User's Guide</seealso>
       and
       <seealso marker="using_public_key#verify_hostname_examples">code examples</seealso>
       describes this function more detailed.
       </p>
       <p>The <c>{OtherRefId,term()}</c> is defined by the user and is passed to the <c>match_fun</c>, if defined.
-      If that term is a binary, it will be converted to a string.
+      If the term in <c>OtherRefId</c> is a binary, it will be converted to a string.
       </p>
       <p>The <c>ip</c> Reference ID takes an <seealso marker="inet:inet#type-ip_address">inet:ip_address()</seealso>
       or an ip address in string format (E.g "10.0.1.1" or "1234::5678:9012") as second element.
       </p>
-      <p>See <seealso marker="#pkix_verify_hostname_match_fun-1">pkix_verify_hostname_match_fun/1</seealso> for a
-      function that return a fun suitable for this option.
-      </p>
+      <p>The options are:</p>
+      <taglist>
+	<tag><c>match_fun</c></tag>
+	<item>
+	  The <c>fun/2</c> in this option replaces the default host name matching rules. The fun should return a
+	  boolean to tell if the Reference ID and Presented ID matches or not. The fun can also return a third 
+	  value. the atom <c>default</c>, if the default matching rules shall apply.
+	  This makes it possible to augment the tests with a special case:
+	  <code>
+fun(....) -> true;   % My special case
+   (_, _) -> default % all others falls back to the inherit tests
+end
+	  </code>
+	  <br/>See <seealso marker="#pkix_verify_hostname_match_fun-1">pkix_verify_hostname_match_fun/1</seealso> for a
+	  function that takes a protocol name as argument and returns a <c>fun/2</c> suitable for this option and
+	  <seealso marker="using_public_key#redefining_match_op">Re-defining the match operation</seealso>
+	  in the User's Guide for an example.
+	</item>
+
+	<tag><c>fail_callback</c></tag>
+	<item>If a matching fails, there could be circumstances when the certificate should be accepted anyway. Think for
+	example of a web browser where you choose to accept an outdated certificate. This options enables implementation
+	of such a function. This <c>fun/1</c> is called when no <c>ReferenceID</c> matches. The return value of the fun
+	(a <c>boolean()</c>) decides the outcome. If <c>true</c> the the certificate is accepted otherwise
+	it is rejected. See
+	<seealso marker="using_public_key#-pinning--a-certificate">"Pinning" a Certificate</seealso>
+	in the User's Guide.
+	</item>
+
+	<tag><c>fqdn_fun</c></tag>
+	<item>This option augments the host name extraction from URIs and other Reference IDs. It could for example be
+	a very special URI that is not standardised. The fun takes a Reference ID as argument and returns one of:
+	<list>
+	  <item>the hostname</item>
+	  <item>the atom <c>default</c>: the default host name extract function will be used</item>
+	  <item>the atom <c>undefined</c>: a host name could not be extracted. The pkix_verify_hostname/3
+	  will return <c>false</c>.</item>
+	</list>
+	<br/>For an example, see
+	<seealso marker="using_public_key#hostname_extraction">Hostname extraction</seealso>
+	in the User's Guide.
+	</item>
+      </taglist>
+
     </desc>
   </func>
 
   <func>
-    <name>pkix_verify_hostname_match_fun(Alg) ->  fun(RefId | FQDN::string(), PresentedID) -> boolean() | default</name>
+    <name>pkix_verify_hostname_match_fun(Protcol) ->  fun(RefId | FQDN::string(), PresentedID) -> boolean() | default</name>
     <fsummary>Returns a fun that is intendended as argument to the match_fun option in pkix_verify_hostname/3.
     </fsummary>
     <type>
-      <v>Alg = https</v>
+      <v>Protocol = https</v>
       <d>The algorithm for wich the fun should implement the special matching rules</d>
       <v>RefId</v>
       <d>See <seealso marker="#pkix_verify_hostname-3">pkix_verify_hostname/3</seealso>.</d>
diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml
index 417d479da3..b936b7fcb5 100644
--- a/lib/public_key/doc/src/using_public_key.xml
+++ b/lib/public_key/doc/src/using_public_key.xml
@@ -570,6 +570,7 @@ true = public_key:verify(Digest, none, Signature, PublicKey),</code>
      <c>fqdn_fun</c> and <c>match_fun</c>.
      </p>
      <section>
+       <marker id="hostname_extraction"></marker>
        <title>Hostname extraction</title>
        <p>The <c>fqdn_fun</c> extracts hostnames (Fully Qualified Domain Names) from uri_id
        or other ReferenceIDs that are not pre-defined in the public_key function.
@@ -595,7 +596,8 @@ true = public_key:verify(Digest, none, Signature, PublicKey),</code>
        </code>
      </section>
      <section>
-       <title>Re-defining the match operations</title>
+       <marker id="redefining_match_op"></marker>
+       <title>Re-defining the match operation</title>
        <p>The default matching handles dns_id and uri_id. In an uri_id the value is tested for
        equality with a value from the <c>Subject Alternate Name</c>. If som other kind of matching
        is needed, use the  <c>match_fun</c> option.
-- 
cgit v1.2.3