ssh_agent(3erl)

💅 ssh_agent — the Erlang Module Definition ✨

okay so bestie, real talk: this is ssh_agent, a Callback module for using an SSH agent instead of the default ssh_file callback. iykyk. 🫶

---

🌸 NAME 🌸

ssh_agent — the callback module that lets you vibe with an SSH agent instead of the default ssh_file callback. yes, that's the whole name, it's giving minimal icon energy. 💅

---

✨ DESCRIPTION ✨

So here's the tea: this module defines a callback handler for the communication with an SSH Agent, and it can be used to replace the default callback. What does that actually get you? It lets you issue signing requests to an agent that stores SSH private keys, so you can perform authentication. no cap, that's the whole point. 🔑

Ssh_agent implements the ssh_client_key_api, which means you can use it by setting the option key_cb when starting a client (with, for example, ssh:connect, ssh:shell). literally just:

{key_cb, {ssh_agent, []}}

The agent communication is established through a UNIX domain socket. By default, the socket path will be fetched from the SSH_AUTH_SOCK environment variable — which, fun fact, is the default socket path in the agent implementation of OpenSSH. 🌈

Wanna set a different socket path? The socket_path option has you covered, bestie:

{key_cb, {ssh_agent, [{socket_path, SocketPath}]}}

Note: 🚨 These functions are Callbacks for the SSH app. They are not intended to be called from the user's code! like, do not. i'm begging. 🙈

---

🎀 DATA TYPES 🎀

Options for the ssh_agent callback module 🦋

• socket_path_option() = {socket_path, string()} — Sets the socket path for the communication with the agent. your agent, your rules. ✨
• timeout_option() = {timeout, integer()} — Sets the time-out in milliseconds when communicating with the agent via the socket. The default value is 1000. so one second to make it happen — clock's ticking ⏰
• call_ssh_file_option() = {call_ssh_file, atom()} — The module which the add_host_key and is_host_key callbacks are delegated to. Defaults to the ssh_file module. very "i'm outsourcing this one, bestie" of it. 💜

---

👑 EXPORTS 👑

add_host_key/3 and add_host_key/4 🔥

add_host_key(Host :: string(),
             PublicKey :: public_key:public_key(),
             Options) ->
                ok | {error, Error :: term()}

add_host_key(Host,
             Port :: inet:port_number(),
             PublicKey :: public_key:public_key(),
             Options) ->
                Result

Types:

Host =
    inet:ip_address() |
    inet:hostname() |
    [inet:ip_address() | inet:hostname()]
Options =
    ssh_client_key_api:client_key_cb_options(call_ssh_file_option())
Result = ok | {error, Error :: term()}

This callback is delegated to the ssh_file module. it's giving "i know a guy". 🫡

---

is_host_key/4 and is_host_key/5 ⭐

is_host_key(Key :: public_key:public_key(),
            Host :: string(),
            Algorithm :: ssh:pubkey_alg(),
            Options) ->
               boolean()

is_host_key(Key :: public_key:public_key(),
            Host,
            Port :: inet:port_number(),
            Algorithm :: ssh:pubkey_alg(),
            Options) ->
               boolean()

Types:

Host =
    inet:ip_address() |
    inet:hostname() |
    [inet:ip_address() | inet:hostname()]
Options =
    ssh_client_key_api:client_key_cb_options(call_ssh_file_option())

This callback is delegated to the ssh_file module too. same guy, different question. 💀

---

user_key/2 🧚

user_key(Algorithm :: ssh:pubkey_alg(), Options) -> Result

Types:

Result =
    {ok, public_key:private_key()} |
    {ok, {ssh2_pubkey, PubKeyBlob :: binary()}} |
    {error, string()}
Options =
    ssh_client_key_api:client_key_cb_options(socket_path_option()
 |
                                             timeout_option())

Types and description 🌸

See the api description in ssh_client_key_api, Module:user_key/2. that's the main character of this section, go read it. 👑

---

and that's the whole page, bestie — slay 💖

cute sign-off time: this iconic little number is brought to you by Ericsson AB, from ssh 4.15.3.1, and it's the ssh_agent(3erl) page. mwah. 💋🎀