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 that 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...=="
}
}
}
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. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 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.
