Overview

By default, Clio Operate encrypts all data at rest with platform-managed keys. Bring your own key (BYOK) adds a key that you create and own. Your key wraps the encryption keys, so you control whether your data can be decrypted.

Clio Operate uses your key to protect all databases and virtual machine disks in your stack. You choose where the key is held, and that choice decides how much independent control you have over it.

BYOK protects data that leaves the running platform, such as storage media and backups. BYOK does not control who can see your data inside the running platform. The next section sets out these limits.

Important: BYOK is not a free increase in security. BYOK comes with significant risks and requires careful key management. Before you adopt BYOK, make sure that you understand what BYOK protects, what it does not protect, and the risks of managing your own key.

What BYOK protects, and what it does not

Choose a key model

You generate the key in both models. The difference is where the key lives after you create it.

The trade-off with a key held in your tenant

Option 2 gives you independent control. Option 2 is the stronger position for audit and for contract termination. In exchange, Clio Operate cannot run without access to your key. Every decision that you make about the key lifecycle has a direct effect on your own service.

With Option 2, you keep sole control of:

• Key creation, rotation and deletion.
• Access grants, and the withdrawal of access grants.
• Vault configuration, and the audit trail of key use.

Clio operates the platform but cannot:

• Export or read your key material.
• Create, modify or delete your keys.
• Change your vault settings, or prevent you from revoking access.

If you choose Option 1, you generate the key and transfer it to Clio through the Azure key import process. Clio then rotates or replaces the key on your instruction. The rest of this article describes Option 2.

How BYOK works

Envelope encryption

Your key does not encrypt your data directly. Your key protects a second key, and that second key encrypts the data. This method is called envelope encryption. It uses three layers:

• Key encryption key (your key): an RSA key of 2048, 3072 or 4096 bits. The key stays in your vault and never leaves your tenant. The key wraps (encrypts) the data encryption key.
• Data encryption key: an AES-256 symmetric key that Azure generates and holds. Azure unwraps the key when the service starts or revalidates, and then caches it. The data encryption key encrypts your data.
• Your data at rest: database pages, disk blocks, backups, snapshots and images.

This design has three consequences:

• Rotation is fast. A new key version re-wraps the data encryption key. Your data is not re-encrypted. Rotation takes seconds for the databases and less than an hour for the disks, with no downtime.
• Availability depends on your key. Azure must reach your key to unwrap the data encryption key. If Azure cannot reach your key, the service stops.
• The key is never exported. Only two operations run against your key: wrap and unwrap. The private key material never leaves your vault, and Clio never holds a copy.

Cross-tenant access

Clio Operate accesses your key through Microsoft Entra workload identity federation. The trust relationship uses no client secret and no certificate. As a result, no credential on the identity side can leak, expire or need rotation.

The trust chain has four parts:

1. App registration (Clio tenant): a Microsoft Entra application. Clio shares the application (client) ID with you.
2. Managed identity (Clio tenant): attached to the application as a federated identity credential. Clio configures the databases and virtual machine disks with this identity, the application ID and your key URI.
3. Service principal (your tenant): the enterprise application that you install. The service principal has the same application ID but its own object ID in your directory. You grant key access to this service principal, and you revoke access from it.
4. Your key vault and keys (your tenant): the vault holds the keys that Clio Operate uses to wrap and unwrap the data encryption keys.

What the access you grant permits

You grant the Clio Operate service principal the Key Vault Crypto Service Encryption User role. This role permits three operations:

• Get: read the public part of the key and the key properties.
• Wrap Key: ask your vault to encrypt the data encryption key.
• Unwrap Key: ask your vault to decrypt the data encryption key, so that the service can start and serve data.

The role does not permit Clio Operate to:

• Export or read the private key material.
• Create, modify or delete keys.
• Change vault configuration, access grants, policies or network rules.
• List other keys or secrets. Access is limited to the keys that you nominate.

Your vault logs every wrap and unwrap request. You can withdraw the role at any time without Clio's involvement. One role assignment covers your whole Clio Operate stack.

Before you start

BYOK is intended for use in environments that hold production data. Contact Clio Operate support to arrange BYOK. Clio sends you the application name and application ID that you need for setup.

Gather this information before you start:

• Your Microsoft Entra tenant ID, and the subscription that will hold the vault.
• The Azure region of your Clio Operate stack. Your vault must be in the same region.
• Whether you will use Key Vault (Standard or Premium) or Managed HSM.
• Whether your vault uses Azure role-based access control (RBAC) or access policies.
• Whether a tenant policy blocks non-administrators from installing applications.
• Your named key custodians, a deputy, and an out-of-hours contact. See Key custodians.
• Your rotation cadence and key lifecycle policy.

Key custodians

More than one person must be able to manage your keys. One deputy is enough if the deputy independently holds the Key Vault Crypto Officer and User Access Administrator roles.

Check whether your team can install applications

Many organisations use a Microsoft Entra policy that blocks non-administrators from installing applications or creating service principals. If this policy applies to you, a privileged administrator must complete step 1 of the setup. Scheduling this administrator is often the longest lead time in the setup, so check this policy early.

Confirm that purge protection is acceptable

Purge protection is mandatory. Azure checks purge protection when Clio sets your key as the encryption protector, and the configuration fails without it. After you enable purge protection, you cannot turn it off. Raise this requirement early with the owner of your vault standards.

Set up BYOK

Setup phases

Setup has four phases. Phase 3 cannot start until you complete phase 2.

Clio uses two identities: one for the databases and one for the disks. With two identities, a problem on one layer cannot affect the other.

Clio recommends two keys: one for the databases and one for the disks. With two keys, you can rotate or revoke the database layer and the compute layer independently. You can also use one key for both.

Set up your tenant

Complete these steps in your own Microsoft Entra tenant. Each step lists the Azure role that it requires.

1. Create a service principal from the application ID that Clio gives you. Alternatively, grant tenant-wide admin consent. 
   Role: Application Administrator, Cloud Application Administrator or Global Administrator.
2. Create a key vault in the same Azure region as your Clio Operate stack. Use Key Vault Standard or Premium, or Managed HSM if you require FIPS 140-2 Level 3. 
   The same-region rule is an Azure requirement. 
   Role: Key Vault Contributor.
3. Enable soft-delete and purge protection on the vault. 
   Role: Key Vault Contributor.
4. Create the RSA keys, of 2048, 3072 or 4096 bits. Do not set an expiry date. 
   Clio recommends one key for the databases and one key for the disks. You can also use one key for both. 
   Role: Key Vault Crypto Officer.
5. Assign the Key Vault Crypto Service Encryption User role to the Clio Operate service principal, scoped to the vault. 
   Role: User Access Administrator.
6. Send Clio the key URIs. Confirm whether your vault uses Azure RBAC or access policies. 
   No elevated role is required.

What Clio does next

After Clio receives your key identifiers, Clio completes the resource configuration:

1. Clio attaches the managed identity and your application ID to the Clio Operate database service.
2. Clio sets your database key as the encryption protector for all Clio Operate databases. Existing databases migrate in place, with no rebuild and no downtime.
3. Clio creates a disk encryption set with the identity, the application ID and your disk key URL.
4. Clio attaches all virtual machine disks to the encryption set. Clio also enables encryption at host, so that caches and temporary disks are covered.
5. Clio configures the databases and the disk encryption set to use new key versions automatically. Clio also enables monitoring and alerting, including a check that detects a missing key version.

Resource configuration takes about one day, plus the disk migration window.

The disk migration requires one planned outage. Azure must deallocate the virtual machines to re-encrypt their disks, so Clio agrees a maintenance window with you. The database change is online and needs no downtime.

Rotate a key

To rotate a key, create a new key version in your vault. Nothing goes offline, and your data is not re-encrypted. The timings below are approximate and come from Microsoft Azure documentation.

Clio recommends that you:

• Set a rotation policy on your keys in your vault, so that new key versions are created automatically. Clio configures Clio Operate to use each new version, so routine rotation needs no coordination with Clio.
• Never set an expiry date on a key. An expiry date causes an outage on that date.
• Tell Clio before any non-routine change, such as replacing a key, disabling a key, or changing the role assignment.
• Name your key custodians and a deputy, and tell Clio when these people change.

Keep every old key version

Important: Do not delete an old key version. Database backups, including log backups, stay encrypted under the key version that was current when each backup was taken. If you delete a superseded version, Clio cannot restore your data from that period.

Neither you nor Clio would discover the problem until a restore was needed. Clio monitors your key version count and alerts if the count drops. Your own key management process must also protect old versions.

Revoke a key

Revocation makes your data unusable to everyone at the same time. This includes your own users, your integrations and Clio support engineers. Only Option 2 lets you revoke without Clio's involvement.

After you disable the key, the service degrades in this order. The timings are approximate and come from Microsoft Azure documentation.

Recover after revocation

Recovery depends on how quickly you restore key access:

• Access restored within 30 minutes: databases recover automatically. Virtual machines need a manual restart.
• Access restored after 30 minutes: databases and virtual machines both need manual intervention. You and Clio must both assess whether any in-progress writes were lost. This assessment is difficult.

Changes to permissions do not take effect immediately. This delay also applies when you restore access.

Clio recommends that you agree the following with Clio before go-live:

• A notice period and named contacts for deliberate revocation.
• An escalation contact, available 24 hours a day, who can re-enable a key.

Avoid accidental revocation

Accidental revocation is a more likely risk than deliberate revocation. Each of these events has the same effect as revoking on purpose:

• An expiry date set on the key, by policy or by habit.
• An old key version deleted during routine key maintenance. This deletion breaks restores rather than the live service, so nobody notices it until a restore is needed.
• The role assignment removed during an access review, or by an automated least-privilege remediation tool.
• The vault, or its resource group, deleted. Soft-delete and purge protection protect against this event.
• The subscription or vault moved to a different Microsoft Entra directory. This move breaks the identity trust.
• A Conditional Access or tenant restriction change that blocks the federated service principal.
• The service principal removed during a clean-up of enterprise applications. To a reviewer, the service principal can look like an unused third-party application.

Clio recommends three safeguards:

• A resource lock on the vault, to prevent accidental deletion.
• A documented exclusion of the vault, the keys and the Clio Operate service principal from access reviews, automated remediation and application clean-up.
• A named escalation contact who is available out of hours. During a revocation incident, Clio can only ask you to re-enable the key.

Clio monitors for key expiry dates, wrap and unwrap failures, changes in key version count, and database inaccessibility. This monitoring helps Clio detect a problem before it causes an outage.

Does BYOK restrict Clio support access?

No. Your key controls whether the data can be decrypted at all. Your key does not control individual access. A Clio engineer with a valid credential who runs a query gets readable data, the same as without BYOK.

Why the key does not restrict support access

Encryption at rest decrypts data below the application. Access decisions happen above that level. The layers work like this, from top to bottom:

• Application and support tooling: sees plain text. A valid credential returns readable data.
• Database engine and guest operating system: serves query results and file reads in plain text.
• Encryption boundary: the internals of Azure storage and the database engine decrypt pages and blocks with the cached data encryption key.
• Your key: unwraps the data encryption key when the service starts or revalidates. Azure uses your key on rotation, not on every query.

BYOK gives you:

• Protection wherever data leaves the running platform, including media, backups, snapshots and images.
• The ability to make your data unusable, at contract termination or on suspicion of compromise.
• Separation of key custody from data custody, with an audit trail as evidence.

Controls that govern support access

These controls address support access. Clio uses just-in-time elevation for support access.