Update Security Configurations REST Service

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

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

By default, Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Security 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 Security Guardium Key Lifecycle Manager server.
port Specify the port number on which the IBM Security 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 Security Guardium Key Lifecycle Manager. For example, en or de.
Request body

JSON object with the following specification

Property name Description
FIPS Specify the value as on or off to enable or disable Federal Information Processing Standards (FIPS) publication 140-2 standard compliance in Guardium Key Lifecycle Manager.

By default, this flag is set to off.

When you set this property to on, Guardium Key Lifecycle Manager uses the IBMJCEPlusFIPS provider instead of the IBMJCE provider for all cryptographic functions.

Suite_B Specify the value as on or off to enable or disable US National Security Agency (NSA) Suite B standard compliance in Guardium Key Lifecycle Manager.

By default, this flag is set to off.

Set the property with one of the following values:
  • 128
  • 192

When you set this property to on, 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 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 enable 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/SKLM/rest/v1/ckms/SKLM/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/SKLM/rest/v1/ckms/SKLM/rest/v1/ckms/securityConfigurations/update
{
  "FIPS": "on"
}

Success response

Status Code: 200 OK{
  "code": "0",
  "status": "CTGKM3545I Security Configurations updated for below mentioned configurations.",
  "FIPS": "on"
}
Enable NIST SP 800-131A

Service request

POST https://localhost:port/SKLM/rest/v1/ckms/SKLM/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/SKLM/rest/v1/ckms/SKLM/rest/v1/ckms/securityConfigurations/update
{
  "FIPS": "off"
}
Disable Suite B

Service request

POST https://localhost:port/SKLM/rest/v1/ckms/SKLM/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/SKLM/rest/v1/ckms/SKLM/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
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.