---
name: "ssh_agent"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/ssh_agent"
---

# ssh\_agent(3erl)

Callback module for using an SSH agent instead of the default ssh\_file callback.

## NAME

ssh\_agent - Callback module for using an SSH agent instead of the default ssh\_file callback.

## DESCRIPTION

This module defines a callback handler for the communication with an SSH Agent and can be used to replace the default callback. This allows to issue signing requests to an agent that stores SSH private keys to perform authentication.

Ssh\_agent implements the ssh\_client\_key\_api, to allow it to be used by setting the option *key\_cb* when starting a client (with for example ssh:connect, ssh:shell ).

```
      {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 is the default socket path in the agent implementation of OpenSSH.

In order to set a different socket path the *socket\_path* option can be set.

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

**Note:**

The functions are *Callbacks*  for the SSH app. They are not intended to be called from the user's code!

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

```
timeout_option() = {timeout, integer()}
```

Sets the time-out in milliseconds when communicating with the agent via the socket. The default value is *1000*.

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

## EXPORTS

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

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

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