Example of using the kek endpoint to bring in your own key encryption key (KEK)

To have better control over the key encryption key (KEK), you can bring your own KEK by using check and rotate REST API endpoints.

When you perform a fresh installation or an upgrade, the KEK is stored with BMC Software. Use the check REST API endpoint to review the existing KEK and then use the rotate endpoint to change the existing KEK with your key.

Form to track changes in the KEK

You can change the KEK anytime, except during an upgrade. The AR System:KEK Audit form tracks the changes in KEK.

The following screenshot shows the AR System:KEK Audit form:

Endpoint to check the existing KEK

Use the check endpoint to review the existing KEK. The following table lists the details of the check endpoint:

URL qualifier

/api/arsys/v1.0/kek/check

Method

GET

Header

Header	Value
Authorization	Token
Content-type	Application/json

Returns

A successful call shows SHA256 of the existing KEK.
See the following example:
{
"message": "SHA256 of the Key",
"result": "6220117B7C8308B9B6C5CBC2272DBEFE1F8E5FF33212A9C9A5EDBB84905AAB31"
{
An error message with the reason is displayed when the API call fails.

Endpoint to change the existing KEK

Use the rotate endpoint to change the existing KEK. The following table lists the details of the rotate endpoint:

URL qualifier

/api/arsys/v1.0/kek/rotate

Method

POST

Headers

Header	Value
Authorization	Token
Content-Type	Application/json

Parameter

Name	Description
key	A hexadecimal 256-bit encryption key of 32-byte length See the example below: "38fcb7871cf78002dcc721f437da5387"

Returns

A successful call returns a confirmation message of key change.
See the following example:
{
"message": "Key rotated successfully",
"result": "834F77E3D847C00B92908FDE43203B7E37D8B23C0D7858E02313F1EA9BDF0698"
}
An error message with the reason is displayed when the API call fails.

Example of using the check and rotate endpoints

The following sample code shows an example of using the check endpoint:

{
"name": "check Copy",
"protocolProfileBehavior": {
"disableBodyPruning": true
},
"request": {
"method": "GET",
"header": [
{
"key": "X-Requested-By",
"value": "XMLHttpRequest",
"type": "default"
}
],
"body": {
"mode": "raw",
"raw": "",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "<server name>/api/arsys/v1.0/kek/check",
"protocol": "https",
"host": [
"<Server name>"
],
"path": [
"api",
"arsys",
"v1.0",
"kek",
"check"
]
}
},
"response": []
}
]
}
r

The following sample code shows an example of using the Rotate endpoint:

{
"name": "<Name>",
"request": {
"method": "POST",
"header": [
{
"key": "X-Requested-By",
"value": "XMLHttpRequest",
"type": "default"
}
],
"body": {
"mode": "raw",
"raw": "{\r\n \"key\": \"<key>\"\r\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://<server name>/api/arsys/v1.0/kek/rotate",
"protocol": "https",
"host": [
"<server name>"
],
"path": [
"api",
"arsys",
"v1.0",
"kek",
"rotate"
]
}
},
"response": []
},

An example of checking and changing the KEK

The following video shows sending a REST call from the Postman client to check and change the KEK: