Provided by: erlang-manpages_24.3.4.1+dfsg-1_all 
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.
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)
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() |
{ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()} |
{ed_pub, ed25519 | ed448, Key :: binary()},
openssh_key_v1_attributes()}]
openssh_key_v1_attributes() = [{atom(), term()}]
Types for the experimental implementaition of the openssh_key_v1 format. The
#ECPoint{} and ECPrivateKey{} are not used for Edwards curves (ed25519 and ed448),
but will be in next major release.
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 begining 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 deprecated
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.