From 53bfbb61333af35cde29bb786817856925dcedf0 Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Mon, 2 Nov 2015 13:08:13 +0100
Subject: ssh: Document pwdfun

---
 lib/ssh/doc/src/ssh.xml | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

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

diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 2b190c98b6..31a5e71401 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -471,12 +471,43 @@ kex is implicit but public_key is set explicitly.</p>
 	    </p>
 	  </item>
 
-	  <tag><c><![CDATA[{pwdfun, fun(User::string(), password::string()) -> boolean()}]]></c></tag>
+	  <tag><c><![CDATA[{pwdfun, fun(User::string(), Password::string(), PeerAddress::{ip_adress(),port_number()}, State::any()) -> boolean()}]]></c></tag>
+	  <item>
+	    <p>Provides a function for password validation. This could used for calling an external system or if
+	    passwords should be stored as a hash. The fun returns:
+	      <list type="bulleted">
+		<item><c>true</c> if the user and password is valid and</item>
+		<item><c>false</c> otherwise.</item> 
+	      </list>
+	    </p>
+	    <p>This fun can also be used to make delays in authentication tries for example by calling
+	      <seealso marker="stdlib:timer#sleep/1">timer:sleep/1</seealso>. To facilitate counting of failed tries
+	      the <c>State</c> variable could be used. This state is per connection only. The first time the pwdfun
+	      is called for a connection, the <c>State</c> variable has the value <c>undefined</c>.  
+	      The pwdfun can return - in addition to the values above - a new state
+	      as:
+	      <list type="bulleted">
+		<item><c>{true,  NewState:any()}</c> if the user and password is valid or</item>
+		<item><c>{false, NewState:any()}</c> if the user or password is invalid</item> 
+	      </list>
+	    </p>
+	    <p>A third usage is to block login attempts from a missbehaving peer. The <c>State</c> described above 
+	    can be used for this. In addition to the responses above, the following return value is introduced:
+	    <list type="bulleted">
+	      <item><c>disconnect</c> if the connection should be closed immediately after sending a SSH_MSG_DISCONNECT
+	      message.</item>
+	    </list>
+	    </p>
+	  </item>
+
+	  <tag><c><![CDATA[{pwdfun, fun(User::string(), Password::string()) -> boolean()}]]></c></tag>
 	  <item>
 	    <p>Provides a function for password validation. This function is called
 	      with user and password as strings, and returns
 	      <c><![CDATA[true]]></c> if the password is valid and
 	      <c><![CDATA[false]]></c> otherwise.</p>
+	      <p>This option (<c>{pwdfun,fun/2}</c>) is the same as a subset of the previous 
+	      (<c>{pwdfun,fun/4}</c>). It is kept for compatibility.</p>
 	  </item>
 
 	  <tag><c><![CDATA[{negotiation_timeout, integer()}]]></c></tag>
-- 
cgit v1.2.3


From 19f3eafbb237af7b6a9d81ebbddae19c41418f8b Mon Sep 17 00:00:00 2001
From: Hans Nilsson <hans@erlang.org>
Date: Tue, 3 Nov 2015 14:53:30 +0100
Subject: ssh: changes after doc review

---
 lib/ssh/doc/src/ssh.xml | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

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

diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 31a5e71401..f530a68dd9 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -60,6 +60,29 @@
     
   </section>
   
+  <section>
+    <title>OPTIONS</title>
+    <p>The exact behaviour of some functions can be adjusted with the use of options which are documented together
+    with the functions. Generally could each option be used at most one time in each function call. If given two or more
+    times, the effect is not predictable unless explicitly documented.</p>
+    <p>The options are of different kinds:</p>
+    <taglist>
+      <tag>Limits</tag>
+      <item><p>which alters limits in the system, for example number of simultaneous login attempts.</p></item>
+
+      <tag>Timeouts</tag>
+      <item><p>which give some defined behaviour if too long time elapses before a given event or action,
+      for example time to wait for an answer.</p></item>
+
+      <tag>Callbacks</tag>
+      <item><p>which gives the caller of the function the possibility to execute own code on some events,
+      for example calling an own logging function or to perform an own login function</p></item>
+
+      <tag>Behaviour</tag>
+      <item><p>which changes the systems behaviour.</p></item>
+    </taglist>
+  </section>
+
   <section>
     <title>DATA TYPES</title>
     <p>Type definitions that are used more than once in
@@ -471,7 +494,7 @@ kex is implicit but public_key is set explicitly.</p>
 	    </p>
 	  </item>
 
-	  <tag><c><![CDATA[{pwdfun, fun(User::string(), Password::string(), PeerAddress::{ip_adress(),port_number()}, State::any()) -> boolean()}]]></c></tag>
+	  <tag><c><![CDATA[{pwdfun, fun(User::string(), Password::string(), PeerAddress::{ip_adress(),port_number()}, State::any()) -> boolean() | disconnect | {boolean(),any()} }]]></c></tag>
 	  <item>
 	    <p>Provides a function for password validation. This could used for calling an external system or if
 	    passwords should be stored as a hash. The fun returns:
-- 
cgit v1.2.3