Customer-managed keys (CMK)

Note: This functionality is not currently available for FedRAMP customers / government entities. Additionally, CMK is 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. By allowing you to own and manage your own keys through third-party key management solutions, CMK enables you to maintain control over the encryption of persistent data within RelativityOne.

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.

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:

  1. 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.
  2. Generate service principal credentials - see Managing guest service principal keys.
  3. 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:

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.
    Notes:
  • Service principals are accounts for machines. It is recommended to use a set of unique credentials for each machine.
  • Authenticate as your guest user account when managing service principals.
  • The PowerShell scripts mentioned in the runbook are attached to the Relativity invitation email.

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
    Notes:
  • The parameter for the AadTenantId is located in the CMK invitation email sent to the principal administrator.
  • If a user has already logged in through Microsoft's login portal in the current PowerShell session (i.e., when running Connect-AzureAD or Connect-AzureRmAccount), then a login prompt will not display and the last logged in user will be used.
  • Get-UserToken uses AzureRm module version 5.7.0 and AzureAD module version 2.0.1.6. If a newer version of either module is already loaded in the current PowerShell session prior to running this script, errors may result.

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
    Notes:
  • The key value is not stored.
  • The parameter for the ApiHost can also be found in the CMK invitation template email sent to the principal administrator.

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
    Notes:
  • Only the start date, end date, keyName, and keyId are returned.
  • Key values are not stored and cannot be retrieved.

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

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.

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.

    • 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.
    • 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.
  1. Select the Keys tab and select the data-at-rest-rsa2048 key.
  2. Select New Version.
  3. 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.

  1. 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.

  1. 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.

    Notes:
  • DO NOT DISABLE THE OLD KEY VERSION.
  • The old key version is still in use, and disabling it right now will prevent RelativityOne from migrating to the new key version.
  • Disabling a key that is in use will crash your instance.

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

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.
  1. Enter the following commands.
  2. $keyVault = (Get-AzureRmKeyVault)[0]
    $currentKey = Get-AzureKeyVaultKey -VaultName $keyVault.VaultName -Name data-at-rest-rsa2048
    Add-AzureKeyVaultKey -VaultName $keyVault.VaultName -Name $currentKey.Name -Destination HSM
    Update-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

Use this operation to disable your RelativityOne instance (e.g., cases where there is a strong suspicion that the data inside RelativityOne could be corrupted and there is a need to disable the instance and make all the data unreadable).

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.

    • 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.
    • 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.
  1. Select the Keys tab, and then select the data-at-rest-rsa2048 key.
  2. Click Delete to delete the key.

Pulling the key (programmatic)

  1. 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.

  2. Enter the following commands.
  3. $keyVault = (Get-AzureRmKeyVault)[0]
    Remove-AzureKeyVaultKey -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 menu bar at the top of the page and select the Relativity Directory if not already selected.
  3. Navigate to the CMK key vault.

    • 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.
    • 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.
  1. Select Manage deleted keys at the top of the list.
  2. On the right pane you will see the list containing the previously deleted key vaults.

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

Restoring the key (programmatic)

To restore the key:

  1. 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.

  2. Enter the following commands.
  3. $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.