Merge branch 'hans/ssh/document_user/OTP-15314' into maint

* hans/ssh/document_user/OTP-15314:
  ssh: Re-phrase and adjust the documentation (ssh_file.xml)
  ssh: Move some option's documentation to ssh_file user_dir user_dir_fun (missing previously) *_passphrase system_dir
  ssh: Clearify a couple of options user_dir, system_dir and *_passphrase are only used in the default callback module ssh_file
  ssh: Links updated in ssh.xml
  ssh: Add reference manual page for the ssh_file module
  ssh: Add new User's Guide chapter about SSH terminology The term "user" means different things in OpenSSH and in Erlang/SSH. This new chapter explains why.

11 files changed, 520 insertions, 67 deletions

diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile
index 77fa356092..4e32dd9976 100644
--- a/lib/ssh/doc/src/Makefile
+++ b/lib/ssh/doc/src/Makefile
@@ -45,6 +45,7 @@ XML_REF3_FILES = \
 	ssh_connection.xml \
 	ssh_server_channel.xml \
 	ssh_server_key_api.xml \
+	ssh_file.xml \
 	ssh_sftp.xml \
 	ssh_sftpd.xml \
 
@@ -56,8 +57,8 @@ XML_CHAPTER_FILES = \
 	notes.xml \
 	introduction.xml \
 	using_ssh.xml \
+	terminology.xml \
 	configure_algos.xml
-#	ssh_protocol.xml \
 
 BOOK_FILES = book.xml
 
diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml
index df37b0244f..60572b985b 100644
--- a/lib/ssh/doc/src/ref_man.xml
+++ b/lib/ssh/doc/src/ref_man.xml
@@ -40,6 +40,7 @@
   <xi:include href="ssh_connection.xml"/>
   <xi:include href="ssh_client_key_api.xml"/>
   <xi:include href="ssh_server_key_api.xml"/>
+  <xi:include href="ssh_file.xml"/>
   <xi:include href="ssh_sftp.xml"/>
   <xi:include href="ssh_sftpd.xml"/>
 </application>
diff --git a/lib/ssh/doc/src/specs.xml b/lib/ssh/doc/src/specs.xml
index acdbe2ddfd..a6517f3660 100644
--- a/lib/ssh/doc/src/specs.xml
+++ b/lib/ssh/doc/src/specs.xml
@@ -6,6 +6,7 @@
   <xi:include href="../specs/specs_ssh_connection.xml"/>
   <xi:include href="../specs/specs_ssh_server_channel.xml"/>
   <xi:include href="../specs/specs_ssh_server_key_api.xml"/>
+  <xi:include href="../specs/specs_ssh_file.xml"/>
   <xi:include href="../specs/specs_ssh_sftp.xml"/>
   <xi:include href="../specs/specs_ssh_sftpd.xml"/>
 </specs>
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index f238bf2ca8..b75b4a33c2 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -99,8 +99,8 @@
     </p>
 
     <p>The paths could easily be changed by options:
-    <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso> and
-    <seealso marker="#type-system_dir_daemon_option"><c>system_dir</c></seealso>.
+    <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso> and
+    <seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>.
     </p>
     <p>A completly different storage could be interfaced by writing call-back modules
     using the behaviours
@@ -123,12 +123,12 @@
 	  <item><c>ssh_host_ecdsa_key</c> and <c>ssh_host_ecdsa_key.pub</c></item>
 	</list>
 	<p>The host keys directory could be changed with the option 
-	<seealso marker="#type-system_dir_daemon_option"><c>system_dir</c></seealso>.</p>
+	<seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>.</p>
 	</item>
 	<item>Optional: one or more <i>User's public key</i> in case of <c>publickey</c> authorization.
 	Default is to store them concatenated in the file <c>.ssh/authorized_keys</c> in the user's home directory.
 	<p>The user keys directory could be changed with the option 
-	<seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>.</p>
+	<seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>.</p>
 	</item>
       </list>
     </section>
@@ -138,7 +138,7 @@
       <p>The keys and some other data are by default stored in files in the directory <c>.ssh</c>
       in the user's home directory.</p>
       <p>The directory could be changed with the option 
-      <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>.
+      <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>.
       </p>
       <list>
 	<item>Optional: a list of <i>Host public key(s)</i> for previously connected hosts. This list
@@ -192,22 +192,13 @@
 	<p>If there is no public key of a specified type available, the corresponding entry is ignored.
 	Note that the available set is dependent on the underlying cryptolib and current user's public keys.
 	</p>
-        <p>See also the option <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>
+        <p>See also the option <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
         for specifying the path to the user's keys.
 	</p>
       </desc>
     </datatype>
 
     <datatype>
-      <name name="pubkey_passphrase_client_options"/>
-      <desc>
-	<p>If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be
-	supplied with thoose options.
-	</p>
-      </desc>
-    </datatype>
-
-    <datatype>
       <name name="host_accepting_client_options"/>
       <name name="accept_hosts"/>
       <name name="fp_digest_alg"/>
@@ -220,7 +211,7 @@
             <p>This option guides the <c>connect</c> function on how to act when the connected server presents a Host 
             Key that the client has not seen before. The default is to ask the user with a question on stdio of whether to
             accept or reject the new Host Key.
-            See the option <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>
+            See the option <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
             for specifying the path to the file <c>known_hosts</c> where previously accepted Host Keys are recorded.
 	    See also the option 
 	    <seealso marker="#type-key_cb_common_option">key_cb</seealso>
@@ -276,7 +267,7 @@
 	    accept question the next time the same host is connected. If the option
 	    <seealso marker="#type-key_cb_common_option"><c>key_cb</c></seealso>
 	    is not present, the key is saved in the file "known_hosts". See option
-	    <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso> for
+	    <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso> for
 	    the location of that file.
 	    </p>
 	    <p>If <c>false</c>, the key is not saved and the key will still be unknown
@@ -478,18 +469,6 @@
       <name name="pwdfun_4"/>
       <desc>
 	<taglist>
-          <tag><marker id="type-system_dir_daemon_option"/><c>system_dir</c></tag>
-          <item>
-            <p>Sets the system directory, containing the host key files
-            that identify the host keys for <c>ssh</c>. Defaults to
-            <c>/etc/ssh</c>.</p>
-	    <p>For security reasons, this directory is normally accessible only to the root user.</p>
-	    <p>See also the option 
-	    <seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	    for the general way to handle keys.
-	    </p>
-	  </item>
-
 	  <tag><c>auth_method_kb_interactive_data</c></tag>
 	  <item>
 	    <p>Sets the text strings that the daemon sends to the client for presentation to the user when
@@ -502,7 +481,7 @@
 	    </p>
           </item>
 
-	  <tag><c>user_passwords</c></tag>
+	  <tag><marker id="option-user_passwords"/><c>user_passwords</c></tag>
 	  <item>
             <p>Provides passwords for password authentication. The passwords are used when someone tries
 	    to connect to the server and public key user-authentication fails. The option provides
@@ -510,7 +489,7 @@
 	    </p>
           </item>
 
-          <tag><c>password</c></tag>
+          <tag><marker id="option-password"/><c>password</c></tag>
           <item>
             <p>Provides a global password that authenticates any user.</p>
 	    <warning>
@@ -519,7 +498,9 @@
 	    </warning>
 	  </item>
 
-	  <tag><c>pwdfun</c> with <c>pwdfun_4()</c></tag>
+	  <tag><marker id="option-pwdfun"/><c>pwdfun</c> with 
+	  <seealso marker="#type-pwdfun_4"><c>pwdfun_4()</c></seealso>
+	  </tag>
 	  <item>
 	    <p>Provides a function for password validation. This could used for calling an external system or handeling
 	    passwords stored as hash values.
@@ -546,7 +527,9 @@
 	    can be used for this. The return value <c>disconnect</c> is useful for this.</p>
 	  </item>
 
-	  <tag><c>pwdfun</c> with <c>pwdfun_2()</c></tag>
+	  <tag><c>pwdfun</c> with
+	  <seealso marker="#type-pwdfun_2"><c>pwdfun_2()</c></seealso>
+	  </tag>
 	  <item>
 	    <p>Provides a function for password validation. This function is called with user and password
 	    as strings, and returns:</p>
@@ -725,21 +708,6 @@
     </datatype>
 
     <datatype>
-      <name name="user_dir_common_option"/>
-      <desc>
-	<p>Sets the user directory. That is, the directory containing <c>ssh</c> configuration
-	files for the user, such as 
-	<c>known_hosts</c>, <c>id_rsa</c>, <c>id_dsa</c>>, <c>id_ecdsa</c> and <c>authorized_key</c>.
-	Defaults to the directory normally referred to as <c>~/.ssh</c>.
-	</p>
-	<p>See also the option 
-	<seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	for the general way to handle keys.
-	</p>
-      </desc>
-    </datatype>
-
-    <datatype>
       <name name="profile_common_option"/>
       <desc>
 	<p>Used together with <c>ip-address</c> and <c>port</c> to
@@ -795,7 +763,8 @@
 	</p>
 	<p>The <c>Opts</c> defaults to <c>[]</c> when only the <c>Module</c> is specified.
 	</p>
-	<p>The default value of this option is <c>{ssh_file, []}</c>.
+	<p>The default value of this option is <c>{ssh_file, []}</c>. See also the manpage of
+	<seealso marker="ssh:ssh_file">ssh_file</seealso>.
 	</p>
 	<p>A call to the call-back function <c>F</c> will be</p>
 	<code>
@@ -804,7 +773,10 @@
 	<p>where <c>...</c> are arguments to <c>F</c> as in 
 	<seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and/or
 	<seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
-	The <c>UserOptions</c> are the options given to <c>ssh:connect</c>, <c>ssh:shell</c> or <c>ssh:daemon</c>.
+	The <c>UserOptions</c> are the options given to 
+	<seealso marker="ssh:ssh#connect-3">ssh:connect</seealso>,
+	<seealso marker="ssh:ssh#shell-1">ssh:shell</seealso> or
+	<seealso marker="ssh:ssh#daemon-2">ssh:daemon</seealso>.
 	</p>
 
       </desc>
diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml
index e80bb1853d..eb804e67dc 100644
--- a/lib/ssh/doc/src/ssh_app.xml
+++ b/lib/ssh/doc/src/ssh_app.xml
@@ -74,13 +74,18 @@
       <c>id_ecdsa_key</c>,
       <c>known_hosts</c>, and <c>authorized_keys</c> in ~/.ssh,
       and for the host key files in <c>/etc/ssh</c>. These locations can be changed
-      by the options <c>user_dir</c> and <c>system_dir</c>.
+      by the options
+      <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso> and
+      <seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>.
       </p>
       <p>Public key handling can also be customized through a callback module that
       implements the behaviors
       <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and
       <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
       </p>
+      <p>See also the default callback module documentation in
+      <seealso marker="ssh_file">ssh_file</seealso>.
+      </p>
 
   </section>
   <section>
diff --git a/lib/ssh/doc/src/ssh_file.xml b/lib/ssh/doc/src/ssh_file.xml
new file mode 100644
index 0000000000..ae6ba2e1d9
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_file.xml
@@ -0,0 +1,275 @@
+<?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.
+    All data, for instance key pairs, are stored in files in the normal file system. This page documents the files, where they
+    are stored and configuration options for this callback module.
+    </p>
+    <p>The intention is to be compatible with the
+    <url href="http://www.openssh.com">OpenSSH</url>
+    storage in files. Therefore it mimics directories and filenames of
+    <url href="http://www.openssh.com">OpenSSH</url>.
+    </p>
+
+    <p>Ssh_file implements the <seealso marker="ssh:ssh_server_key_api">ssh_server_key_api</seealso> and
+    the <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>
+
+    <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>Files, directories and who uses them</title>
+    <section>
+      <title>Daemons</title>
+      <p>Daemons uses all files stored in the <seealso marker="#SYSDIR">SYSDIR</seealso> directory.
+      </p>
+      <p>Optionaly, in case of <c>publickey</c> authorization, one or more of the remote user's public keys
+      in the <seealso marker="#USERDIR">USERDIR</seealso> directory are used.
+      See the files 
+      <seealso marker="#USERDIR-authorized_keys"><c>USERDIR/authorized_keys</c></seealso> and
+      <seealso marker="#USERDIR-authorized_keys2"><c>USERDIR/authorized_keys2</c></seealso>.
+      </p>
+    </section>
+
+    <section>
+      <title>Clients</title>
+      <p>Clients uses all files stored in the <seealso marker="#USERDIR">USERDIR</seealso> directory.
+      </p>
+    </section>
+
+    <section>
+      <title>Directory contents</title>
+      <taglist>
+	<tag><marker id="LOCALUSER"/>LOCALUSER</tag>
+	<item><p>The user name of the OS process running the Erlang virtual machine (emulator).</p>
+	</item>
+
+	<tag><marker id="SYSDIR"/>SYSDIR</tag>
+	<item><p>This is the directory holding the server's files:</p>
+	<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>
+	<p>For security reasons, this directory is normally accessible only to the root user.
+	</p>
+	<p>To change the SYSDIR, see the <seealso marker="#type-system_dir_daemon_option">system_dir</seealso> option.
+	</p>
+	</item>
+
+	<tag><marker id="USERDIR"/>USERDIR</tag>
+	<item><p>This is the directory holding the files:</p>
+	<list>
+	  <item><marker id="USERDIR-authorized_keys"/><c>authorized_keys</c>
+	  and, as second alternative
+	  <marker id="USERDIR-authorized_keys2"/><c>authorized_keys2</c> - 
+	  the user's public keys are stored concatenated in one of those files.
+	  </item>
+	  <item><marker id="USERDIR-known_hosts"/><c>known_hosts</c> - host keys from hosts visited
+	  concatenated. The file is created and used 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>.
+	</p>
+	<p>To change the USERDIR, see the <seealso marker="#type-user_dir_common_option">user_dir</seealso> option
+	</p>
+	</item>
+      </taglist>
+    </section>
+  </section>
+
+  <datatypes>
+    <datatype_title>Options for the default ssh_file callback module</datatype_title>
+    <datatype>
+      <name name="user_dir_common_option"/>
+      <desc>
+	<p>Sets the <seealso marker="#USERDIR">user directory</seealso>.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="user_dir_fun_common_option"/>
+      <name name="user2dir"/>
+      <desc>
+	<p>Sets the <seealso marker="#USERDIR">user directory</seealso> dynamically
+	by evaluating the <c>user2dir</c> function.
+	</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="system_dir_daemon_option"/>
+      <desc>
+        <p>Sets the <seealso marker="#SYSDIR">system directory</seealso>.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="pubkey_passphrase_client_options"/>
+      <desc>
+	<p>If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be
+	supplied with thoose options.
+	</p>
+      </desc>
+    </datatype>
+
+  </datatypes>
+
+  <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><seealso marker="#type-system_dir_daemon_option">system_dir</seealso></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>
+      </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><seealso marker="#type-user_dir_fun_common_option">user_dir_fun</seealso></item>
+	  <item><seealso marker="#type-user_dir_common_option">user_dir</seealso></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>
+      </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><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
+	</list>
+	<p><strong>File</strong></p>
+	<list>
+	  <item><seealso marker="#USERDIR-known_hosts"><c>USERDIR/known_hosts</c></seealso></item>
+	</list>
+      </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><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
+	</list>
+	<p><strong>File</strong></p>
+	<list>
+	  <item><seealso marker="#USERDIR-known_hosts"><c>USERDIR/known_hosts</c></seealso></item>
+	</list>
+      </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><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
+	  <item><seealso marker="#type-pubkey_passphrase_client_options">dsa_pass_phrase</seealso></item>
+	  <item><seealso marker="#type-pubkey_passphrase_client_options">rsa_pass_phrase</seealso></item>
+	  <item><seealso marker="#type-pubkey_passphrase_client_options">ecdsa_pass_phrase</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>
diff --git a/lib/ssh/doc/src/terminology.xml b/lib/ssh/doc/src/terminology.xml
new file mode 100644
index 0000000000..db1e08970d
--- /dev/null
+++ b/lib/ssh/doc/src/terminology.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <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>Terminology</title>
+    <prepared></prepared>
+    <docno></docno>
+    <approved></approved>
+    <date></date>
+    <rev></rev>
+    <file>terminology.xml</file>
+  </header>
+
+  <section>
+    <title>General Information</title>
+    <p>In the following terms that may cause confusion are explained.
+    </p>
+  </section>
+
+  <section>
+    <title>The term "user"</title>
+    <p>A "user" is a term that everyone understands intuitively. However, the understandings may differ which can
+       cause confusion.
+    </p>
+    <p>The term is used differently in <url href="http://www.openssh.com">OpenSSH</url> and SSH in Erlang/OTP.
+       The reason is the different environments and use cases that are not immediatly obvious.
+    </p>
+    <p>This chapter aims at explaining the differences and giving a rationale for why Erlang/OTP handles "user" as
+       it does.
+    </p>
+
+    <section>
+      <title>In OpenSSH</title>
+      <p>Many have been in contact with the command 'ssh' on a Linux machine (or similar) to remotly log in on
+      another machine. One types 
+      </p>
+      <code>ssh host</code>
+      <p>to log in on the machine named <c>host</c>. The command prompts for your password on the remote <c>host</c> and
+      then you can read, write and execute as your <i>user name</i> has rights on the remote <c>host</c>. There are
+      stronger variants with pre-distributed keys or certificates, but that are for now just details in the
+      authentication process.
+      </p>
+      <p>You could log in as the user <c>anotheruser</c> with
+      </p>
+      <code>ssh anotheruser@host</code>
+      <p>and you will then be enabled to act as <c>anotheruser</c> on the <c>host</c> if authorized correctly.
+      </p>
+      <p>So what does <i>"your user name has rights"</i> mean? In a UNIX/Linux/etc context it is exactly as that context:
+      The <i>user</i> could read, write and execute programs according to the OS rules.
+      In addition, the user has a home directory (<c>$HOME</c>) and there is a <c>$HOME/.ssh/</c> directory
+      with ssh-specific files.
+      </p>
+      <section>
+	<title>SSH password authentication</title>
+	<p>When SSH tries to log in to a host, the ssh protocol communicates the user name (as a string) and a password.
+	The remote ssh server checks that there is such a user defined and that the provided password is acceptable.
+	</p>
+	<p>If so, the user is authorized.
+	</p>
+      </section>
+      <section>
+	<title>SSH public key authentication</title>
+	<p>This is a stronger method where the ssh protocol brings the user name, the user's public key and some
+	cryptographic information which we could ignore here.
+	</p>
+	<p>The ssh server on the remote host checks:
+	</p>
+	<list>
+	  <item>That the <i>user</i> has a home directory,</item>
+	  <item>that home directory contains a .ssh/ directory and</item>
+	  <item>the .ssh/ directory contains the public key just received in the <c>authorized_keys</c> file</item>
+	</list>
+	<p>if so, the user is authorized.
+	</p>
+      </section>
+      <section>
+	<title>The SSH server on UNIX/Linux/etc after a succesful authentication</title>
+	<p>After a succesful incoming authentication, a new process runs as the just authenticated user.</p>
+	<p>Next step is to start a service according to the ssh request. In case of a request of a shell, 
+	a new one is started which handles the OS-commands that arrives from the client (that's "you").
+	</p>
+	<p>In case of a sftp request, an sftp server is started in with the user's rights. So it could read, write or delete
+	files if allowed for that user.
+	</p>
+      </section>
+    </section>
+
+    <section>
+      <title>In Erlang/OTP SSH</title>
+      <p>For the Erlang/OTP SSH server the situation is different. The server executes in an Erlang process
+      in the Erlang emulator which in turn executes in an OS process. The emulator does not try to change its
+      user when authenticated over the SSH protocol.
+      So the remote user name is only for authentication purposes in the Erlang/OTP SSH application.
+      </p>
+      <section>
+	<title>Password authentication in Erlang SSH</title>
+	<p>The Erlang/OTP SSH server checks the user name and password in the following order:
+	</p>
+	<list type="ordered">
+	  <item>If a 
+	  <seealso marker="ssh:ssh#option-pwdfun"><c>pwdfun</c></seealso>
+	  is defined, that one is called and the returned boolean is the authentication result.
+	  </item>
+	  <item>Else, if the 
+	  <seealso marker="ssh:ssh#option-user_passwords"><c>user_passwords</c></seealso>
+	  option is defined and the username and the password matches, the authentication is a success.
+	  </item>
+	  <item>Else, if the option 
+	  <seealso marker="ssh:ssh#option-password"><c>password</c></seealso>
+	  is defined and matches the password the authentication is a success.
+	  Note that the use of this option is not recommended in non-test code.
+	  </item>
+	</list>
+      </section>
+      <section>
+	<title>Public key authentication in Erlang SSH</title>
+	<p>The user name, public key and cryptographic data (a signature) that is sent by the client, are used as follows
+	(some steps left out for clearity):
+	</p>
+	<list type="ordered">
+	  <item>A callback module is selected using the options 
+	  <seealso marker="ssh:ssh#type-key_cb_common_option"><c>key_cb</c></seealso>.
+	  </item>
+	  <item>The callback module is used to check that the provided public key is one of the user's pre-stored.
+	        In case of the default callback module, the files <c>authorized_keys</c> and <c>authorized_keys2</c>
+		are searched in a directory found in the following order:
+		<list>
+		  <item>If the option
+		  <seealso marker="ssh:ssh_file#type-user_dir_fun_common_option"><c>user_dir_fun</c></seealso>
+		  is defined, that fun is called and the returned directory is used,
+		  </item>
+		  <item>Else, If the option 
+		  <seealso marker="ssh:ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
+			is defined, that directory is used,
+		  </item>
+		  <item>Else the subdirectory <c>.ssh</c> in the home directory of the user executing
+		  the OS process of the Erlang emulator is used.
+		  </item>
+		</list>
+		If the provided public key is not found, the authentication fails.
+	  </item>
+	  <item>Finally, if the provided public key is found, the signature provided by the client is checked with
+	  the public key.
+	  </item>
+	</list>
+      </section>
+      <section>
+	<title>The Erlang/OTP SSH server after a succesful authentication</title>
+	<p>After a successful authentication an <i>Erlang process</i> is handling the service request from the remote
+	ssh client. The rights of that process are those of the user of the OS process running the Erlang emulator.
+	</p>
+	<p>If a shell service request arrives to the server, an <i>Erlang shell</i> is opened in the server's emulator.
+	The rights in that shell is independent of the just authenticated user.
+	</p>
+	<p>In case of an sftp request, an sftp server is started with the rights of the user of the Erlang emulator's OS
+	process. So with sftp the authenticated user does not influence the rights.
+	</p>
+	<p>So after an authentication, the user name is not used anymore and has no influence.
+	</p>
+      </section>
+    </section>
+  </section>
+</chapter>
+	
diff --git a/lib/ssh/doc/src/usersguide.xml b/lib/ssh/doc/src/usersguide.xml
index 38ffa48cde..8a4df208d8 100644
--- a/lib/ssh/doc/src/usersguide.xml
+++ b/lib/ssh/doc/src/usersguide.xml
@@ -36,5 +36,6 @@
   </description>
   <xi:include href="introduction.xml"/>
   <xi:include href="using_ssh.xml"/>
+  <xi:include href="terminology.xml"/>
   <xi:include href="configure_algos.xml"/>
 </part>
diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
index 80662e9a70..4455d5ecc5 100644
--- a/lib/ssh/doc/src/using_ssh.xml
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -74,16 +74,17 @@
     <marker id="Running an Erlang ssh Daemon"></marker>
     <title>Running an Erlang ssh Daemon</title>
 
-    <p>The <c>system_dir</c> option must be a directory containing a host
-    key file and it defaults to <c>/etc/ssh</c>. For details, see Section
-    Configuration Files in <seealso
-    marker="SSH_app">ssh(6)</seealso>.
+    <p>The
+    <seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>
+    option must be a directory containing a host key file and it defaults to <c>/etc/ssh</c>.
+    For details, see Section Configuration Files in <seealso marker="SSH_app">ssh(6)</seealso>.
     </p>
 
     <note><p>Normally, the <c>/etc/ssh</c> directory is only readable by root.</p>
     </note>
 
-    <p>The option <c>user_dir</c> defaults to directory <c>users ~/.ssh</c>.</p>
+    <p>The option <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
+    defaults to directory <c>users ~/.ssh</c>.</p>
 
     <p><em>Step 1.</em> To run the example without root privileges,
     generate new keys and host keys:</p>
diff --git a/lib/ssh/src/ssh.hrl b/lib/ssh/src/ssh.hrl
index 94b9f3a196..3ac74c4925 100644
--- a/lib/ssh/src/ssh.hrl
+++ b/lib/ssh/src/ssh.hrl
@@ -173,7 +173,7 @@
 
 -type common_options() :: [ common_option() ].
 -type common_option() :: 
-        user_dir_common_option()
+        ssh_file:user_dir_common_option()
       | profile_common_option()
       | max_idle_time_common_option()
       | key_cb_common_option()
@@ -191,8 +191,6 @@
 
 -define(COMMON_OPTION, common_option()).
 
-
--type user_dir_common_option()      :: {user_dir,  false | string()}.
 -type profile_common_option()       :: {profile,   atom() }.
 -type max_idle_time_common_option() :: {idle_time, timeout()}.
 -type rekey_limit_common_option()   :: {rekey_limit, Bytes::limit_bytes() |
@@ -223,14 +221,14 @@
         {transport, {atom(),atom(),atom()} }
       | {vsn, {non_neg_integer(),non_neg_integer()} }
       | {tstflg, list(term())}
-      | {user_dir_fun, fun()}
+      | ssh_file:user_dir_fun_common_option()
       | {max_random_length_padding, non_neg_integer()} .
 
 
 
 -type client_option()         ::
         pref_public_key_algs_client_option()
-      | pubkey_passphrase_client_options()
+      | ssh_file:pubkey_passphrase_client_options()
       | host_accepting_client_options()
       | authentication_client_options()
       | diffie_hellman_group_exchange_client_option()
@@ -246,10 +244,6 @@
 
 -type pref_public_key_algs_client_option() :: {pref_public_key_algs, [pubkey_alg()] } .
 
--type pubkey_passphrase_client_options() ::   {dsa_pass_phrase,      string()}
-                                            | {rsa_pass_phrase,      string()}
-                                            | {ecdsa_pass_phrase,    string()} .
-
 -type host_accepting_client_options() ::
         {silently_accept_hosts, accept_hosts()}
       | {user_interaction,     boolean()}
@@ -311,7 +305,7 @@
 -type send_ext_info_daemon_option() :: {send_ext_info, boolean()} .
 
 -type authentication_daemon_options() ::
-        {system_dir, string()}
+        ssh_file:system_dir_daemon_option()
       | {auth_method_kb_interactive_data, prompt_texts() }
       | {user_passwords, [{UserName::string(),Pwd::string()}]}
       | {password, string()}
diff --git a/lib/ssh/src/ssh_file.erl b/lib/ssh/src/ssh_file.erl
index 832952ed52..669b0f9be2 100644
--- a/lib/ssh/src/ssh_file.erl
+++ b/lib/ssh/src/ssh_file.erl
@@ -39,6 +39,23 @@
 	 is_auth_key/3]).
 
 
+-export_type([system_dir_daemon_option/0,
+              user_dir_common_option/0,
+              user_dir_fun_common_option/0,
+              pubkey_passphrase_client_options/0
+             ]).
+
+-type system_dir_daemon_option()   :: {system_dir, string()}.
+-type user_dir_common_option()     :: {user_dir,  string()}.
+-type user_dir_fun_common_option() :: {user_dir_fun, user2dir()}.
+-type user2dir() :: fun((RemoteUserName::string()) -> UserDir :: string()) .
+
+-type pubkey_passphrase_client_options() ::   {dsa_pass_phrase,      string()}
+                                            | {rsa_pass_phrase,      string()}
+                                            | {ecdsa_pass_phrase,    string()} .
+
+
+
 -define(PERM_700, 8#700).
 -define(PERM_644, 8#644).