Customer-managed keys (CMK) (2024)

Note: This functionality is not currently available for FedRAMP customers / government entities. Additionally, CMKis currently not offered as part of the Relativity PayGo model.

Customer Managed Keys (CMK) provide you with control over the keys used to encrypt data at rest in RelativityOne. This allows you to own and manage your own keys through third-party key management solutions. Customer Managed Keys enable you to maintain control over the encryption of persistent data within RelativityOne.

Business or contractual obligations may require periodic key rotation. If your Key Management Service (KMS) supports automated key rotation, leverage this feature. Otherwise, manually initiate the key rotation processes as needed.

The scope of the feature covers RelativityOne services that retain persistent data, which includes:

• File
• SQL
• Audit
• Analytics
• Secret Store

Note: If you have any issues, please contact Relativity Support with “R1 – CMK – ” in the subject.

Adding a new CMK administrator

To add a new CMK administrator for your organization, you must submit a ticket requesting the new CMK administrator via the Customer Support form.

Note: The number of CMK administrators that can be created is limited to 10.

Once your new CMK administrator account is created, you will receive three emails:

• Email from Relativity containing the following important values (which you will use when executing the supplied runbooks and PowerShell scripts) and instructions to follow.
  • AadTenantId
  • ApiHost
• Invitation from Microsoft to create a guest user in the RelativityOne (Production) directory.

Getting started with CMK

To get started for the first time, perform the following tasks:

• Create your account - follow the instructions in the email invitation from Microsoft to create a guest user in the RelativityOne (Production) directory. If you already have an Azure account, we recommend that you link the guest user to your existing account.
• Generate service principal credentials - see Managing guest service principal keys.
• Manage your root encryption key - Your program or HSM will authenticate as the service principal created in the previous step. When managing your key, you will use the AadTenantId and ApiHost values provided to you by Relativity in the introductory email. You can perform the following operations with your key:
  • Customer-managed keys (CMK) - when a customer changes a key, all new data is encrypted with that new key.
  • Customer-managed keys (CMK) – when disabling your RelativityOne instance.
  • Customer-managed keys (CMK) - when you ran Customer-managed keys (CMK) and want to recover your RelativityOne instance.

Note: To maintain the performance of RelativityOne during normal operations, a root encryption key is utilized only to encrypt a data encryption key, which in turn is used to encrypt data at rest within RelativityOne. The data encryption key that is currently in use is cached for up to one hour. In the event that you need to revoke this key, please be aware that it will take up to an hour for the revocation to take effect and RelativityOne may become unavailable during this time. Additionally, both Soft Delete and Do Not Purge features are enabled on the environment key vault, which means that you will have a 90-day window to restore a revoked key. It is important to note that Relativity staff will not be able to restore a key that you have deleted.

Managing guest service principal keys

Use this operation in the following situations:

• On initial CMK setup.
• When wanting to create additional guest service principal keys to access CMK.
• When wanting to retrieve a list of ids, start dates, and end dates for service principal keys.
• When wanting to revoke service principal keys.

Retrieving access tokens

Retrieve an access token by executing Get-UserToken.ps1. A login prompt will pop up. By default, tokens expire one hour from the time they are retrieved.

$token = .\Get-UserToken.ps1 -AadTenantId $AadTenantId

Get guest service principal id

To get a guest service principal id, please execute the following script:

.\Get-UserToken.ps1 -AadTenantId $AadTenantId | .\Get-ClientId.ps1 -ApiHost $ApiHost

Creating guest service principal secret

To create a guest service principal key, call Create-Key.ps1 and enter the token retrieved in Retrieving access tokens. The key name that is passed in must be unique and no more than 16 characters long.

.\Get-UserToken.ps1 -AadTenantId $AadTenantId | .\Create-Key.ps1 -ApiHost $ApiHost -keyName $KeyName

Retrieving the key list

To retrieve a list of keys for a guest service principal, call Get-Keys.ps1 and enter the token retrieved in Retrieving access tokens.

.\Get-UserToken.ps1 -AadTenantId $AadTenantId | .\Get-Keys.ps1 -ApiHost $ApiHost

Revoking a key

To remove a key for a guest service principal, call Remove-Key.ps1, entering in the token retrieved in Retrieving access tokens and specifying the keyId of the key that should be revoked.

.\Get-UserToken.ps1 -AadTenantId $AadTenantId | .\Remove-Key.ps1 -ApiHost $ApiHost -KeyId $KeyId

Key management operations

There are three key management operations used to safely store data at rest. These operations include key rotation, pulling, and restoration. Each of these operations can be performed in a manual (basic) or automated (advanced) fashion.

Key rotation

Periodically replace the root encryption key to mitigate security risks. This process is typically initiated when the key exceeds its recommended lifespan (e.g., two years) or as mandated by security policies.

Note: There is a CMK syncer automation account deployed to every subscription that runs on an interval of every 15 minutes and ensures the storage account is using the latest encryption key. All old data is re-encrypted when the data is accessed.

Key pulling

In cases of suspected data corruption or other critical security concerns, you can disable the RelativityOne instance by pulling the encryption key. This process introduces a 15-20 minute delay due to key caching.

Key restoration

To restore a RelativityOne instance after a key pull operation, initiate the key restoration process.

Rotating the key (manual):

1. Login to portal.azure.com as the user invited during setup.
2. Click the Directory + Subscription icon on menu bar at the top of the page and select the Relativity Directory if not already selected.
3. Navigate to the CMK key vault.
   1. Use the search bar at the top of the page. This can be done by:
      • Entering the key vault name. The matching key vault will show up under the Resources section of the result pane.
      • Entering the phrase "key vault". Then go to "Key Vaults" from the Services section.
   2. Alternately, navigate to the All Resources tab, and then filter for the CMK key vault by name. Note that now the list of the keys is empty.
4. Select the Keys tab and select the data-at-rest-rsa2048 key.
5. Select New Version.
6. Set the default options:
   • Options = Generate
   • Key Type = RSA-HSM
   • RSA Key Size = 2048

Note: Microsoft only supports the RSA 2048 key size for encryption at rest.

7. Click Create to create a new version of the key.The new key version will show up under the Current Version section. The old key is currently in the Older Version section and it does not have the expiration date set.

8. Select the old version, check Set expiration date, and set the expiration date of the old version to any time prior to the current time, and then click Save.
   • Note that the date is two years in advance.
   • Change the date as well as the time.
   • If you try to use the pop-up picker, you cannot type in the box.

When you are done, portal's key list will look like this:

Pulling the key (manual)

1. Login to portal.azure.com as the user invited during setup.
2. Click the Directory + Subscription icon on menu bar at the top of the page and select the Relativity Directory if not already selected.
3. Navigate to the CMK key vault.
   1. Use the search bar at the top of the page. This can be done by:
      • Entering the key vault name. The matching key vault will show up under the Resources section of the result pane.
      • Entering the phrase "key vault". Then go to "Key Vaults" from the Services section.
   2. Alternately, navigate to the All Resources tab, and then filter for the CMK key vault by name. Note that now the list of the keys is empty.
4. Select the Keys tab, and then select the data-at-rest-rsa2048 key.
5. Click Delete to delete the key.

Restoring the key (manual)

1. Login to portal.azure.com as the user invited during setup.
2. Click the Directory + Subscription icon on the menu bar at the top of the page and select the Relativity Directory if not already selected.
3. Navigate to the CMK key vault.
   1. Use the search bar at the top of the page. You can find the CMK key vault by:
      • Entering the key vault name. The matching key vault will show up under the Resources section of the result pane.
      • Entering the phrase "key vault" and then going to "Key Vaults" from the Services section.
   2. Alternatively, navigate to the All Resources tab, and then filter for the CMK key vault by name. The list of the keys will be empty at this point.
4. Select Manage deleted keys at the top of the list.
5. On the right pane, you will see a list containing the previously deleted key vaults.

6. Select the checkbox next to the deleted key name, and click Recover at the bottom of the pane.
7. Click Refresh in the "Keys vaults" view. The data-at-rest-rsa2048 key should be on the list again.
8. There may be a slight delay. If the key is not visible, wait several seconds and then click Refresh again.
9. Select the key and you should see all the versions being restored.

Rotating the key (programmatic):

1. Connect to AzureRM as a service principal or as the user invited during setup using Connect-AzureRmAccount.
   • If connecting as a service principal, specify -TenantId $AadTenantId -SubscriptionId $SubscriptionId.
2. Enter the following commands.

$keyVault = (Get-AzureRmKeyVault)[0]$currentKey = Get-AzureKeyVaultKey -VaultName $keyVault.VaultName -Name data-at-rest-rsa2048Add-AzureKeyVaultKey -VaultName $keyVault.VaultName -Name $currentKey.Name -Destination HSMUpdate-AzureKeyVaultKey -VaultName $keyVault.VaultName -Name $currentKey.Name -Version $currentKey.Version -Expires (Get-Date).ToUniversalTime()

Note: This command is not available in AzureRM 5.7.0. It is, however, available in AzureRM 6.13.0. If unable to run this command and unable to Import version 6.13.0, the old key can be expired manually by following step 8 of Rotating the key (manual):.

Pulling the key (programmatic)

• Connect to AzureRM as a service principal or as the user invited during setup using Connect-AzureRmAccount.

  Note: If connecting as a service principal, specify -TenantId $AadTenantId -SubscriptionId $SubscriptionId.

• Enter the following commands.

$keyVault = (Get-AzureRmKeyVault)[0]
Remove-AzureKeyVaultKey -VaultName $keyVault.VaultName -Name data-at-rest-rsa2048

Restoring the key (programmatic)

To restore the key:

• Connect to AzureRM as a service principal or as the user invited during setup using Connect-AzureRmAccount.

  Note: If connecting as a service principal, specify -TenantId $AadTenantId -SubscriptionId $SubscriptionId.

• Enter the following commands.

$keyVault = (Get-AzureRmKeyVault)[0]
Undo-AzureKeyVaultKeyRemoval -VaultName $keyVault.VaultName -Name data-at-rest-rsa2048

Security Logs API

Programmatic access to logging around CMK operations is provided upon request. This API service provides transparency into users who have access to your keys and auditing of key CMK operations.

If you need access to CMK security logs, please submit a request via the Customer Support form and include "CMK-Security Log" in the description.