Installation

Prerequisites

In order to integrate your Primus HSM keys with the ServiceNow Cloud Encryption, you need to meet the following requirements:

• An account on the ServiceNow platform with ServiceNow Platform Encryption subscription bundle. See Cloud Encryption with Key Management for more information.
• A Primus HSM or a CloudHSM Partition.

info

This guide assumes you have a running ServiceNow platform instance and will only go over the details of the HSM integration.

Step 1: Download and Install Primus API Provider

To wrap the customer managed key and export it from the HSM, one of the Primus API Providers can be used. In this guide, we will use the REST API, since it is easy to use and is included in most CloudHSM subscriptions.

1. Choose the API you want to use: REST, JCE, or PKCS#11.
2. Ensure your Primus HSM or CloudHSM Partition has the API licensed and enabled.
3. Download the Primus API Provider.
4. Install and configure the API Provider on your host device.

For details, see the guides to the respective Primus API Providers:

• REST
• JCE
• PKCS#11

Step 2: Prepare ServiceNow Wrapping Certificate

Download the ServiceNow Cloud Encryption wrapping certificate. It will be used to wrap the AES symmetric key.

On the ServiceNow Platform:

1. Navigate to All > Cloud Encryption Key Management > Key Management Operations. The Cloud Encryption Key Metadata list loads. All keys that have been used in your instance are listed.
2. In the Upload Customer Managed key window select the Download Wrapping Certificate. Save the public_certificate_xyz.zip to your local machine.

This certificate will be used to wrap your customer managed key. Next, you need to import the certificate into the HSM.

Step 3: Import Certificate

Use the POST /v1/certificate/import/plain/ REST endpoint to import the certificate into the HSM partition. We will name the imported certificate as servicenow_wrapping_certificate.

Certificate String Import

The certificate string to be imported must not include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. Additionally, make sure that the certificate string is in a single line.

{
  "label": "servicenow_wrapping_certificate",
  "certificate": "MIIC2DCCAcCgAwIBAgIUY8ZQq2NwX3zF3r9B4y3nQ6R5fXUwDQYJKoZIhvcNAQELBQAwFTETMBEGA1UEAwwKUmFuZG9tQ0EwHhcNMjUxMjE3MTAzMjAwWhcNMjYxMjE3MTAzMjAwWjAVMRMwEQYDVQQDDApSYW5kb21DZXJ0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwN0mJX6q8E4hHc7bJc4Qf5vM8nq9GZxZJr0wX5P0qzJ9YyUu7R0x3KfK0nR6bFvQ3FJ7mF9mV0x4W8zJ5kYpZkH2v8H2Lk9QnJp4rT6sP5y3R1cWcH1B9yJXkX4FJ5y0KZkN2mY3sY7X6L2nPZQ0HkP8NQ1Zy5xV7TtFJ2n7MZ0GJ8YQ5k9FqYkPZJm8p8M0WqZK6cF8FQ0n0L5wIDAQABo1MwUTAdBgNVHQ4EFgQUbZp1x5GJkZJvZpYxX3y7sXGZ8VQwHwYDVR0jBBgwFoAUbZp1x5GJkZJvZpYxX3y7sXGZ8VQwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAZm8kY0nZ7x5K2Zr1TQXJ0pFZPp0y6FQk8M7GZ3Qw8k9Y6V7r1QXJpZ0N8Y2FZQwM0XrYp5Q3nZQk8M7H0FZpJ6V5X2Y0Q8n7FZQwM0XrYp5Q3nZQk8M7H0FZpJ6V5X2Y0Q8n7FZQwM0XrYp5Q3nZQk8M7H0FZpJ6V5X2Y0Q8n7FZQwM0XrYp5Q3nZQk8M7H0FZpJ6V5X2Y0Q8n7"
}

Step 4: Create Customer Managed Key

Create a new AES-256 bit symmetric key using your selected API Provider. This is the key that you will "bring" to ServiceNow.

In the examples below, we will use servicenow_customer_managed_encryption_key as the key name.

With REST, call the POST /v1/key endpoint, with a request body as shown below:

{
    "label": "servicenow_customer_managed_encryption_key",
    "algorithm": "AES",
    "keySize": 256,
    "attributes": {
        "encrypt": true,
        "decrypt": true,
        "verify": true,
        "sign": false,
        "wrap": false,
        "unwrap": false,
        "derive": false,
        "bip32": false,
        "extractable": true,
        "modifiable": true,
        "destroyable": true,
        "sensitive": true,
        "copyable": false
    }
}

Step 4: Wrap and Export the Key

After successfully importing the certificate (or its public key) into the HSM, wrap the previously generated AES key servicenow_customer_managed_encryption_key with the certificate and export it in base64.

Request-Body:

{
   "wrapKeyRequest": {
        "keyToBeWrapped": "servicenow_customer_managed_encryption_key_20251029",
        "wrapKeyName": "servicenow_wrapping_certificate",
        "wrapMethod": "RSA_WRAP_OAEP"
    }
}

Response:

{
  "wrappedKey": "e5bTlxcDRAMx7fzLWIYc9Krs1pYD+0kjMVVf7pQbnHNADNFUG+mLUOf2oyX8oAtpQn9fjdToWCpSym4QqMfMkC+RprChU+YYRUbAWf2FbsbK8acd3+CBkK6oCvcoK1iOC9ZhDOXpT2N199JoJGt9hqWkwMLMwADHNGazIes1nN8SXt02XKWhJAmwppJgsHUR8BLQysXt6mZTpIzWdlJLHUlWOKxaE5mJa2xlfbRXZ5sYzYGwBjAdzAW93jh+Muz3nLx5DzpMj2HDpsqgcLlHIcOyeMITUZI0GMTPMVklKQvXiXN3bfl5Fq6FYzaoqdslHIShNNQx5SOvM5yIg=="
}

Save the wrappedKey value to a .txt file which will be imported into ServiceNow.

Base64 characters

The file must only contain valid base64 characters e5bTlxcDRAMx..................==.

Step 5: Bring Your Own Key

With the key generated, wrapped and extracted into a .txt file it can now be imported into the ServiceNow Encryption Platform as a Cloud Encryption customer managed key.

Follow the ServiceNow guide to rotate and switch to your customer managed key for your instance.