SPS stores the host keys and X.509 certificates of the trusted servers. When a client tries to connect to a server, SPS verifies the host key or the certificate of the server, and allows connections only to the servers that have their keys available on SPS (unless the SSH Connection Policy is configured differently).

URL

GET https://<IP-address-of-SPS>/api/ssh-host-keys

Cookies

Cookie name	Description	Required	Values
session_id	Contains the authentication token of the user	Required	The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API. NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format)..

Sample request

The following command lists the SSH host keys and certificates of the servers that the users can connect to using SSH.

curl --cookie cookies https://<IP-address-of-SPS>/api/ssh-host-keys/

The following command retrieves the properties of a specific key.

curl --cookie cookies https://<IP-address-of-SPS>/api/ssh-host-keys/<object-id>

Response

The following is a sample response received when listing SSH host keys and certificates from the https:<IP-address-of-SPS>/api/ssh-host-keys/ endpoint.

For details of the meta object, see Message format.

The key of these objects is in the following format: <type-of-the-key>-<host-address>:<host-port>.

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-dss-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.1:22"}
    },
    {
      "key": "ssh-dss-10.110.0.2:2222",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.2:2222"}
    },
    {
      "key": "ssh-rsa-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-rsa-10.110.0.1:22"}
    },
    {
      "key": "x509v3-sign-rsa-d00::2222:dead:2222",
      "meta": {"href": "/api/ssh-host-keys/x509v3-sign-rsa-d00::2222:dead:2222"}
    }
  ]
}

When retrieving the endpoint of a specific host key, the response is the following.

{
  "key": "ssh-rsa-10.10.100.1:22",
  "meta": {
    "href": "/api/ssh-host-keys/ssh-rsa-10.10.100.1:22",
    "parent": "/api/ssh-host-keys"
  },
  "ssh-rsa-10.10.100.1:22": {
    "address": "10.10.100.1",
    "port": 22,
    "type": {
      "selection": "ssh-rsa",
      "value": "AAAAB3NzaC1yc2EAAAABIwAAAQEAxrtNxBZieXhBI2gJoAdsjKNq...=="
    }
  }
}

Element			Type	Description
key			string	Top level element, contains the ID of the host key or certificate in the following format: <type-of-the-key>-<host-address>:<host-port>
<id-of-the-host-key>			Top level element (string)	The ID of the host key or certificate in the following format: <type-of-the-key>-<host-address>:<host-port>.
	address		string	The IPv4 or IPv6 address of the host that the key belongs to. Note that for IPv6 addresses, this is always the canonical format of the address.
	port		number	The port number where the host uses the key or certificate.
	type		JSON object	The ID of the host key or certificate in the following format: <type-of-the-key>-<host-address>:<host-port>.
		selection	string	Specifies the type of the host key. Possible values: ssh-rsa, ssh-dss, x509v3-sign-rsa, x509v3-sign-dss
		value	string	The host key or certificate as a string in PEM format.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Code	Description	Notes
201	Created	The new resource was successfully created.
400	InvalidQuery	The requested filter or its value is invalid.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404	NotFound	The requested object does not exist.

Search and filter host keys

To list only specific host keys, you can use the following filters.

• List every host key and certificate:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys

• List host keys of a specific type:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?type=<type-to-list>

  Possible values: ssh-rsa, ssh-dss, x509v3-sign-rsa, x509v3-sign-dss. For example:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?type=ssh-rsa

• List host keys for a specific port number:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?port=<port-number-to-list>

• List host keys for a specific host address (IPv4 or IPv6):

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?address=<host-address>

• For a complex filter, separate the parameters with an ampersand (&) character, for example:

  GET https://<IP-address-of-SPS>/api/ssh-host-keys?port=<port-number-to-list>&type=<type-to-list>

The response to such requests is a JSON object, where the items list includes the IDs of the selected host keys (or an empty list). For example, filtering for ssh-dss keys could return a similar list:

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-dss-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.1:22"}
    },
    {
      "key": "ssh-dss-10.110.0.2:2222",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.2:2222"}
    }
  ]
}

Add new host key

To upload a new host key or certificate, you have to POST the host key and other data as a JSON object to the https://<IP-address-of-SPS>/api/ssh-host-keys endpoint. For details, see Create a new object. The body of the POST request must contain a JSON object with the parameters listed in Element . If the POST request is successful, the response includes an ID for the host key in the following format: <type-of-the-key>-<host-address>:<host-port>. For example:

{
  "address": "10.110.0.1",
  "port": 22,
  "type": {
    "selection": "ssh-rsa",
    "value": "AAAAB3NzaC1yc2EAAAAD...zvMwgc=="
  }
}

Note that for IPv6 addresses, SPS will automatically convert the address to its canonical format.

Delete host key

To delete a host key or certificate, you have to DELETE https://<IP-address-of-SPS>/api/ssh-host-keys/<ID-of-the-host-key> endpoint. For details, see Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

{
    "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.20.35:22",
        "parent": "/api/ssh-host-keys"
    }
}

You must commit your changes to actually delete the object from SPS.