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(-) 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