SSH host keys and certificates
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.
Telnet connections
Topics:
Telnet connections
List of endpoints for configuring the policies, options and connection rules of Telnet connections.
URL
GET https://<IP-address-of-SPS>/api/configuration/telnet
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 available settings for configuring for Telnet connections.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/telnet
Response
The following is a sample response received when listing the configuration settings.
For details of the meta object, see Message format.
{
"items": [
{
"key": "channel_policies",
"meta": {
"href": "/api/configuration/telnet/channel_policies"
}
},
{
"key": "options",
"meta": {
"href": "/api/configuration/telnet/options"
}
}
],
"meta": {
"first": "/api/configuration/aaa",
"href": "/api/configuration/telnet",
"last": "/api/configuration/x509",
"next": "/api/configuration/troubleshooting",
"parent": "/api/configuration",
"previous": "/api/configuration/ssh",
"transaction": "/api/transaction"
}
}
| Item | Description |
|---|---|
| channel_policies | List of the default and custom channel policies. |
| options | List of global Telnet options that affect all connections. |
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 |
|---|---|---|
| 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. |
Telnet connection policies
Connection policies determine if a server can be accessed from a particular client. Connection policies reference other resources (policies, usergroups, keys) that must be configured and available before creating a connection policy.
|
|
Caution:
The connection policies of this protocol are available in READ-ONLY mode on the REST API. Also, the returned data is incomplete, it does not include any protocol-specific settings, only the parameters that are common to every supported protocol. To modify the connection policies of this protocol, you must use the SPS web interface. Using the REST API, you can modify the connection policies of the RDP and SSH protocols. |
URL
GET https://<IP-address-of-SPS>/api/configuration/telnet/connections/
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 Telnet connection policies.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/telnet/connections/
The following command retrieves the properties of a specific policy.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/telnet/connections/<connection-key>