---
name: "ssh_client_key_api"
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_client_key_api"
---

# ssh\_client\_key\_api(3erl)

\-behaviour(ssh\_client\_key\_api).

## NAME

ssh\_client\_key\_api - \
      \-behaviour(ssh\_client\_key\_api).

## DESCRIPTION

Behavior describing the API for public key handling of an SSH client. By implementing the callbacks defined in this behavior, the public key handling of an SSH client can be customized. By default the *ssh* application implements this behavior with help of the standard OpenSSH files, see the  [ssh(7)](/ssh/7.md) application manual.

## DATA TYPES

```
client_key_cb_options(T) =
    [{key_cb_private, [T]} | ssh:client_option()]
```

Options provided to ssh:connect/\[3,4\].

The option list given in the *key\_cb* option is available with the key *key\_cb\_private*.

## EXPORTS

**Module:add\_host\_key(HostNames, PublicHostKey, ConnectOptions) -\> ok \| {error, Reason}**\

Types:

HostNames = string()\

Description of the host that owns the *PublicHostKey*.

PublicHostKey = public\_key:public\_key()\

Of ECDSA keys, only the Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.

ConnectOptions = client\_key\_cb\_options()\

This function is retired in favour for *Module:add\_host\_key/4* which is the preferred API function. The calling SSH application will still try the *add\_host\_key/3* if the call to *add\_host\_key/4* failed.

Adds a host key to the set of trusted host keys.

**Module:add\_host\_key(Host, Port, PublicHostKey, ConnectOptions) -\> ok \| {error, Reason}**\

Types:

Host = inet:ip\_address() \| inet:hostname() \| \[ inet:ip\_address() \| inet:hostname() \]\

The host that owns the *PublicHostKey*. One or more IP addresses or hostnames.

Port = inet:port\_number()\

The Port number of the Host.

PublicHostKey = public\_key:public\_key()\

Of ECDSA keys, only the Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.

ConnectOptions = client\_key\_cb\_options()\

Adds a host key to the set of trusted host keys.

This function is preferred to the old *Module:add\_host\_key/3* since it also uses the peer host port number and may return an error message.

The OTP/SSH application first calls this function in the callback module, and then the old *Module:add\_host\_key/3* for compatibility.

**Module:is\_host\_key(Key, Host, Algorithm, ConnectOptions) -\> Result**\

Types:

Key = public\_key:public\_key()\

Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.

Host = string()\

Description of the host.

Algorithm = ssh:pubkey\_alg()\

Host key algorithm.

ConnectOptions = client\_key\_cb\_options()\
 Result = boolean()\

This function is retired in favour for *Module:is\_host\_key/5* which is the preferred API function. The calling SSH application will still try the *is\_host\_key/4* if the call to *is\_host\_key/5* failed.

Checks if a host key is trusted.

**Module:is\_host\_key(Key, Host, Port, Algorithm, ConnectOptions) -\> Result**\

Types:

Key = public\_key:public\_key()\

Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.

Host = inet:ip\_address() \| inet:hostname() \| \[ inet:ip\_address() \| inet:hostname() \]\

Description of the host with one or more IP addresses or hostnames.

Port = inet:port\_number()\

The Port number of the host.

Algorithm = ssh:pubkey\_alg()\

Host key algorithm.

ConnectOptions = client\_key\_cb\_options()\
 Result = boolean() \| {error, Error::term()}\

The exact error message depends on the actual callback module. The Error message makes the connection to fail, and is returned from e.g ssh:connect/3.

Checks if a host key is trusted.

This function is preferred to the old *Module:is\_host\_key/4* since it also uses the peer host port number and may return an error message.

The OTP/SSH application first calls this function in the callback module, and then the old *Module:is\_host\_key/4* for compatibility.

**Module:user\_key(Algorithm, ConnectOptions) -\> Result**\

Types:

Algorithm = ssh:pubkey\_alg()\

Host key algorithm.

ConnectOptions = client\_key\_cb\_options()\
 Result = {ok, public\_key:private\_key()} \| {ok, {ssh2\_pubkey, PubKeyBlob :: binary()}} \| {error, term()}\

Fetches the users *public key* matching the *Algorithm*. Some key callback modules may return *{ssh2\_pubkey, PubKeyBlob :: binary()}*.

**Note:**

The private key contains the public key.