Add KMS server

Content Platform for Cloud Scale Management API Reference

Version
2.5.x
Audience
anonymous
Part Number
MK-HCPCS007-08

You can configure the connection to an external KMS server.

HTTP request syntax (URI)

POST https://host_ip:9099/mapi/v1/kmip/add_server
Note: The first KMS server you configure is designated as the primary server, and any other servers you configure are designated as secondary servers. Use the method promote_server to designate another KMS server as the primary server.

Request structure

The request body is:

{
  "name": "name",
  "host": "{hostname|ip_addr}",
  ["port": [nnnnn],]
  "isTLS12Enabled": {true|false},
  "httpsCiphers": "cipher_1[,...,cipher_n]"
}
Parameter Required Type Description
name Yes String The user-assigned name of the KMS server you want to add. Type up to 63 Unicode characters.

The server name must be unique.

host Yes String The host name or IP address of the KMS server.
port No Integer The port number of the KMS server.

Default: 5956

isTLS12Enabled Yes Boolean true if TLS v1.2 is enabled, false otherwise.

Note: TLS v1.2 support is provided for backward compatibility only.

httpsCiphers Yes String A string of comma-separated cyphers. The default group supports interoperability with a range of commercial key managers.

Default: TLS_RSA_WITH_AES_128_CBC_​SHA256, TLS_RSA_WITH_AES_256_CBC_​SHA256, TLS_ECDHE_ECDSA_WITH_AES_​256_CBC_SHA384, SSL_RSA_WITH_3DES_EDE_CBC_SHA, TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_​256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_​256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_​128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_​128_GCM_SHA256

Response structure

The response returns the same parameters as the request with the following additions. The response body structure is:

{
  "name": "label",
  "host": "host_name",
  "port": nnnnn,
  "isPrimary": {true|false},
  "isTLS12Enabled": {true|false},
  "httpsCiphers": "cipher_1[,...,cipher_n]",
  "isOnline": {true|false},
  "uuid": "uuid"
}

Parameter

Type

Description

name String The name of the KMS server.
host String The host name or IP address of the KMS server.
port 32-bit integer The port number of the KMS server.
isPrimary Boolean true if server is primary (read/write access), false if server is secondary (read-only access).
isTLS12Enabled Boolean true if TLS v1.2 is enabled, false otherwise.
httpsCiphers String A string of comma-separated cyphers.
isOnline Boolean true if server is online, false if server is offline.
uuid UUID The UUID of the server.

Return codes

Status code

HTTP name

Description

200 OK The request was executed successfully.
400 Bad Request The request is missing a valid storage component or parameter.
401 Unauthorized Access was denied because credentials are not valid.
404 Not Found The KMS server was not found.
405 Method Not Allowed The specified HTTP method is not allowed for a storage component. Resend using POST.
500 Internal Server Error The system was unable to set the requested object in the database.

Example

Request example:

POST https://10.10.24.195:9099/mapi/v1/kmip/add_server

JSON request:

{
  "name": "myServer",
  "host": "kmip.company.com",
  "port": 5678,
  "isTLS12Enabled": false,
  "httpsCiphers": "TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384"
}

JSON response:

{
  "name": "myServer",
  "host": "kmip.company.com",
  "port": 5678,
  "isPrimary": true,
  "isTLS12Enabled": false,
  "httpsCiphers": "TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384"
  "isOnline": true,
  "uuid": "uuid"
}