List of options that affect all SSH connections.
GET https://<IP-address-of-SPS>/api/configuration/ssh/options
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). |
The following command lists global SSH options.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ssh/options
The following is a sample response received when listing global SSH options.
For details of the meta object, see Message format.
{ "body": { "audit": { "cleanup": { "channel_database_cleanup_days": 600, "enabled": true }, "timestamping": { "selection": "local", "signing_interval": 30 } }, "gssapi": { "enabled": false }, "service": { "enabled": true, "log_level": 4 } }, "key": "options", "meta": { "first": "/api/configuration/ssh/authentication_policies", "href": "/api/configuration/ssh/options", "last": "/api/configuration/ssh/settings_policies", "next": "/api/configuration/ssh/settings_policies", "parent": "/api/configuration/ssh", "previous": "/api/configuration/ssh/connections", "transaction": "/api/transaction" } }
Element | Type | Description | ||
---|---|---|---|---|
key | Top level item | Contains the ID of the endpoint. | ||
body | Top level item | Contains the elements of the global SSH options. | ||
audit | Top level item | Contains settings for timestamping and cleanup. | ||
service | Top level item | Global setting to enable SSH connections, and specify the logging detail. | ||
enabled | boolean | Set to true to enable SSH connections. | ||
log_level | int | Defines the logging detail of SSH connections. | ||
gssapi | Top level item | Deprecated setting. |
Set SPS as the timestamping server:
{ "audit": { "cleanup": { "enabled": false }, "timestamping": { "selection": "local", "signing_interval": 30 } }, "gssapi": { "enabled": false }, "service": { "enabled": true, "log_level": 4 } }
Enable cleanup, and set it to occur every 10 days:
{ "audit": { "cleanup": { "channel_database_cleanup_days": 10, "enabled": true }, "timestamping": { "selection": "local", "signing_interval": 30 } }, "gssapi": { "enabled": false }, "service": { "enabled": true, "log_level": 4 } }
Change timestamping to a remote server, without specifying a timestamping policy:
{ "audit": { "cleanup": { "channel_database_cleanup_days": 10, "enabled": true }, "timestamping": { "oid": { "enabled": false }, "selection": "remote", "server_url": "<url-of-timestamping-server>", "signing_interval": 30 } }, "gssapi": { "enabled": false }, "service": { "enabled": true, "log_level": 4 } }
Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:
{ "audit": { "cleanup": { "channel_database_cleanup_days": 10, "enabled": true }, "timestamping": { "oid": { "enabled": true, "policy_oid": "1.2.3" }, "selection": "remote", "server_url": "<url-of-timestamping-server>", "signing_interval": 30 } }, "gssapi": { "enabled": false }, "service": { "enabled": true, "log_level": 4 } }
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. |
To modify global SSH settings, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/options endpoint. You can find a detailed description of the available parameters listed in Element . The elements of the audit item are described in Elements of audit.
For details, see Commit a transaction.
SSH settings policies define protocol-level settings (algorithms, greetings and banners, timeout). You can create multiple policies, and choose the appropriate one for each SSH connection.
GET https://<IP-address-of-SPS>/api/configuration/ssh/settings_policies
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). |
The following command lists SSH settings policies.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ssh/settings_policies
The following command retrieves the properties of a specific policy.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/ssh/settings_policies/<policy-id>
The following is a sample response received when listing SSH settings policies.
For details of the meta object, see Message format.
{ "items": [ { "key": "-300", "meta": { "href": "/api/configuration/ssh/settings_policies/-300" } }, { "key": "236283841571912b948b88", "meta": { "href": "/api/configuration/ssh/settings_policies/236283841571912b948b88" } } ], "meta": { "first": "/api/configuration/ssh/authentication_policies", "href": "/api/configuration/ssh/settings_policies", "last": "/api/configuration/ssh/settings_policies", "next": null, "parent": "/api/configuration/ssh", "previous": "/api/configuration/ssh/options", "transaction": "/api/transaction" } }
When retrieving the endpoint of a specific policy, the response is the following.
{ "body": { "client_side_algorithms": { "cipher": [ "aes128-ctr", "aes192-ctr", "aes256-ctr" ], "compression": [ "none" ], "kex": [ "diffie-hellman-group14-sha1" ], "mac": [ "hmac-sha2-256", "hmac-sha2-512" ] }, "greeting": "Welcome!", "name": "API_SSH_Setting", "preconnect_channel_check": true, "server_side_algorithms": { "cipher": [ "aes128-ctr", "aes192-ctr", "aes256-ctr" ], "compression": [ "none" ], "kex": [ "diffie-hellman-group14-sha1" ], "mac": [ "hmac-sha2-256", "hmac-sha2-512" ] }, "software_version": "SSH", "strict_mode": true, "timeout": 600, "userauth_banner": "This is a monitored connection." }, "key": "236283841571912b948b88", "meta": { "first": "/api/configuration/ssh/settings_policies/-300", "href": "/api/configuration/ssh/settings_policies/236283841571912b948b88", "last": "/api/configuration/ssh/settings_policies/236283841571912b948b88", "next": null, "parent": "/api/configuration/ssh/settings_policies", "previous": "/api/configuration/ssh/settings_policies/-300", "transaction": "/api/transaction" } }
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. |
To add a settings policy, you have to:
For details, see Open a transaction.
POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/settings_policies/ endpoint. You can find a detailed description of the available parameters listed in Element .
If the POST request is successful, the response includes the key of the new policy. For example:
{ "key": "59790911-415c-4ed3-a0d2-1164637472ca", "meta": { "href": "/api/configuration/ssh/settings_policies/59790911-415c-4ed3-a0d2-1164637472ca", "parent": "/api/configuration/ssh/settings_policies", "transaction": "/api/transaction" } }
For details, see Commit a transaction.
To modify a settings policy, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/ssh/settings_policies/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Element .
For details, see Commit a transaction.
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).
GET https://<IP-address-of-SPS>/api/ssh-host-keys
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). |
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>
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...==" } } }
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. |
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"} } ] }
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.
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.
© ALL RIGHTS RESERVED. Nutzungsbedingungen Datenschutz Cookie Preference Center