Update Security Configurations REST Service

Use the Update Security Configurations REST Service to set the security configurations in IBM Guardium Key Lifecycle Manager.

Operation: POST
URL: https://host:port/GKLM/rest/v1/ckms/securityConfigurations/update

By default, IBM® Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Guardium Key Lifecycle Manager installation, you can modify this default port.

Request

Request Parameters

Parameter	Description
host	Specify the IP address or hostname of the IBM Guardium Key Lifecycle Manager server.
port	Specify the port number on which the IBM Guardium Key Lifecycle Manager server listens for requests.

Request Headers

Header name	Value
Content-Type	`application/json`
Accept	`application/json`
Authorization	`SKLMAuth userAuthId=<authIdValue>`
Accept-Language	Any valid locale that is supported by IBM Guardium Key Lifecycle Manager. For example, `en` or `de`.

Request body

JSON object with the following specification

Property name	Description
FIPS	Use this property to enable Federal Information Processing Standards (FIPS) publication 140-3 standard compliance in IBM Guardium Key Lifecycle Manager. By default, the property value is set to `off`. To use FIPS `140-3` provider, specify the value as `140-3`. Note for FIPS: Federal Information Processing Standards (FIPS) 140-3 is a National Institute of Standards and Technology (NIST) standard that supersedes FIPS 140-2. With IBM Guardium Key Lifecycle Manager 5.1, support for FIPS 140-2 is withdrawn. Therefore, when a user configures IBM Guardium Key Lifecycle Manager 5.1 in FIPS mode, endpoints can no longer use ciphers, which were earlier available in FIPS 140-2 but are no longer available in FIPS 140-3. You can set the property with any of the following values: `140-3` `off`
Suite_B	Specify the value as `on` or `off` to enable or disable US National Security Agency (NSA) Suite B standard compliance in IBM Guardium Key Lifecycle Manager. By default, this flag is set to `off`. Set the property with any of the following values: `128` `192` When you set this property to `on`, IBM Guardium Key Lifecycle Manager uses the `IBMJSSE2` provider instead of the `IBMJCE` provider for all cryptographic functions.
SP800_131A	Specify the value as `on` or `off` to enable or disable IBM Guardium Key Lifecycle Manager to communicate over secure sockets in compliance with the National Institute of Standards and Technology (NIST) Special Publication (SP) 800-131A standard in strict mode. By default, this flag is set to `off`. Set the property to `on` to enable this standard. Note: Ensure that the FIPS property is set to off when you disable the SP800_131A property.
securityLevel	Specify one of the following values to configure the cipher suite group to be used by the TLS handshake. HIGH: For 128-bit ciphers and higher MEDIUM: For 40-bit ciphers WEAK: For all ciphers without encryption CUSTOM: When the cipher suite group is customized This property is ignored if you set the enabledCiphers property with a specific list of ciphers.
enabledCiphers	Specify a unique list of cipher suites. You can specify multiple cipher suites as comma-separated values. For example: `enabledCiphers=”TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256”` If you set this property, the securityLevel property is ignored. Note: Ensure that you use only the Cipher Suites that are supported by the client.

Response

Response Headers

Header name	Value and description
Status Code	200 OK The request was successful. The response body contains the requested representation. 400 Bad Request The authentication information was not provided in the correct format. 401 Unauthorized The authentication credentials were missing or incorrect. 404 Not Found Error The processing of the request fails. 500 Internal Server Error The processing of the request fails because of an unexpected condition on the server.
Content-Type	`application/json`
Content-Language	Locale for the response message.

Success response body

JSON object with the following specification

JSON property name	Description
code	Returns the code that is specified by the `status` property.
status	Returns the status to indicate whether the node is added to the multi-master cluster.

Error Response Body

JSON object with the following specification.

JSON property name	Description
code	Returns the application error code.
message	Returns a message that describes the error.

Example

Enable Suite B

Service request

POST https://localhost:port/GKLM/rest/v1/ckms/securityConfigurations/update
{
  "Suite_B": "128"
}

Success response

Status Code: 200 OK
{
  "code": "0",
  "status": "CTGKM3545I Security Configurations updated for below mentioned configurations.",
  "Suite_B": "128"
}

Enable FIPS

Service request

POST https://localhost:port/GKLM/rest/v1/ckms/GKLM/rest/v1/ckms/securityConfigurations/update
{
  "FIPS": "140-3"
}

Success response

Status Code: 200 OK{
  "code": "0",
  "status": "CTGKM3545I Security Configurations updated for below mentioned configurations.",
  "FIPS": "140-3"
}

Enable NIST SP 800-131A

Service request

POST https://localhost:port/GKLM/rest/v1/ckms/securityConfigurations/update
{
  "SP800_131A": "on"
}

Success response

Status Code: 200 OK
{
  "code": "0",
  "status": "CTGKM3545I Security Configurations updated for below mentioned configurations.",
   "SP800_131A": "on"
}

Important: After you set the SP800_131A property, ensure that FIPS is disabled by using the Get Security Configuration Details REST Service. If it is not disabled, set its value to off.

POST https://localhost:port/GKLM/rest/v1/ckms/GKLM/rest/v1/ckms/securityConfigurations/update
{
  "FIPS": "off"
}

Disable Suite B

Service request

POST https://localhost:port/GKLM/rest/v1/ckms/GKLM/rest/v1/ckms/securityConfigurations/update
{
  "Suite_B": "off"
}

Success response

Status Code: 200 OK
{
  "code": "0",
  "status": "CTGKM3545I Security Configurations updated for below mentioned configurations.",
  "Suite_B": "off"
}

Invalid service request with incorrect values

POST https://localhost:port/GKLM/rest/v1/ckms/GKLM/rest/v1/ckms/securityConfigurations/update
{
  "Suite_B": "on"
}

Error response

{
  "code": "CTGKM3540E",
  "status": "CTGKM3540E Suite B should have either 128 or 192 or off as their values."
}

Table 1. Topic change log
Date	Change description
16 Oct 2024	Updated description for the FIPS property.
09 Feb 2022	Added example for disabling a security configuration property.
03 Feb 2022	Corrected the REST example and the description of the enabledCiphers property.
04 Oct 2021	Corrected the description of the REST service.
10 Sept 2021	Initial version.