Add KMS server

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"
}