Search documentation of ssh

# ssh_file (ssh v6.0.2)

Copy Markdown View Source

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.

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

## Summary

### Types: Options

experimental_openssh_key_v1_decode()
experimental_openssh_key_v1_encode()
key()

The key representation

openssh_key_v1_attributes()

Types for the experimental implementation of the `openssh_key_v1` format.

optimize_key_lookup()

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.

pubkey_passphrase_client_options()

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

system_dir_daemon_option()

Sets the system directory.

user2dir()

Sets the user directory dynamically by evaluating the `user2dir` function.

user_dir_common_option()

Sets the user directory.

user_dir_fun_common_option()

### API

decode(SshBin, Type)

Decodes an SSH file-binary.

encode(InData, Type)

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

extract_public_key(PrivKey)

Fetches the public key from a private key.

### Callback Implementations

add_host_key(Host, Port, Key, Options)

Implements `ssh_client_key_api:add_host_key/4`.

host_key(Algorithm, Options)

Implements `ssh_server_key_api:host_key/2`.

is_auth_key(Key, User, Options)

Implements `ssh_server_key_api:is_auth_key/3`.

is_host_key(Key, Host, Port, Algorithm, Options)

Implements `ssh_client_key_api:is_host_key/5`.

user_key(Algorithm, Options)

Implements `ssh_client_key_api:user_key/2`.

## Types: Options

# experimental_openssh_key_v1_decode()

(since OTP 21.2)

    -type experimental_openssh_key_v1_decode() :: [{key(), openssh_key_v1_attributes()}].

# experimental_openssh_key_v1_encode()

(since OTP 21.2)

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

(since OTP 21.2)

    -type key() :: public_key:public_key() | public_key:private_key().

The key representation

# openssh_key_v1_attributes()

(since OTP 21.2)

    -type openssh_key_v1_attributes() :: [{atom(), term()}].

Types for the experimental implementation of the `openssh_key_v1` format.

# optimize_key_lookup()

(since OTP 21.2)

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

(since OTP 21.2)

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

(since OTP 21.2)

    -type system_dir_daemon_option() :: {system_dir, string()}.

Sets the system directory.

# user2dir()

(since OTP 21.2)

    -type user2dir() :: fun((RemoteUserName :: string()) -> UserDir :: string()).

Sets the user directory dynamically by evaluating the `user2dir` function.

# user_dir_common_option()

(since OTP 21.2)

    -type user_dir_common_option() :: {user_dir, string()}.

Sets the user directory.

# user_dir_fun_common_option()

(since OTP 21.2)

    -type user_dir_fun_common_option() :: {user_dir_fun, user2dir()}.

## API

# decode(SshBin, Type)

(since OTP 24.0)

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

(since OTP 24.0)

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

(since OTP 25.0)

    -spec extract_public_key(PrivKey) -> PubKey
                                when PrivKey :: public_key:private_key(), PubKey :: public_key:public_key().

Fetches the public key from a private key.

## Callback Implementations

# add_host_key(Host, Port, Key, Options)

(since OTP 23.0)

    -spec 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`

# host_key(Algorithm, Options)

(since OTP 21.2)

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

(since OTP 21.2)

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

(since OTP 23.0)

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

(since OTP 21.2)

    -spec 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`