From f7daea8abf0626e8e4df1c260223aa76c21f64b8 Mon Sep 17 00:00:00 2001
From: Hans Nilsson In the following terms that may cause confusion are explained.
+ A "user" is a term that everyone understands intuitively. However, the understandings may differ which can
+ cause confusion.
+ The term is used differently in This chapter aims at explaining the differences and giving a rationale for why Erlang/OTP handles "user" as
+ it does.
+ Many have been in contact with the command 'ssh' on a Linux machine (or similar) to remotly log in on
+ another machine. One types
+ to log in on the machine named You could log in as the user and you will then be enabled to act as So what does "your user name has rights" mean? In a UNIX/Linux/etc context it is exactly as that context:
+ The user could read, write and execute programs according to the OS rules.
+ In addition, the user has a home directory ( 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.
+ If so, the user is authorized.
+ 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.
+ The ssh server on the remote host checks:
+ if so, the user is authorized.
+ After a succesful incoming authentication, a new process runs as the just authenticated user. 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").
+ 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.
+ 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.
+ The Erlang/OTP SSH server checks the user name and password in the following order:
+ 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):
+ After a successful authentication an Erlang process 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.
+ If a shell service request arrives to the server, an Erlang shell is opened in the server's emulator.
+ The rights in that shell is independent of the just authenticated user.
+ 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.
+ So after an authentication, the user name is not used anymore and has no influence.
+ This module is the default callback handler for the client's and the server's user and host "database" operations.
+
+ The intention is to be compatible with the OpenSSH storage in files. Therefore it mimics directories and filenames
+ of OpenSSH.
+ The functions are Callbacks for the SSH app. They are not intended to be called from the user's code!
+ Ssh_file implements the Such another callback module could be used by setting the option
+ At least one host key must be defined. The default value of SYSDIR is The default value of USERDIR is Types and description See the api description in
+ Options Files Types and description See the api description in
+ Options Files Types and description See the api description in
+ Option File Types and description See the api description in
+ Option File Types and description See the api description in
+ Options Filesssh host
+ ssh anotheruser@host
+
+
+
+
+
+
+
+
+ If the provided public key is not found, the authentication fails.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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 +510,7 @@
Provides a global password that authenticates any user.
Provides a function for password validation. This could used for calling an external system or handeling
passwords stored as hash values.
@@ -546,7 +548,9 @@
can be used for this. The return value
Provides a function for password validation. This function is called with user and password as strings, and returns:
@@ -730,7 +734,8 @@Sets the user directory. That is, the directory containing
See also the option
where
If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be supplied with thoose options.
+Those options can only be used if the module in
+
This option can only be used if the module in
+
This option can only be used if the module in
+
The
The default value of this option is
The default value of this option is
A call to the call-back function
--
cgit v1.2.3
From d655a343837f4a05ca7a9683d57245734d7482ac Mon Sep 17 00:00:00 2001
From: Hans Nilsson
Date: Mon, 22 Oct 2018 16:12:02 +0200
Subject: ssh: Move some option's documentation to ssh_file user_dir
user_dir_fun (missing previously) *_passphrase system_dir
---
lib/ssh/doc/src/ssh.xml | 71 +++--------------------
lib/ssh/doc/src/ssh_app.xml | 7 ++-
lib/ssh/doc/src/ssh_file.xml | 122 +++++++++++++++++++++++++++++-----------
lib/ssh/doc/src/terminology.xml | 4 +-
lib/ssh/doc/src/using_ssh.xml | 11 ++--
5 files changed, 112 insertions(+), 103 deletions(-)
(limited to 'lib/ssh/doc/src')
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index e674991748..b75b4a33c2 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -99,8 +99,8 @@
The paths could easily be changed by options:
- user_dir and
- system_dir .
+ user_dir and
+ system_dir .
A completly different storage could be interfaced by writing call-back modules
using the behaviours
@@ -123,12 +123,12 @@
ssh_host_ecdsa_key and ssh_host_ecdsa_key.pub
The host keys directory could be changed with the option
- system_dir .
+ system_dir .
- Optional: one or more User's public key in case of
publickey authorization.
Default is to store them concatenated in the file .ssh/authorized_keys in the user's home directory.
The user keys directory could be changed with the option
- user_dir .
+ user_dir .
@@ -138,7 +138,7 @@
The keys and some other data are by default stored in files in the directory .ssh
in the user's home directory.
The directory could be changed with the option
- user_dir .
+ user_dir .
- Optional: a list of Host public key(s) for previously connected hosts. This list
@@ -192,27 +192,12 @@
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.
- See also the option user_dir
+
See also the option user_dir
for specifying the path to the user's keys.
-
-
-
- If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be
- supplied with thoose options.
-
-
- Those options can only be used if the module in
- key_cb
- handles that option. That is the case with the default value of the key_cb option.
-
-
-
-
-
@@ -226,7 +211,7 @@
This option guides the connect 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 user_dir
+ See the option user_dir
for specifying the path to the file known_hosts where previously accepted Host Keys are recorded.
See also the option
key_cb
@@ -282,7 +267,7 @@
accept question the next time the same host is connected. If the option
key_cb
is not present, the key is saved in the file "known_hosts". See option
- user_dir for
+ user_dir for
the location of that file.
If false , the key is not saved and the key will still be unknown
@@ -484,24 +469,6 @@
- system_dir
- -
-
Sets the system directory, containing the host key files
- that identify the host keys for ssh . Defaults to
- /etc/ssh .
- For security reasons, this directory is normally accessible only to the root user.
- See also the option
- key_cb
- for the general way to handle keys.
-
-
- This option can only be used if the module in
- key_cb
- handles that option. That is the case with the default value of the key_cb option.
-
-
-
-
auth_method_kb_interactive_data
-
Sets the text strings that the daemon sends to the client for presentation to the user when
@@ -740,28 +707,6 @@
-
-
-
- Sets the user directory. That is, the directory containing ssh configuration
- files for the user, such as
- known_hosts , id_rsa , id_dsa >, id_ecdsa and authorized_key .
- Defaults to the directory normally referred to as ~/.ssh where ~ is the home directory of the user
- that the Erlang executes as.
-
- See also the option
- key_cb
- for the general way to handle keys.
-
-
- This option can only be used if the module in
- key_cb
- handles that option. That is the case with the default value of the key_cb option.
-
-
-
-
-
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 @@
id_ecdsa_key ,
known_hosts , and authorized_keys in ~/.ssh,
and for the host key files in /etc/ssh . These locations can be changed
- by the options user_dir and system_dir .
+ by the options
+ user_dir and
+ system_dir .
Public key handling can also be customized through a callback module that
implements the behaviors
ssh_client_key_api and
ssh_server_key_api .
+ See also the default callback module documentation in
+ ssh_file .
+
diff --git a/lib/ssh/doc/src/ssh_file.xml b/lib/ssh/doc/src/ssh_file.xml
index 910c6698fc..20dcb86fd6 100644
--- a/lib/ssh/doc/src/ssh_file.xml
+++ b/lib/ssh/doc/src/ssh_file.xml
@@ -34,37 +34,52 @@
This module is the default callback handler for the client's and the server's user and host "database" operations.
- The intention is to be compatible with the OpenSSH storage in files. Therefore it mimics directories and filenames
- of OpenSSH.
+ The intention is to be compatible with the
+ OpenSSH
+ storage in files. Therefore it mimics directories and filenames of
+ OpenSSH .
The functions are Callbacks for the SSH app. They are not intended to be called from the user's code!
-
- Making your own callback module
- Ssh_file implements the ssh_server_key_api and
- ssh_client_key_api .
- This enables the user to make an own interface using for example a database handler.
-
- Such another callback module could be used by setting the option
- key_cb
- when starting a client or a server (with for example
- ssh:connect ,
- ssh:daemon of
- ssh:shell
- ).
-
-
+
+ Making your own callback module
+ Ssh_file implements the ssh_server_key_api and
+ ssh_client_key_api .
+ This enables the user to make an own interface using for example a database handler.
+
+ Such another callback module could be used by setting the option
+ key_cb
+ when starting a client or a server (with for example
+ ssh:connect ,
+ ssh:daemon of
+ ssh:shell
+ ).
+
+
+
+
+ Daemons
+ Daemons uses all files stored in the SYSDIR directory and
+ optionaly one or more User's public key in case of publickey authorization.
+ The user's public keys are stored concatenated in the file
+ authorized_keys
+ in the
+ USERDIR directory.
+
+
+
+
+ Clients
+ Clients uses all files stored in the USERDIR directory.
+
+
Files, directories and conventions
-
-
LOCALUSER
- The user name of the OS process running the Erlang virtual machine (emulator).
@@ -78,6 +93,10 @@
At least one host key must be defined. The default value of SYSDIR is /etc/ssh .
+ For security reasons, this directory is normally accessible only to the root user.
+
+ To change the SYSDIR, see the system_dir option.
+
USERDIR
@@ -91,12 +110,51 @@
id_ecdsa - private ecdsa user key (optional)
The default value of USERDIR is /home/ LOCALUSER /.ssh .
- See also the user_dir common option.
-
+
+ To change the USERDIR, see the user_dir option
+
+
+
+ Options for the default ssh_file callback module
+
+
+
+ Sets the user directory .
+
+
+
+
+
+
+ Sets the user directory dynamically
+ by evaluating the function
+
+ fun(RemoteUser) -> USERDIR end
+
+
+
+
+
+
+ Sets the system directory .
+
+
+
+
+
+
+ If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be
+ supplied with thoose options.
+
+
+
+
+
+
host_key(Algorithm, DaemonOptions) -> {ok, Key} | {error, Reason}
@@ -108,7 +166,7 @@
Options
- {system_dir, SYSDIR }
+ system_dir
@@ -133,8 +191,8 @@
Options
- {user_dir_fun, fun(RemoteUser) -> USERDIR end}
- {user_dir, USERDIR }
+ user_dir_fun
+ user_dir
Files
@@ -155,7 +213,7 @@
Option
- {user_dir, USERDIR }
+ user_dir
File
@@ -175,7 +233,7 @@
Option
- {user_dir, USERDIR }
+ user_dir
File
@@ -195,10 +253,10 @@
Options
- {user_dir, USERDIR }
- {dsa_pass_phrase, PWD}
- {rsa_pass_phrase, PWD}
- {ecdsa_pass_phrase, PWD}
+ user_dir
+ dsa_pass_phrase
+ rsa_pass_phrase
+ ecdsa_pass_phrase
Files
diff --git a/lib/ssh/doc/src/terminology.xml b/lib/ssh/doc/src/terminology.xml
index 874a03b36e..db1e08970d 100644
--- a/lib/ssh/doc/src/terminology.xml
+++ b/lib/ssh/doc/src/terminology.xml
@@ -147,11 +147,11 @@
are searched in a directory found in the following order:
- If the option
-
user_dir_fun
+ user_dir_fun
is defined, that fun is called and the returned directory is used,
- Else, If the option
-
user_dir
+ user_dir
is defined, that directory is used,
- Else the subdirectory
.ssh in the home directory of the user executing
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 @@
Running an Erlang ssh Daemon
- The system_dir option must be a directory containing a host
- key file and it defaults to /etc/ssh . For details, see Section
- Configuration Files in ssh(6) .
+
The
+ system_dir
+ option must be a directory containing a host key file and it defaults to /etc/ssh .
+ For details, see Section Configuration Files in ssh(6) .
Normally, the /etc/ssh directory is only readable by root.
- The option user_dir defaults to directory users ~/.ssh .
+ The option user_dir
+ defaults to directory users ~/.ssh .
Step 1. To run the example without root privileges,
generate new keys and host keys:
--
cgit v1.2.3
From 4f80074408ca5d21a56b0b234ff7434c8d155836 Mon Sep 17 00:00:00 2001
From: Hans Nilsson
Date: Tue, 23 Oct 2018 10:42:00 +0200
Subject: ssh: Re-phrase and adjust the documentation (ssh_file.xml)
---
lib/ssh/doc/src/ssh_file.xml | 133 ++++++++++++++++++++++---------------------
1 file changed, 68 insertions(+), 65 deletions(-)
(limited to 'lib/ssh/doc/src')
diff --git a/lib/ssh/doc/src/ssh_file.xml b/lib/ssh/doc/src/ssh_file.xml
index 20dcb86fd6..ae6ba2e1d9 100644
--- a/lib/ssh/doc/src/ssh_file.xml
+++ b/lib/ssh/doc/src/ssh_file.xml
@@ -32,22 +32,17 @@
Default callback module for the client's and server's database operations in the ssh application
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.
-
- The intention is to be compatible with the
- OpenSSH
- storage in files. Therefore it mimics directories and filenames of
- OpenSSH .
+
The intention is to be compatible with the
+ OpenSSH
+ storage in files. Therefore it mimics directories and filenames of
+ OpenSSH .
-
- The functions are Callbacks for the SSH app. They are not intended to be called from the user's code!
-
-
-
-
- Making your own callback module
+
Ssh_file implements the ssh_server_key_api and
- ssh_client_key_api .
+ the ssh_client_key_api .
This enables the user to make an own interface using for example a database handler.
Such another callback module could be used by setting the option
@@ -58,64 +53,76 @@
ssh:shell
).
-
-
- Daemons
- Daemons uses all files stored in the SYSDIR directory and
- optionaly one or more User's public key in case of publickey authorization.
- The user's public keys are stored concatenated in the file
- authorized_keys
- in the
- USERDIR directory.
-
-
+
+ The functions are Callbacks for the SSH app. They are not intended to be called from the user's code!
+
+
+
- Clients
- Clients uses all files stored in the USERDIR directory.
-
-
+ Files, directories and who uses them
+
+ Daemons
+ Daemons uses all files stored in the SYSDIR directory.
+
+ Optionaly, in case of publickey authorization, one or more of the remote user's public keys
+ in the USERDIR directory are used.
+ See the files
+ USERDIR/authorized_keys and
+ USERDIR/authorized_keys2 .
+
+
-
- Files, directories and conventions
-
- LOCALUSER
- - The user name of the OS process running the Erlang virtual machine (emulator).
-
+
+ Clients
+ Clients uses all files stored in the USERDIR directory.
+
+
- SYSDIR
- - SYSDIR is the directory holding the server's files:
-
+
+ Directory contents
+
+ LOCALUSER
+ The user name of the OS process running the Erlang virtual machine (emulator).
+
+
+ SYSDIR
+ This is the directory holding the server's files:
+
ssh_host_dsa_key - private dss host key (optional)
ssh_host_rsa_key - private rsa host key (optional)
ssh_host_ecdsa_key - private ecdsa host key (optional)
-
- At least one host key must be defined. The default value of SYSDIR is /etc/ssh .
-
- For security reasons, this directory is normally accessible only to the root user.
-
- To change the SYSDIR, see the system_dir option.
-
-
+
+ At least one host key must be defined. The default value of SYSDIR is /etc/ssh .
+
+ For security reasons, this directory is normally accessible only to the root user.
+
+ To change the SYSDIR, see the system_dir option.
+
+
- USERDIR
- - USERDIR is the directory holding the files:
-
- authorized_keys - list of keys allowed in public_key authorization (optional)
- authorized_keys2 - list of keys allowed in public_key authorization (optional and unusual)
- known_hosts - list of hosts visited (created by the client)
+ USERDIR
+ This is the directory holding the files:
+
+ authorized_keys
+ and, as second alternative
+ authorized_keys2 -
+ the user's public keys are stored concatenated in one of those files.
+
+ known_hosts - host keys from hosts visited
+ concatenated. The file is created and used by the client.
id_dsa - private dss user key (optional)
id_rsa - private rsa user key (optional)
id_ecdsa - private ecdsa user key (optional)
-
- The default value of USERDIR is /home/ LOCALUSER /.ssh .
-
- To change the USERDIR, see the user_dir option
-
-
-
-
+
+ The default value of USERDIR is /home/ LOCALUSER /.ssh .
+
+ To change the USERDIR, see the user_dir option
+
+
+
+
@@ -129,11 +136,11 @@
+
Sets the user directory dynamically
- by evaluating the function
+ by evaluating the user2dir function.
- fun(RemoteUser) -> USERDIR end
@@ -177,7 +184,6 @@
SYSDIR/ssh_host_dsa_key
SYSDIR/ssh_host_ecdsa_key
-
@@ -199,7 +205,6 @@
USERDIR/authorized_keys
USERDIR/authorized_keys2
-
@@ -219,7 +224,6 @@
USERDIR/known_hosts
-
@@ -239,7 +243,6 @@
USERDIR/known_hosts
-
--
cgit v1.2.3