ssh_file(3)

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

DESCRIPTION

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 or ssh:shell ).

CALLBACKS: The callback functions (host_key/2, is_auth_key/3, user_key/2, is_host_key/5, add_host_key/4) are called by the SSH application internally. They are documented here to show which files and options the default implementation uses. See ssh_server_key_api and ssh_client_key_api for the callback specifications. The public API functions are decode/2, encode/2, and extract_public_key/1.

  Files, directories and who uses them

Daemons

Daemons uses all files stored in the SYSDIR directory.

Optionally, 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)

    The key files could be generated with OpenSSH's ssh-keygen command.

    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.

        It is composed of lines as for OpenSSH:

            (options)? keytype base64-encoded-key comment

        where

            options :: option(,option)*
            option :: % All options are skipped
            keytype :: 'ssh-dsa'
                     | 'ssh-rsa'
                     | 'ssh-ecdsa-nistp256'
            	 | 'ssh-ecdsa-nistp384'
                     | 'ssh-ecdsa-nistp521'
                     | 'ssh-ed25519'
            	 | 'ssh-ed448'
            base64-encoded-key :: % The user's public key
            comment :: % Comments are skipped
    known_hosts
        host keys from hosts visited concatenated. The file is created and used by the client.

        It 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

        • 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 key files could be generated with OpenSSH's ssh-keygen command.

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

    To change the USERDIR, see the user_dir option

DATA TYPES

experimental_openssh_key_v1_decode() :: [{key(), openssh_key_v1_attributes()}].
experimental_openssh_key_v1_encode() :: [{[{public_key:public_key(), public_key:private_key(), Comment :: binary()} | {public_key:private_key(), Comment :: binary()}], openssh_key_v1_attributes()}].
key() :: public_key:public_key() | public_key:private_key().

    The key representation
openssh_key_v1_attributes() :: [{atom(), term()}].

    Types for the experimental implementation of the openssh_key_v1 format.
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.
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 those options.

    Note that EdDSA passhrases (Curves 25519 and 448) are not implemented.
system_dir_daemon_option() :: {system_dir, string()}.

    Sets the system directory.
user2dir() :: fun((RemoteUserName :: string()) -> UserDir :: string()).

    Sets the user directory dynamically by evaluating the user2dir function.
user_dir_common_option() :: {user_dir, string()}.

    Sets the user directory.
user_dir_fun_common_option() :: {user_dir_fun, user2dir()}.

FUNCTIONS

add_host_key(Host, Port, Key, Options) -> Result when 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()}.

    Implements ssh_client_key_api:add_host_key/4.

    Option

        • user_dir

    File

        • USERDIR/known_hosts
decode(SshBin, Type) -> Decoded | {error, term()} when SshBin :: binary(), Type :: ssh2_pubkey | public_key | openssh_key | rfc4716_key | openssh_key_v1 | known_hosts | auth_keys, Decoded :: Decoded_ssh2_pubkey | Decoded_public | Decoded_openssh | Decoded_rfc4716 | Decoded_openssh_key_v1 | Decoded_known_hosts | Decoded_auth_keys, Decoded_ssh2_pubkey :: public_key:public_key(), Decoded_public :: Decoded_rfc4716 | Decoded_openssh_key_v1 | Decoded_openssh, Decoded_openssh :: [{public_key:public_key(), [{comment, string()}]}], Decoded_rfc4716 :: [{key(), [{headers, Attrs}]}], Decoded_openssh_key_v1 :: experimental_openssh_key_v1_decode(), Decoded_known_hosts :: [{public_key:public_key(), [{comment, string()} | {hostnames, [string()]}]}], Decoded_auth_keys :: [{public_key:public_key(), [{comment, string()} | {options, [string()]}]}], Attrs :: {Key :: string(), Value :: string()}.

    Decodes an SSH file-binary.

    If Type is public_key the binary can be either an RFC4716 public key or an OpenSSH public key.

    NOTE: The implementation of the openssh_key_v1 format is still experimental.
encode(InData, Type) -> binary() | {error, term()} when Type :: ssh2_pubkey | openssh_key | rfc4716_key | openssh_key_v1 | known_hosts | auth_keys, InData :: InData_ssh2_pubkey | InData_openssh | InData_rfc4716 | InData_openssh_key_v1 | InData_known_hosts | InData_auth_keys, InData_ssh2_pubkey :: public_key:public_key(), InData_openssh :: [{public_key:public_key(), [{comment, string()}]}], InData_rfc4716 :: [{key(), [{headers, Attrs}]}], InData_openssh_key_v1 :: experimental_openssh_key_v1_encode(), InData_known_hosts :: [{public_key:public_key(), [{comment, string()} | {hostnames, [string()]}]}], InData_auth_keys :: [{public_key:public_key(), [{comment, string()} | {options, [string()]}]}], Attrs :: {Key :: string(), Value :: string()}.

    Encodes a list of SSH file entries (public keys and attributes) to a binary.

    NOTE: The implementation of the openssh_key_v1 format is still experimental.
extract_public_key(PrivKey) -> PubKey when PrivKey :: public_key:private_key(), PubKey :: public_key:public_key().

    Fetches the public key from a private key.
host_key(Algorithm, Options) -> Result when Algorithm :: ssh:pubkey_alg(), Result :: {ok, public_key:private_key()} | {error, term()}, Options :: ssh_server_key_api:daemon_key_cb_options(none()).

    Implements ssh_server_key_api: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_key
is_auth_key(Key, User, Options) -> boolean() when Key :: public_key:public_key(), User :: string(), Options :: ssh_server_key_api:daemon_key_cb_options(optimize_key_lookup()).

    Implements ssh_server_key_api:is_auth_key/3.

    Options

        • user_dir_fun

        • user_dir

    Files

        • USERDIR/authorized_keys

        • USERDIR/authorized_keys2

    This functions discards all options in the beginning of the lines of thoose files when reading them.
is_host_key(Key, Host, Port, Algorithm, Options) -> Result when 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()}.

    Implements ssh_client_key_api:is_host_key/5.

    Option

        • user_dir

    File

        • USERDIR/known_hosts
user_key(Algorithm, Options) -> Result when Algorithm :: ssh:pubkey_alg(), Result :: {ok, public_key:private_key()} | {error, string()}, Options :: ssh_client_key_api:client_key_cb_options(none()).

    Implements ssh_client_key_api:user_key/2.

    Options

        • user_dir

        • dsa_pass_phrase

        • rsa_pass_phrase

        • ecdsa_pass_phrase

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

    Files

        • USERDIR/id_dsa

        • USERDIR/id_rsa

        • USERDIR/id_ecdsa

        • USERDIR/id_ed25519

        • USERDIR/id_ed448