ssh: Add reference manual page for the ssh_file module

This callback module has the knowledge about the different files
used by Erlang/OTP SSH.

It was unfortunatly not documented previously.

1 files changed, 214 insertions, 0 deletions

diff --git a/lib/ssh/doc/src/ssh_file.xml b/lib/ssh/doc/src/ssh_file.xml
new file mode 100644
index 0000000000..910c6698fc
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_file.xml
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2018</year><year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+      
+      http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+    
+    <title>ssh_file</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>ssh_file</module>
+  <modulesummary>Default callback module for the client's and server's database operations in the ssh application</modulesummary>
+  <description>
+    <p>This module is the default callback handler for the client's and the server's user and host "database" operations.
+    </p>
+    <p>
+      The intention is to be compatible with the OpenSSH storage in files. Therefore it mimics directories and filenames
+      of OpenSSH.
+    </p>
+    <note>
+      <p>The functions are <i>Callbacks</i> for the SSH app. They are not intended to be called from the user's code!
+      </p>
+    </note>
+  </description>
+    <section>
+      <title>Making your own callback module</title>
+      <p>Ssh_file implements the <seealso marker="ssh:ssh_server_key_api">ssh_server_key_api</seealso> and
+      <seealso marker="ssh:ssh_client_key_api">ssh_client_key_api</seealso>.
+	This enables the user to make an own interface using for example a database handler.
+      </p>
+      <p>Such another callback module could be used by setting the option
+      <seealso marker="ssh:ssh#type-key_cb_common_option"><c>key_cb</c></seealso>
+      when starting a client or a server (with for example
+      <seealso marker="ssh:ssh#connect-3">ssh:connect</seealso>,
+      <seealso marker="ssh:ssh#daemon-2">ssh:daemon</seealso> of
+      <seealso marker="ssh:ssh#shell-1">ssh:shell</seealso>
+      ).
+      </p>
+    </section>
+
+  <section>
+    <title>Files, directories and conventions</title>
+    <taglist>
+      <!--tag><marker id="REMOTEUSER"/>REMOTEUSER</tag>
+      <item>The user name sent by the client to the server.
+      <p/></item-->
+
+      <tag><marker id="LOCALUSER"/>LOCALUSER</tag>
+      <item>The user name of the OS process running the Erlang virtual machine (emulator).
+      <p/></item>
+
+      <tag><marker id="SYSDIR"/>SYSDIR</tag>
+      <item>SYSDIR is the directory holding the server's files:
+      <list>
+	  <item><marker id="SYSDIR-ssh_host_dsa_key"/><c>ssh_host_dsa_key</c> - private dss host key (optional)</item>
+	  <item><marker id="SYSDIR-ssh_host_rsa_key"/><c>ssh_host_rsa_key</c> - private rsa host key (optional)</item>
+	  <item><marker id="SYSDIR-ssh_host_ecdsa_key"/><c>ssh_host_ecdsa_key</c> - private ecdsa host key (optional)</item>
+      </list>
+      <p>At least one host key must be defined. The default value of SYSDIR is <marker id="#/etc/ssh"/><c>/etc/ssh</c>.
+      </p>
+      </item>
+
+      <tag><marker id="USERDIR"/>USERDIR</tag>
+      <item>USERDIR is the directory holding the files:
+      <list>
+	  <item><marker id="USERDIR-authorized_keys"/><c>authorized_keys</c> - list of keys allowed in public_key authorization (optional)</item>
+	  <item><marker id="USERDIR-authorized_keys2"/><c>authorized_keys2</c> - list of keys allowed in public_key authorization (optional and unusual)</item>
+	  <item><marker id="USERDIR-known_hosts"/><c>known_hosts</c> - list of hosts visited (created by the client)</item>
+	  <item><marker id="USERDIR-id_dsa"/><c>id_dsa</c> - private dss user key (optional)</item>
+	  <item><marker id="USERDIR-id_rsa"/><c>id_rsa</c> - private rsa user key (optional)</item>
+	  <item><marker id="USERDIR-id_ecdsa"/><c>id_ecdsa</c> - private ecdsa user key (optional)</item>
+      </list>
+      <p>The default value of USERDIR is <c>/home/</c><seealso marker="#LOCALUSER"><c>LOCALUSER</c></seealso><c>/.ssh</c>.
+      See also the <seealso marker="ssh:ssh#type-user_dir_common_option">user_dir</seealso> common option.
+      </p></item>
+      
+    </taglist>
+  </section>
+
+  <funcs>
+    <func>
+      <name>host_key(Algorithm, DaemonOptions) -> {ok, Key} | {error, Reason}</name>
+      <fsummary></fsummary>
+      <desc>
+	<p><strong>Types and description</strong></p>
+	<p>See the api description in
+	<seealso marker="ssh:ssh_server_key_api#Module:host_key-2">ssh_server_key_api, Module:host_key/2</seealso>.
+	</p>
+	<p><strong>Options</strong></p>
+	<list>
+	  <item><c>{system_dir, </c><seealso marker="#SYSDIR">SYSDIR</seealso><c>}</c></item>
+	  <!-- item>dsa_pass_phrase</item -->
+	  <!-- item>rsa_pass_phrase</item -->
+	  <!-- item>ecdsa_pass_phrase</item -->
+	</list>
+	<p><strong>Files</strong></p>
+	<list>
+	  <item><seealso marker="#SYSDIR-ssh_host_rsa_key"><c>SYSDIR/ssh_host_rsa_key</c></seealso></item>
+	  <item><seealso marker="#SYSDIR-ssh_host_dsa_key"><c>SYSDIR/ssh_host_dsa_key</c></seealso></item>
+	  <item><seealso marker="#SYSDIR-ssh_host_ecdsa_key"><c>SYSDIR/ssh_host_ecdsa_key</c></seealso></item>
+	</list>
+	<p>&nbsp;</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>is_auth_key(PublicUserKey, User, DaemonOptions) -> Result</name>
+      <fsummary></fsummary>
+      <desc>
+	<p><strong>Types and description</strong></p>
+	<p>See the api description in
+	<seealso marker="ssh:ssh_server_key_api#Module:is_auth_key-3">ssh_server_key_api: Module:is_auth_key/3</seealso>.
+	</p>
+	<p><strong>Options</strong></p>
+	<list>
+	  <item><marker id="user_dir_fun"/><c>{user_dir_fun, fun(RemoteUser) -> USERDIR end}</c></item>
+	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	</list>
+	<p><strong>Files</strong></p>
+	<list>
+	  <item><seealso marker="#USERDIR-authorized_keys"><c>USERDIR/authorized_keys</c></seealso></item>
+	  <item><seealso marker="#USERDIR-authorized_keys2"><c>USERDIR/authorized_keys2</c></seealso></item>
+	</list>
+	<p>&nbsp;</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>add_host_key(HostNames, PublicHostKey, ConnectOptions) -> ok | {error, Reason}</name>
+      <fsummary></fsummary>
+      <desc>
+	<p><strong>Types and description</strong></p>
+	<p>See the api description in
+	<seealso marker="ssh:ssh_client_key_api#Module:add_host_key-3">ssh_client_key_api, Module:add_host_key/3</seealso>.
+	</p>
+	<p><strong>Option</strong></p>
+	<list>
+	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	</list>
+	<p><strong>File</strong></p>
+	<list>
+	  <item><seealso marker="#USERDIR-known_hosts"><c>USERDIR/known_hosts</c></seealso></item>
+	</list>
+	<p>&nbsp;</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result</name>
+      <fsummary></fsummary>
+      <desc>
+	<p><strong>Types and description</strong></p>
+	<p>See the api description in
+	<seealso marker="ssh:ssh_client_key_api#Module:is_host_key-4">ssh_client_key_api, Module:is_host_key/4</seealso>.
+	</p>
+	<p><strong>Option</strong></p>
+	<list>
+	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	</list>
+	<p><strong>File</strong></p>
+	<list>
+	  <item><seealso marker="#USERDIR-known_hosts"><c>USERDIR/known_hosts</c></seealso></item>
+	</list>
+	<p>&nbsp;</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>user_key(Algorithm, ConnectOptions) -> {ok, PrivateKey} | {error, Reason}</name>
+      <fsummary></fsummary>
+      <desc>
+	<p><strong>Types and description</strong></p>
+	<p>See the api description in
+	<seealso marker="ssh:ssh_client_key_api#Module:user_key-2">ssh_client_key_api, Module:user_key/2</seealso>.
+	</p>
+	<p><strong>Options</strong></p>
+	<list>
+	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	  <item><seealso marker="ssh:ssh#type-pubkey_passphrase_client_options"><c>{dsa_pass_phrase, PWD}</c></seealso></item>
+	  <item><seealso marker="ssh:ssh#type-pubkey_passphrase_client_options"><c>{rsa_pass_phrase, PWD}</c></seealso></item>
+	  <item><seealso marker="ssh:ssh#type-pubkey_passphrase_client_options"><c>{ecdsa_pass_phrase, PWD}</c></seealso></item>
+	</list>
+	<p><strong>Files</strong></p>
+	<list>
+	  <item><seealso marker="#USERDIR-id_dsa"><c>USERDIR/id_dsa</c></seealso></item>
+	  <item><seealso marker="#USERDIR-id_rsa"><c>USERDIR/id_rsa</c></seealso></item>
+	  <item><seealso marker="#USERDIR-id_ecdsa"><c>USERDIR/id_ecdsa</c></seealso></item>
+	</list>
+      </desc>
+    </func>
+
+  </funcs>
+
+</erlref>