Bring Your Own Key (BYOK): Customer-Managed Encryption for Terraform Platforms

When your security team asks whether you control the encryption keys on your Terraform platform, the honest answer with most tools is no. The platform vendor manages the keys. Your Terraform variables, including cloud credentials, database passwords, and API tokens, are encrypted, but if the vendor rotates, loses, or is compelled to expose those keys, you have no recourse.

BYOK (Bring Your Own Key) changes that. You supply a KMS key from your own AWS or GCP account. Scalr uses it to encrypt sensitive data but never stores the key itself. You retain full control: rotate the key on your own schedule, restrict access to it, or revoke it entirely to immediately shut down Scalr's access to your account data.

This article covers what BYOK protects, how the encryption model works, which compliance frameworks it satisfies, and how to set it up in Scalr with AWS KMS or GCP Cloud KMS.

What BYOK Protects

BYOK in Scalr encrypts account-level configuration data stored in Scalr's database:

• Terraform and shell variables (including sensitive values marked as secrets)
• Provider configuration credentials (AWS access keys, GCP service account keys, etc.)
• Workspace metadata (names, settings)
• VCS provider tokens and SSH keys

It does not apply to Terraform state files. State is a separate concern, if you need to control where state is stored and how it's encrypted, use Storage Profiles, which redirect state to a bucket in your own AWS, GCP, or Azure account. BYOK and Storage Profiles address different layers and can be used together.

How the Encryption Model Works

Scalr uses envelope encryption, the same pattern AWS and GCP use internally.

When you enable BYOK, Scalr generates a random 256-bit data encryption key (DEK) and immediately encrypts it with your KMS key (called the key encryption key, or KEK). The KEK never leaves your KMS. Scalr stores only the wrapped (encrypted) DEK.

Every time Scalr needs to read or write sensitive data, it calls your KMS API to decrypt the DEK, uses the DEK to decrypt the data with AES-256-GCM, then discards the plaintext DEK from memory.

The practical implication of this model: revoking Scalr's access to your KMS key immediately prevents Scalr from decrypting any account data. This is the "emergency stop" that compliance teams want.

Warning: Do not disable or delete your KMS key while BYOK is active. If the key becomes inaccessible, Scalr cannot decrypt account data and operations will fail. Only revoke access when you intend to stop using the account.

Who Needs BYOK

BYOK is not required for most Terraform teams. Scalr encrypts all sensitive data at rest by default, using platform-managed keys with strong operational controls. BYOK is for organizations where compliance, contractual, or internal security requirements specifically demand customer-managed encryption keys.

The frameworks and regulations that commonly drive this requirement:

SOC 2 Type II — The Availability, Confidentiality, and Security trust service criteria do not mandate BYOK, but auditors increasingly ask about key ownership when third-party platforms store credentials. BYOK provides clean answers to CC6.1 (logical access controls) and CC9.2 (vendor management).

HIPAA — The HIPAA Security Rule (45 CFR § 164.312) requires encryption of ePHI at rest and in transit, but does not specify key management requirements. However, Business Associate Agreements (BAAs) frequently include language requiring customer control over encryption keys. If your Terraform configurations reference systems that process ePHI, BYOK helps satisfy BAA requirements and supports your documentation of technical safeguards.

FedRAMP — FedRAMP Moderate and High baselines (NIST SP 800-53 SC-12, SC-28) require strong protection of cryptographic keys, with customer-managed keys often expected for sensitive workloads. BYOK directly addresses SC-28 (Protection of Information at Rest).

GDPR / EU Data Residency — While GDPR does not mandate BYOK, it requires "appropriate technical measures" for personal data protection. For organizations operating under data processing agreements that specify encryption controls, BYOK demonstrates that the data controller (you) has sole ability to render data inaccessible, which is a defensible position under Art. 32.

PCI DSS — Requirement 3.5 (protect keys used to secure stored cardholder data) and Requirement 3.6 (key management procedures) can require customer-managed keys in environments where your Terraform configurations store or manage payment infrastructure.

Internal security policy — Many security teams apply a zero-trust posture to SaaS vendors: assume the vendor may be breached or compelled, and ensure that a breach of the vendor cannot expose your secrets. BYOK enforces this at the cryptographic layer.

Scalr BYOK vs. HCP Terraform HYOK

HCP Terraform has a similar feature called HYOK (Hold Your Own Key), available on the Premium plan. It's worth understanding the differences, because they cover different data and work differently.

What's encrypted: HCP Terraform HYOK encrypts state files and plan files. Scalr BYOK encrypts variables, provider credentials, and workspace metadata stored in Scalr's database. For state file encryption in Scalr, you use Storage Profiles to store state in your own cloud bucket where your existing bucket-level key management applies. The two approaches address the same underlying concern (key ownership) but at different layers.

How encryption happens: HCP Terraform HYOK encrypts artifacts locally using an HCP Terraform agent running on your own infrastructure, before they're uploaded to HashiCorp's storage. Scalr BYOK works differently: Scalr calls your KMS API directly to wrap and unwrap the data key. There is no agent to deploy.

KMS support: HCP Terraform HYOK supports AWS KMS, Azure Key Vault, GCP Cloud KMS, and Vault. Scalr BYOK supports AWS KMS and GCP Cloud KMS today.

One important caveat on HCP Terraform HYOK: once you enable it on a workspace, it cannot be disabled. That's a meaningful operational constraint worth noting before adopting it.

If you're migrating from HCP Terraform to Scalr and need equivalent key control coverage, the combination is Scalr BYOK (for variable/credential encryption) plus Storage Profiles pointing to your own bucket (for state).

Setting Up BYOK in Scalr

BYOK is available on the Scalr enterprise plan.

With AWS KMS

Step 1: Create a KMS key

Create a symmetric KMS key in AWS (us-east-1 or us-east-2) with Key Usage set to "Encrypt and decrypt." A multi-region key (key ID starting with mrk-) is recommended — it lets you replicate the key to additional regions later without re-encrypting your data.

Step 2: Grant Scalr the required IAM permissions

Scalr needs three permissions on the key:

{
  "Effect": "Allow",
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:DescribeKey"
  ],
  "Resource": "arn:aws:kms:{REGION}:{ACCOUNT_ID}:key/{KEY_ID}"
}

Scalr supports three authentication methods for AWS KMS — choose the one that fits your security posture:

Access Keys — An IAM user with the above permissions. Simple to set up but stores long-lived credentials in Scalr.

Assume Role — Scalr assumes an IAM role in your account via a cross-account trust policy with an external ID. No long-lived credentials stored. This is the recommended approach for most teams.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::919814621061:user/scalr-saas" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "{YOUR_EXTERNAL_ID}" }
    }
  }]
}

919814621061 is Scalr's AWS account ID. Use a unique string you generate for YOUR_EXTERNAL_ID.

OIDC (Web Identity) — Scalr uses a short-lived OIDC token to assume a role via sts:AssumeRoleWithWebIdentity. No credentials stored anywhere. Strongest option if you already use OIDC for workload identity in your environment.

Step 3: Enable BYOK in Scalr

Go to Account Settings → Security → Encryption, click Enable, select AWS KMS, choose your authentication method, and enter the key ARN and credentials. Scalr validates access to the key before saving — if the key cannot be reached, the configuration will not be applied.

Full setup details: AWS KMS setup guide.

With GCP Cloud KMS

Step 1: Create a KMS key

In GCP Cloud KMS, create a symmetric encryption key in the key ring of your choice. Note the full resource name:

projects/{PROJECT_ID}/locations/{LOCATION}/keyRings/{KEY_RING}/cryptoKeys/{KEY_NAME}

Step 2: Grant Scalr access via a service account

Create a GCP service account and grant it the Cloud KMS CryptoKey Encrypter/Decrypter role on your key. Download a JSON service account key.

Step 3: Enable BYOK in Scalr

Go to Account Settings → Security → Encryption, click Enable, select GCP Cloud KMS, enter your key resource name, and upload the service account key JSON.

Full setup details: GCP KMS setup guide.

Disabling BYOK

To disable BYOK, go to Account Settings → Security → Encryption and click Disable. Scalr re-encrypts your data key under Scalr's own platform key. Your KMS key is no longer called. This is a clean transition, no data loss and no re-encryption of stored data beyond the DEK wrapper.

Frequently Asked Questions

Does BYOK cover Terraform state files?

No. BYOK encrypts account configuration metadata in Scalr's database: variables, credentials, workspace settings. For state file encryption control, use Storage Profiles to store state in your own cloud bucket, where your existing key management policies apply. The two features address different layers and can be used simultaneously.

What happens if I revoke Scalr's access to the KMS key?

Scalr will no longer be able to decrypt account data. Workspace operations, variable reads, and provider configuration access will fail immediately. This is by design as it gives you a hard "off switch" for your account data that does not depend on Scalr's operational procedures.

Does BYOK add latency to Terraform runs?

The DEK wrap/unwrap happens when Scalr reads sensitive configuration at the start of a run. For a typical run, this adds one or two KMS API calls, which complete in single-digit milliseconds. Run execution time is not meaningfully affected.

Can I use BYOK to satisfy my vendor security questionnaire?

Yes. Scalr can provide documentation of the BYOK architecture, the IAM permissions required, and the data categories covered for your security review process. Reach out to support and we can provide the relevant documentation.

Summary

BYOK in Scalr gives you cryptographic control over the encryption keys protecting your Terraform variables, cloud credentials, and workspace configuration. Using a KMS key that stays in your own AWS or GCP account. It satisfies the key management requirements in SOC 2, HIPAA, FedRAMP, and PCI DSS audits without requiring a self-hosted deployment.

To get started, see the BYOK documentation or the provider-specific setup guides for AWS KMS and GCP Cloud KMS. If you're evaluating whether Scalr fits your compliance requirements, you can also book a demo or start a free trial.