From b53bdc5c149d2a05a8fa28e663f042049c0bdabd Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Wed, 16 Oct 2013 15:58:39 +0200
Subject: eldap: Doc

---
 lib/eldap/doc/src/eldap.xml | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

(limited to 'lib/eldap/doc/src')

diff --git a/lib/eldap/doc/src/eldap.xml b/lib/eldap/doc/src/eldap.xml
index 30767abd7e..bb107822b3 100644
--- a/lib/eldap/doc/src/eldap.xml
+++ b/lib/eldap/doc/src/eldap.xml
@@ -35,6 +35,7 @@
     <p>References:</p>
     <list type="bulleted">
       <item> <p>RFC 4510 - RFC 4519</p> </item>
+      <item> <p>RFC 2830</p> </item>
     </list>
     <p>The above publications can be found at <url href="http://www.ietf.org">IETF</url>.
     </p>
@@ -86,6 +87,34 @@ filter()    See present/1, substrings/2,
         <p>Shutdown the connection.</p>
       </desc>
     </func>
+    <func>
+      <name>start_tls(Handle, Options) -> ok | {error,Error}</name>
+      <fsummary>Shutdown the connection.</fsummary>
+      <desc>
+        <p>Same as start_tls(Handle, Options, infinity)</p>
+      </desc>
+    </func>
+    <func>
+      <name>start_tls(Handle, Options, Timeout) -> ok | {error,Error}</name>
+      <fsummary>Shutdown the connection.</fsummary>
+      <type>
+	<v>Handle = handle()</v>
+	<v>Options = ssl:ssl_options()</v>
+	<v>Timeout = inifinity | positive_integer()</v>
+      </type>
+      <desc>
+        <p>Upgrade the connection associated with <c>Handle</c> to a tls connection if possible.</p>
+        <p>Among the Error responses we find:</p>
+	<taglist>
+	  <tag><c>tls_already_started</c></tag>
+	  <item>The connection is already encrypted.  The connection is not affected.</item>
+	  <tag><c>{response,ResponseFromServer}</c></tag>
+	  <item>The upgrade was refused by the LDAP server.  The <c>ResponseFromServer</c> is an atom delivered byt the LDAP server explained in section 2.3 of rfc 2830. The connection is not affected, so it is still un-encrypted.</item>
+	  <tag><c>Error</c></tag>
+	  <item>Any error responded from ssl:connect/3</item>
+	</taglist>
+      </desc>
+    </func>
     <func>
       <name>simple_bind(Handle, Dn, Password) -> ok | {error, Reason}</name>
       <fsummary>Authenticate the connection.</fsummary>
-- 
cgit v1.2.3


From 0d41b12e62f285d1c5317b4c6396737d601191bc Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Mon, 28 Oct 2013 16:44:05 +0100
Subject: eldap: minor doc change after review.

---
 lib/eldap/doc/src/eldap.xml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

(limited to 'lib/eldap/doc/src')

diff --git a/lib/eldap/doc/src/eldap.xml b/lib/eldap/doc/src/eldap.xml
index bb107822b3..5b81716543 100644
--- a/lib/eldap/doc/src/eldap.xml
+++ b/lib/eldap/doc/src/eldap.xml
@@ -89,14 +89,14 @@ filter()    See present/1, substrings/2,
     </func>
     <func>
       <name>start_tls(Handle, Options) -> ok | {error,Error}</name>
-      <fsummary>Shutdown the connection.</fsummary>
+      <fsummary>Upgrade a connection to TLS.</fsummary>
       <desc>
         <p>Same as start_tls(Handle, Options, infinity)</p>
       </desc>
     </func>
     <func>
       <name>start_tls(Handle, Options, Timeout) -> ok | {error,Error}</name>
-      <fsummary>Shutdown the connection.</fsummary>
+      <fsummary>Upgrade a connection to TLS.</fsummary>
       <type>
 	<v>Handle = handle()</v>
 	<v>Options = ssl:ssl_options()</v>
@@ -104,12 +104,16 @@ filter()    See present/1, substrings/2,
       </type>
       <desc>
         <p>Upgrade the connection associated with <c>Handle</c> to a tls connection if possible.</p>
-        <p>Among the Error responses we find:</p>
+	<p>The upgrade is done in two phases: first the server is asked for permission to upgrade. Second, if the request is acknowledged, the upgrade is performed.</p>
+	<p>Error responese from phase one will not affect the current encryption state of the connection. Those responses are:</p>
 	<taglist>
 	  <tag><c>tls_already_started</c></tag>
 	  <item>The connection is already encrypted.  The connection is not affected.</item>
 	  <tag><c>{response,ResponseFromServer}</c></tag>
 	  <item>The upgrade was refused by the LDAP server.  The <c>ResponseFromServer</c> is an atom delivered byt the LDAP server explained in section 2.3 of rfc 2830. The connection is not affected, so it is still un-encrypted.</item>
+	</taglist>
+	<p>Errors in the seconde phase will however end the connection:</p>
+	<taglist>
 	  <tag><c>Error</c></tag>
 	  <item>Any error responded from ssl:connect/3</item>
 	</taglist>
-- 
cgit v1.2.3