ssh_file

Module Summary

Default callback module for the client's and server's database operations in the ssh application

Since

Module ssh_file was introduced in OTP 21.2.

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.

Ssh_file implements the ssh_server_key_api and 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 key_cb when starting a client or a server (with for example ssh:connect, ssh:daemon of ssh:shell ).

Note

The functions are Callbacks for the SSH app. They are not intended to be called from the user's code!

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.

Clients

Clients uses all files stored in the USERDIR directory.

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)
ssh_host_ed25519_key - private eddsa host key for curve 25519 (optional)
ssh_host_ed448_key - private eddsa host key for curve 448 (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.

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)
id_ed25519 - private eddsa user key for curve 25519 (optional)
id_ed448 - private eddsa user key for curve 448 (optional)

The default value of USERDIR is /home/LOCALUSER/.ssh.

To change the USERDIR, see the user_dir option

Data Types

Options for the default ssh_file callback module

user_dir_common_option() = {user_dir, string()}

Sets the user directory.

user_dir_fun_common_option() = {user_dir_fun, user2dir()}
user2dir() =
fun((RemoteUserName :: string()) -> UserDir :: string())

Sets the user directory dynamically by evaluating the user2dir function.

system_dir_daemon_option() = {system_dir, string()}

Sets the system directory.

pubkey_passphrase_client_options() =
    {dsa_pass_phrase, string()} |
    {rsa_pass_phrase, string()} |
    {ecdsa_pass_phrase, string()}

If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be supplied with thoose options.

Note that EdDSA passhrases (Curves 25519 and 448) are not implemented.

optimize_key_lookup() = {optimize, time | space}

Make the handling of large files fast by setting time, but this will use more memory. The space variant shrinks the memory requirements, but with a higher time consumption.

To set it, set the option {key_cb, {ssh_file, [{optimize,TimeOrSpace}]} in the call of "ssh:connect/3, ssh:daemon/2 or similar function call that initiates an ssh connection.

Exports

host_key(Algorithm, Options) -> Result

OTP 21.2

Types

Algorithm = ssh:pubkey_alg()

Result = {ok, public_key:private_key()} | {error, term()}

Options = ssh_server_key_api:daemon_key_cb_options(none())

Types and description

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

Options

system_dir

Files

SYSDIR/ssh_host_rsa_key
SYSDIR/ssh_host_dsa_key
SYSDIR/ssh_host_ecdsa_key
SYSDIR/ssh_host_ed25519_key
SYSDIR/ssh_host_ed448_keyc>

is_auth_key(Key, User, Options) -> boolean()

OTP 21.2

Types

Key = public_key:public_key()

User = string()

Options =
ssh_server_key_api:daemon_key_cb_options(optimize_key_lookup())

Types and description

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

Options

user_dir_fun
user_dir

Files

USERDIR/authorized_keys
USERDIR/authorized_keys2

This functions discards all options in the begining of the lines of thoose files when reading them.

add_host_key(Host, Port, Key, Options) -> Result

OTP 23.0

Types

Host =
    inet:ip_address() |
    inet:hostname() |
    [inet:ip_address() | inet:hostname()]

Port = inet:port_number()

Key = public_key:public_key()

Options = ssh_client_key_api:client_key_cb_options(none())

Result = ok | {error, term()}

Types and description

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

Note that the alternative, the old Module:add_host_key/3 is no longer supported by ssh_file.

Option

user_dir

File

USERDIR/known_hosts

is_host_key(Key, Host, Port, Algorithm, Options) -> Result

OTP 23.0

Types

Key = public_key:public_key()

Host =
    inet:ip_address() |
    inet:hostname() |
    [inet:ip_address() | inet:hostname()]

Port = inet:port_number()

Algorithm = ssh:pubkey_alg()

Options =
ssh_client_key_api:client_key_cb_options(optimize_key_lookup())

Result = boolean() | {error, term()}

Types and description

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

Note that the alternative, the old Module:is_host_key/4 is no longer supported by ssh_file.

Option

user_dir

File

USERDIR/known_hosts

The known_hosts file is composed of lines as for OpenSSH:

(option)? pattern(,pattern)* keytype key (comment)?

where

option :: '@revoked'
pattern :: host | '[' host ']:' port
host :: ip-address | hostname | '*'
port :: portnumber | '*'
keytype :: 'ssh-dsa' | 'ssh-rsa'
         | 'ssh-ecdsa-nistp256' | 'ssh-ecdsa-nistp384' | 'ssh-ecdsa-nistp521'
         | 'ssh-ed25519' | 'ssh-ed448'
key :: % encoded key from eg ssh_host_*.pub

user_key(Algorithm, Options) -> Result

OTP 21.2