ssh: Document and clean up SSH behaviours

1 files changed, 124 insertions, 0 deletions

diff --git a/lib/ssh/doc/src/ssh_client_key_api.xml b/lib/ssh/doc/src/ssh_client_key_api.xml
new file mode 100644
index 0000000000..abc1070e78
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_client_key_api.xml
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2012</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+
+      The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+    <title>ssh_client_key_api</title>
+  </header>
+  <module>ssh_client_key_api</module>
+  <modulesummary>
+     -behaviour(ssh_client_key_api).
+  </modulesummary>
+  <description>
+    <p> Behavior describing the API for an SSH client's public key handling.
+      By implementing the callbacks defined.
+    in this behavior it is possible to customize the SSH client's public key
+    handling. By default the SSH application implements this behavior
+    with help of the standard openssh files, see <seealso marker="SSH_app"> ssh(6)</seealso>. </p>
+  </description>
+
+  <section>
+    <title>DATA TYPES </title>
+
+    <p>Type definitions that are used more than once in this module
+    and/or abstractions to indicate the intended use of the data
+    type:</p>
+
+    <p> boolean() = true | false</p>
+    <p> string() =  [byte()] </p>
+    <p> public_key() =  #'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</p>
+    <p> private_key() =  #'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</p>
+    <p> public_key_algorithm() =  'ssh-rsa'| 'ssh-dss' | atom()</p>
+
+  </section>
+
+  <funcs>
+    <func>
+      <name>Module:add_host_key(HostNames, Key, ConnectOptions) -> ok | {error, Reason}</name>
+      <fsummary>Adds a host key to the set of trusted host keys</fsummary>
+      <type>
+      <v>HostNames = string()</v>
+      <d>Description of the host that owns the <c>PublicKey</c></d>
+
+      <v>Key = public_key() </v>
+      <d> Normally an RSA or DSA public key but handling of other public keys can be added</d>
+
+      <v>ConnectOptions = proplists:proplist() </v>
+      <d>Options provided to  <seealso marker="ssh#daemon">ssh:connect/[3,4]</seealso></d>
+      <v>Reason = term() </v>
+      </type>
+      <desc>
+	 <p> Adds a host key to the set of trusted host keys</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result</name>
+      <fsummary>Checks if a host key is trusted</fsummary>
+      <type>
+	<v>Key = public_key() </v>
+	<d> Normally an RSA or DSA public key but handling of other public keys can be added</d>
+
+	<v>Host = string()</v>
+	<d>Description of the host</d>
+
+	<v>Algorithm = public_key_algorithm()</v>
+	<d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms
+	can be handled.</d>
+
+	<v> ConnectOptions = proplists:proplist() </v>
+	<d>Options provided to  <seealso marker="ssh#daemon">ssh:connect/[3,4]</seealso></d>
+
+	<v> Result = boolean()</v>
+      </type>
+      <desc>
+	<p>Checks if a host key is trusted</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:user_key(Algorithm, ConnectOptions) ->
+      {ok,  PrivateKey}  | {error, Reason}</name>
+      <fsummary>Fetches the users "public key" matching the <c>Algorithm</c>.</fsummary>
+      <type>
+	<v>Algorithm = public_key_algorithm()</v>
+	<d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms
+	can be handled.</d>
+
+	<v> ConnectOptions = proplists:proplist() </v>
+	<d>Options provided to  <seealso marker="ssh#daemon">ssh:connect/[3,4]</seealso></d>
+
+	<v> PrivateKey = private_key()</v>
+	<d> The private key of the user matching the <c>Algorithm</c></d>
+
+	<v>Reason = term() </v>
+      </type>
+
+      <desc>
+	<p>Fetches the users "public key" matching the <c>Algorithm</c>.
+	<note>The private key contains the public key</note>
+	</p>
+      </desc>
+    </func>
+
+  </funcs>
+
+</erlref>