Provided by: erlang-manpages_25.2.3+dfsg-1_all bug

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

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.

       key() = public_key:public_key() | public_key:private_key()

              The key representation

       experimental_openssh_key_v1() =
           [{key(), openssh_key_v1_attributes()}]

       openssh_key_v1_attributes() = [{atom(), term()}]

              Types for the experimental implementaition of the openssh_key_v1 format.

EXPORTS

       host_key(Algorithm, Options) -> Result

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

              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 beginning of the lines of  thoose  files
              when reading them.

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

              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

              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

       user_key(Algorithm, Options) -> Result

              Types:

                 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

                * 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

       decode(SshBin, Type) -> Decoded | {error, term()}

              Types:

                 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.

       encode(InData, Type) -> binary() | {error, term()}

              Types:

                 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.

       extract_public_key(PrivKey) -> PubKey

              Types:

                 PrivKey = public_key:private_key()
                 PubKey = public_key:public_key()

              Fetches the public key from a private key.