View Source ssh_file (ssh v5.2)

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

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 for the default ssh_file callback module

The key representation

Types for the experimental implementaition of the openssh_key_v1 format.

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.

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

Sets the user directory dynamically by evaluating the user2dir function.

Functions

Decodes an SSH file-binary.

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

Fetches the public key from a private key.

Types and description

Types and description

Types and description

Types: Options for the default ssh_file callback module

Link to this type

experimental_openssh_key_v1()

View Source (not exported) (since OTP 21.2)
-type experimental_openssh_key_v1() :: [{key(), openssh_key_v1_attributes()}].

Equivalent to openssh_key_v1_attributes/0.

Link to this type

key()

View Source (not exported) (since OTP 21.2)

The key representation

Link to this type

openssh_key_v1_attributes()

View Source (not exported) (since OTP 21.2)
-type openssh_key_v1_attributes() :: [{atom(), term()}].

Types for the experimental implementaition of the openssh_key_v1 format.

Link to this type

optimize_key_lookup()

View Source (not exported) (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.

Link to this type

pubkey_passphrase_client_options()

View Source (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 thoose options.

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

Link to this type

system_dir_daemon_option()

View Source (since OTP 21.2)
-type system_dir_daemon_option() :: {system_dir, string()}.

Sets the system directory.

Link to this type

user2dir()

View Source (not exported) (since OTP 21.2)
-type user2dir() :: fun((RemoteUserName :: string()) -> UserDir :: string()).

Sets the user directory dynamically by evaluating the user2dir function.

Link to this type

user_dir_common_option()

View Source (since OTP 21.2)
-type user_dir_common_option() :: {user_dir, string()}.

Sets the user directory.

Link to this type

user_dir_fun_common_option()

View Source (since OTP 21.2)
-type user_dir_fun_common_option() :: {user_dir_fun, user2dir()}.

Equivalent to user2dir/0.

Functions

Link to this function

add_host_key(Host, Port, Key, Options)

View Source (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()}.

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

File

Link to this function

decode(SshBin, Type)

View Source (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(),
              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 following key types have been renamed from the deprecated public_key:ssh_decode/2:

  • rfc4716_public_key -> rfc4716_key
  • openssh_public_key -> openssh_key

Note

The implementation of the openssh_key_v1 format is still experimental.

Link to this function

encode(InData, Type)

View Source (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(),
              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 following key types have been renamed from the removed public_key:ssh_encode/2:

  • rfc4716_public_key -> rfc4716_key
  • openssh_public_key -> openssh_key

Note

The implementation of the openssh_key_v1 format is still experimental.

Link to this function

extract_public_key(PrivKey)

View Source (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.

Link to this function

host_key(Algorithm, Options)

View Source (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()).

Types and description

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

Options

Files

Link to this function

is_auth_key(Key, User, Options)

View Source (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()).

Types and description

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

Options

Files

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

Link to this function

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

View Source (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()}.

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

File

Link to this function

user_key(Algorithm, Options)

View Source (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()).

Types and description

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

Options

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

Files