Customer-Managed Encryption Keys¶

ARX supports Customer-Managed Encryption Keys (CMEK), allowing organizations to control the encryption keys used to protect their data. This guide covers the envelope encryption model, supported key providers, configuration, key rotation, and connectivity testing.

Encryption Architecture¶

ARX uses envelope encryption with AES-256-GCM:

1. Data Encryption Key (DEK): A unique AES-256 key is generated for each piece of sensitive data (connector credentials, secrets, etc.). The DEK encrypts the data using AES-256-GCM, which provides both confidentiality and integrity.

2. Key Encryption Key (KEK): The DEK is encrypted (wrapped) by the KEK. Only the encrypted DEK is stored alongside the ciphertext.

3. KEK Provider: The KEK lives in an external key management system. ARX never stores the KEK directly -- it calls the KMS to wrap and unwrap DEKs as needed.

Plaintext --> [AES-256-GCM with DEK] --> Ciphertext + Encrypted DEK
                                              |
                    DEK wrapped by KEK via KMS Provider

KEK Providers¶

ARX supports four KEK sources:

Platform-Managed Keys¶

By default, ARX manages encryption keys through its internal Vault instance. No configuration is needed. This is suitable for organizations that do not require customer-controlled key management.

AWS KMS¶

Provide the ARN of an AWS KMS key:

arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

Ensure the ARX service role has the following IAM permissions on the key: - kms:Encrypt - kms:Decrypt - kms:GenerateDataKey

Azure Key Vault¶

Provide the Key Vault key URI:

https://mykeyvault.vault.azure.net/keys/arxsec-kek/abc123def456

Grant the ARX service principal the Key Vault Crypto User role on the key.

GCP Cloud KMS¶

Provide the key resource path:

projects/my-project/locations/us-central1/keyRings/arxsec/cryptoKeys/arxsec-kek

Grant the ARX service account the roles/cloudkms.cryptoKeyEncrypterDecrypter role.

Configuration¶

View Current Configuration¶

GET /v1/settings/encryption

Returns the organization's current encryption configuration. If no custom configuration exists, the platform-managed default is returned.

Update Configuration¶

PUT /v1/settings/encryption

{
  "kek_source": "aws_kms",
  "kek_id": "arn:aws:kms:us-east-1:123456789012:key/12345678-...",
  "kek_region": "us-east-1"
}

Setting kek_source to platform switches back to ARX-managed encryption and does not require a kek_id.

All encryption configuration endpoints require the admin role.

Key Rotation¶

Rotate the KEK to use a new key version or a completely new key:

POST /v1/settings/encryption/rotate

{
  "new_kek_id": "arn:aws:kms:us-east-1:123456789012:key/new-key-id"
}

The rotation process:

1. ARX validates that the new key is accessible.
2. The KEK configuration is updated to point to the new key.
3. Existing DEKs remain wrapped with the old KEK until re-encryption is performed.

After rotation, schedule re-encryption of existing data to ensure all DEKs are wrapped with the new KEK. The response confirms this:

{
  "status": "rotated",
  "message": "KEK rotation complete. Schedule re-encryption of existing data."
}

For AWS KMS and GCP Cloud KMS, you can also use the provider's automatic key rotation feature, which rotates the underlying key material while keeping the same key ID.

Testing Connectivity¶

Before committing to a CMEK configuration, test that ARX can access the key:

POST /v1/settings/encryption/test

{
  "kek_source": "aws_kms",
  "kek_id": "arn:aws:kms:us-east-1:123456789012:key/12345678-...",
  "kek_region": "us-east-1"
}

Response:

{
  "accessible": true,
  "message": "KMS key is accessible and operational."
}

or:

{
  "accessible": false,
  "message": "KMS key is not accessible. Check ARN/URI and IAM permissions."
}

Always run a connectivity test before updating the encryption configuration to avoid data access issues.

Operational Considerations¶

1. Key deletion risk: If a CMEK key is deleted or access is revoked, ARX cannot decrypt any data protected by that key. Ensure key lifecycle policies prevent accidental deletion.

2. Cross-region latency: Using a KMS key in a different region than the ARX deployment adds latency to every encrypt/decrypt operation. Use a key in the same region when possible.

3. Audit trail: All encryption configuration changes and key rotations are logged. Review the audit log to track who changed the encryption settings and when.

4. Fallback: To revert to platform-managed encryption, set kek_source to platform. Existing data wrapped with the CMEK key must be re-encrypted with the platform key.

Troubleshooting¶

Related Documentation¶

• Authentication Overview
• RBAC & Roles
• SIEM Export