Customer-managed keys (CMK)

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

Customer-managed keys (CMK) give you control over the RelativityOne application's access to your data by enabling you to own and manage your own root encryption keys through third-party key management solutions. While you hold the key, RelativityOne uses it to encrypt and access your data for supported workflows. If you revoke the key, the RelativityOne application loses the ability to access that data in a cohesive and consistent fashion.

If you have any issues, contact Relativity Support with "R1 – CMK – " in the subject.

What CMK does and does not do

CMK is a data-control feature. It governs the RelativityOne application's ability to access your data. It is not a security feature and does not replace RelativityOne's platform security controls, such as user authentication, permissions, Lockbox, or Security Center.

Use CMK when you need to:

• End access on your terms: revoke your key to prevent further application access to your data.
• Meet policy requirements: satisfy company or regional policies that require you to own and manage your own encryption keys.

Be aware of what CMK does not do:

• CMK does not prevent legal access to your data. Revoking your key governs the RelativityOne application's access to your data. It is not a mechanism for preventing access to data under a valid legal process.
• CMK does not protect against compromised accounts. If a user account or system administrator account in your instance is compromised, the application continues to operate with your key in place, and CMK provides no additional protection. Use authentication controls, permissions, and Security Center for these scenarios.

CMK applies to your Confidential Information – Client (CIC) data: the data you bring to and generate in RelativityOne, rather than data required for the normal operation of the platform.

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

• File
• SQL
• Audit
• Analytics
• Secret Store

How key revocation affects your data

Revoking your key disables your entire RelativityOne instance and prevents the RelativityOne application from accessing the data protected by your key. Not all data is handled the same way. Depending on the data type, revocation results in one of three responses:

• Cryptographic shredding: the data becomes unreadable and unrecoverable until you reinstate the key.

• Obfuscation or tokenization: sensitive elements are obscured or replaced with tokens, making the data inaccessible to the application.

• No action: low-sensitivity operational data required to run the platform is unaffected.

In every case, the result prevents the RelativityOne application from accessing your data and locks the instance. Relativity manages the data-type-to-response mapping through a standing CMK governance process.

Adding a new CMK administrator

To add a new CMK administrator for your organization, contact Relativity Support.

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:
  • Rotating the key - when a customer changes a key, all new data is encrypted with that new key.
  • Pulling the key – when disabling your RelativityOne instance.
  • Restoring the key - when you ran Pulling the key and want to recover your RelativityOne instance.

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

Rotating the key

Use this operation in the following situations:

• When the root key must be rotated according to policy.
• When the root key is more than 2 years old or approaching that age.

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
   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:

Rotating the key (programmatic):

1. Connect to Azure as a service principal or as the user invited during setup using Connect-AzAccount.
   • If connecting as a service principal, specify -TenantId $AadTenantId -SubscriptionId $SubscriptionId.
2. Enter the following commands.
   $keyVault = (Get-AzKeyVault)[0] $currentKey = Get-AzKeyVaultKey -VaultName $keyVault.VaultName -Name data-at-rest-rsa2048 Add-AzKeyVaultKey -VaultName $keyVault.VaultName -Name $currentKey.Name -Destination HSM Update-AzKeyVaultKey -VaultName $keyVault.VaultName -Name $currentKey.Name -Version $currentKey.Version -Expires (Get-Date).ToUniversalTime()

Ensure you have the Az.KeyVault module installed. Install it using:Install-Module Az.KeyVault -AllowClobber -Scope CurrentUser. The Az modules replace the deprecated AzureRM modules.

Pulling the key

Use this operation to disable your RelativityOne instance and remove the application's access to your CMK-covered data, as described in How key revocation affects your data.

The key is cached so there is a 15-20 minute delay before the instance will go down.

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.

Pulling the key (programmatic)

• Connect to Azure using the modern Az PowerShell modules as a service principal or as the user invited during setup using Connect-AzAccount.
  If connecting as a service principal, specify -TenantId $AadTenantId -SubscriptionId $SubscriptionId.
• Enter the following commands.
  $keyVault = (Get-AzKeyVault)[0] Remove-AzKeyVaultKey -VaultName $keyVault.VaultName -Name data-at-rest-rsa2048

Restoring the key

Use this operation when you ran Pulling the key and want to recover your RelativityOne instance.

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.

Restoring the key (programmatic)

To restore the key:

• Connect to Azure as a service principal or as the user invited during setup using Connect-AzAccount.
  If connecting as a service principal, specify -TenantId $AadTenantId -SubscriptionId $SubscriptionId.
• Enter the following commands.
  $keyVault = (Get-AzKeyVault) Undo-AzKeyVaultKeyRemoval -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.

This behavior is by design. The Security Logs API is intended to be polled by customer-side integrations at regular intervals (for example, every five minutes) to retrieve logs incrementally and reduce the likelihood of Azure throttling due to high CMK log volume.