From f7daea8abf0626e8e4df1c260223aa76c21f64b8 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 11 Oct 2018 12:44:59 +0200 Subject: 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. --- lib/ssh/doc/src/Makefile | 2 +- lib/ssh/doc/src/terminology.xml | 185 ++++++++++++++++++++++++++++++++++++++++ lib/ssh/doc/src/usersguide.xml | 1 + 3 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 lib/ssh/doc/src/terminology.xml (limited to 'lib') diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile index 77fa356092..07d4b24913 100644 --- a/lib/ssh/doc/src/Makefile +++ b/lib/ssh/doc/src/Makefile @@ -56,8 +56,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/terminology.xml b/lib/ssh/doc/src/terminology.xml new file mode 100644 index 0000000000..874a03b36e --- /dev/null +++ b/lib/ssh/doc/src/terminology.xml @@ -0,0 +1,185 @@ + + + + +
+ + 2018 + 2018 + Ericsson AB. All Rights Reserved. + + + 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. + + + + Terminology + + + + + + terminology.xml +
+ +
+ General Information +

In the following terms that may cause confusion are explained. +

+
+ +
+ The term "user" +

A "user" is a term that everyone understands intuitively. However, the understandings may differ which can + cause confusion. +

+

The term is used differently in OpenSSH and SSH in Erlang/OTP. + The reason is the different environments and use cases that are not immediatly obvious. +

+

This chapter aims at explaining the differences and giving a rationale for why Erlang/OTP handles "user" as + it does. +

+ +
+ In OpenSSH +

Many have been in contact with the command 'ssh' on a Linux machine (or similar) to remotly log in on + another machine. One types +

+ ssh host +

to log in on the machine named host. The command prompts for your password on the remote host and + then you can read, write and execute as your user name has rights on the remote host. There are + stronger variants with pre-distributed keys or certificates, but that are for now just details in the + authentication process. +

+

You could log in as the user anotheruser with +

+ ssh anotheruser@host +

and you will then be enabled to act as anotheruser on the host if authorized correctly. +

+

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 ($HOME) and there is a $HOME/.ssh/ directory + with ssh-specific files. +

+
+ SSH password authentication +

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. +

+
+
+ SSH public key authentication +

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: +

+ + That the user has a home directory, + that home directory contains a .ssh/ directory and + the .ssh/ directory contains the public key just received in the authorized_keys file + +

if so, the user is authorized. +

+
+
+ The SSH server on UNIX/Linux/etc after a succesful authentication +

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. +

+
+
+ +
+ In Erlang/OTP SSH +

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. +

+
+ Password authentication in Erlang SSH +

The Erlang/OTP SSH server checks the user name and password in the following order: +

+ + If a + pwdfun + is defined, that one is called and the returned boolean is the authentication result. + + Else, if the + user_passwords + option is defined and the username and the password matches, the authentication is a success. + + Else, if the option + password + 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. + + +
+
+ Public key authentication in Erlang SSH +

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): +

+ + A callback module is selected using the options + key_cb. + + 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 authorized_keys and authorized_keys2 + are searched in a directory found in the following order: + + If the option + user_dir_fun + is defined, that fun is called and the returned directory is used, + + Else, If the option + user_dir + is defined, that directory is used, + + Else the subdirectory .ssh in the home directory of the user executing + the OS process of the Erlang emulator is used. + + + If the provided public key is not found, the authentication fails. + + Finally, if the provided public key is found, the signature provided by the client is checked with + the public key. + + +
+
+ The Erlang/OTP SSH server after a succesful authentication +

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. +

+
+
+
+ + 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 @@ + -- cgit v1.2.3 From 6213652225bca4199bae301041f2b56d21b4eed4 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Fri, 12 Oct 2018 12:39:07 +0200 Subject: 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. --- lib/ssh/doc/src/Makefile | 1 + lib/ssh/doc/src/ref_man.xml | 1 + lib/ssh/doc/src/specs.xml | 1 + lib/ssh/doc/src/ssh_file.xml | 214 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 217 insertions(+) create mode 100644 lib/ssh/doc/src/ssh_file.xml (limited to 'lib') diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile index 07d4b24913..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 \ 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 @@ + 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 @@ + 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 @@ + + + + +
+ + 20182018 + Ericsson AB. All Rights Reserved. + + + 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. + + + + ssh_file + + + + +
+ ssh_file + 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. +

+

+ 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 + ). +

+
+ +
+ Files, directories and conventions + + + + LOCALUSER + The user name of the OS process running the Erlang virtual machine (emulator). +

+ + SYSDIR + SYSDIR 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. +

+ + + 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) + 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. + See also the user_dir common option. +

+ + +
+ + + + host_key(Algorithm, DaemonOptions) -> {ok, Key} | {error, Reason} + + +

Types and description

+

See the api description in + ssh_server_key_api, Module:host_key/2. +

+

Options

+ + {system_dir, SYSDIR} + + + + +

Files

+ + SYSDIR/ssh_host_rsa_key + SYSDIR/ssh_host_dsa_key + SYSDIR/ssh_host_ecdsa_key + +

 

+ + + + + is_auth_key(PublicUserKey, User, DaemonOptions) -> Result + + +

Types and description

+

See the api description in + ssh_server_key_api: Module:is_auth_key/3. +

+

Options

+ + {user_dir_fun, fun(RemoteUser) -> USERDIR end} + {user_dir, USERDIR} + +

Files

+ + USERDIR/authorized_keys + USERDIR/authorized_keys2 + +

 

+ + + + + add_host_key(HostNames, PublicHostKey, ConnectOptions) -> ok | {error, Reason} + + +

Types and description

+

See the api description in + ssh_client_key_api, Module:add_host_key/3. +

+

Option

+ + {user_dir, USERDIR} + +

File

+ + USERDIR/known_hosts + +

 

+ + + + + is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result + + +

Types and description

+

See the api description in + ssh_client_key_api, Module:is_host_key/4. +

+

Option

+ + {user_dir, USERDIR} + +

File

+ + USERDIR/known_hosts + +

 

+ + + + + user_key(Algorithm, ConnectOptions) -> {ok, PrivateKey} | {error, Reason} + + +

Types and description

+

See the api description in + ssh_client_key_api, Module:user_key/2. +

+

Options

+ + {user_dir, USERDIR} + {dsa_pass_phrase, PWD} + {rsa_pass_phrase, PWD} + {ecdsa_pass_phrase, PWD} + +

Files

+ + USERDIR/id_dsa + USERDIR/id_rsa + USERDIR/id_ecdsa + + + + + + + -- cgit v1.2.3 From 6e7b3e011a7b3323804351e567ea9a1f56f233a3 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Tue, 16 Oct 2018 13:43:17 +0200 Subject: ssh: Links updated in ssh.xml --- lib/ssh/doc/src/ssh.xml | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) (limited to 'lib') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index f238bf2ca8..d256a938c5 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -502,7 +502,7 @@

- user_passwords + user_passwords

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 @@

- password + password

Provides a global password that authenticates any user.

@@ -519,7 +519,9 @@ - pwdfun with pwdfun_4() + pwdfun with + pwdfun_4() +

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 disconnect is useful for this.

 - pwdfun with pwdfun_2() + pwdfun with + pwdfun_2() +

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 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. + 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 @@ -804,7 +809,10 @@

where ... are arguments to F as in ssh_client_key_api and/or ssh_server_key_api. - The UserOptions are the options given to ssh:connect, ssh:shell or ssh:daemon. + The UserOptions are the options given to + ssh:connect, + ssh:shell or + ssh:daemon.

-- cgit v1.2.3 From 2edaee2a6e134b4792956ad8196833faaa6af43b Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 22 Oct 2018 12:40:44 +0200 Subject: ssh: Clearify a couple of options user_dir, system_dir and *_passphrase are only used in the default callback module ssh_file --- lib/ssh/doc/src/ssh.xml | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) (limited to 'lib') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index d256a938c5..e674991748 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -204,6 +204,12 @@

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. +

+ @@ -488,6 +494,12 @@ 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 @@ -741,6 +753,12 @@ 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. +

+ @@ -800,7 +818,8 @@

The Opts defaults to [] when only the Module is specified.

-

The default value of this option is {ssh_file, []}. +

The default value of this option is {ssh_file, []}. See also the manpage of + ssh_file.

A call to the call-back function F will be

-- 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 ++-- lib/ssh/src/ssh.hrl | 14 ++--- lib/ssh/src/ssh_file.erl | 15 +++++ 7 files changed, 131 insertions(+), 113 deletions(-) (limited to 'lib') 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:

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..954d5b68b6 100644 --- a/lib/ssh/src/ssh_file.erl +++ b/lib/ssh/src/ssh_file.erl @@ -39,6 +39,21 @@ 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, false | string()}. +-type user_dir_fun_common_option() :: {user_dir_fun, fun()}. +-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). -- 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 ++++++++++++++++++++++--------------------- lib/ssh/src/ssh_file.erl | 6 +- 2 files changed, 72 insertions(+), 67 deletions(-) (limited to 'lib') 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 -

 

diff --git a/lib/ssh/src/ssh_file.erl b/lib/ssh/src/ssh_file.erl index 954d5b68b6..669b0f9be2 100644 --- a/lib/ssh/src/ssh_file.erl +++ b/lib/ssh/src/ssh_file.erl @@ -46,8 +46,10 @@ ]). -type system_dir_daemon_option() :: {system_dir, string()}. --type user_dir_common_option() :: {user_dir, false | string()}. --type user_dir_fun_common_option() :: {user_dir_fun, fun()}. +-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()} . -- cgit v1.2.3