ssh_file(3erl)

📦
version 25.3.2.8 · 6 versions
, in ubuntu noble

okay bestie, welcome to ssh_file(3erl) 💅 — Erlang Module Definition — aka the page where the default file-based callback module spills all its directory tea. It's giving very "your keys are literally in files" energy, and honestly? iconic.

💖 NAME 💖

ssh_file — the default callback module for the client's and the 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, no cap. 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 the 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. like, it's literally copying OpenSSH's fit, and it ate. 👑

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! bestie, do not call these directly, i'm begging 😭

🎀 FILES, DIRECTORIES AND WHO USES THEM 🎀

💜 Daemons 💜

Daemons use 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 use 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. periodt.

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 those options. 🔐

Note that EdDSA passphrases (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 implementation of the openssh_key_v1 format. 🧪

✨ EXPORTS ✨

okay bestie, this is where the actual callbacks and helper functions live 💅 every signature is exactly what it looks like, no cap.

🦋 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 — the one option listed here, periodt.

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

💖 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 function discards all options at the beginning of the lines in those files when reading them. yes bestie, it just tosses those leading options aside 💅

🦋 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: the alternative, the old Module:add_host_key/3, is no longer supported by ssh_file. so don't try to make it happen, okay? 😭

🎀 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: the alternative, the old Module:is_host_key/4, is no longer supported by ssh_file. lowkey important, bestie 🙈

🎀 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: EdDSA passphrases (Curves 25519 and 448) are not implemented. not me expecting those to work 😭 they do not, okay?

🌸 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. cute and flexible, we love that for us 💅

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. so treat it like a first draft, bestie 🫶

🌈 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

It encodes a list of SSH file entries (public keys and attributes) to a binary. literally turning the group chat into one neat message 🎀

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. again, experimental means experimental, no cap 💀

🦋 extract_public_key(PrivKey) -> PubKey

💖 Types

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

Fetches the public key from a private key. it's giving "give me the public version of this private situation" ✨

okay that's the whole page bestie 💖 big shoutout to Ericsson AB, this is ssh version 4.15.3.1, and the man page is ssh_file(3erl). slay and goodbye 🌈👑

📦 where this page comes from