Skip to main content

Encrypt and decrypt your data with managed keys

Customer-managed encryption keys (CMEK) let you encrypt and decrypt your data with a KMS key you own in your AWS account. You register the key in AWS, and Crusoe uses it at runtime through a role you control.

info

Customer-managed encryption keys (CMEK) are currently only available for Serverless Fine-Tuning. When you register a CMEK for a project in Crusoe, all future jobs will automatically use the CMEK for encryption and decryption.

How access works​

To give CMEK access to the KMS key you store in AWS, you need to:

  1. Create a single AWS Identity and Access Management (IAM) role in your AWS account that:
    • Trusts Crusoe's CrusoeCMEK role to assume it, with your Crusoe project ID as the ExternalId, for tenant isolation.
    • Has permission to call kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, and kms:ReEncrypt* on the specific KMS key you want CMEK to use. Currently, CMEK only calls Encrypt and Decrypt.
  2. Add the role's Amazon Resource Name (ARN) to Crusoe for storage and use at runtime.

Trust chain values​

Crusoe provides two values that remain stable across the lifetime of your account: the Crusoe CMEK role ARN and an ExternalId.

ValueSourceWhere you use itDescription
Crusoe CMEK role ARNarn:aws:iam::1805901
99243:role/CrusoeCMEK		Principal.AWS in your role's trust policyThe ARN of the Crusoe CMEK role that you'll use in your AWS IAM role's trust policy.
ExternalIdYour Crusoe project ID(s)sts:ExternalId condition in your trust policyThe ID that registers the key. To share one KMS key across many projects, list every project ID in the sts:ExternalId condition (StringEquals accepts an array) and register the key in each project.

Configure CMEK​

Use the AWS console (UI) or the AWS CLI to create a KMS key and an IAM role that trusts the CrusoeCMEK role, and then register the key with Crusoe.

Prerequisites​

  • An AWS account with permission to create KMS keys and IAM roles.
  • A Crusoe project ID (used as the ExternalId). To find your project ID in the console, go to projects and click the copy icon next to the project name.
  • Access to the Crusoe console to register the key.

1. Create (or pick) the KMS key​

From the KMS console (in your chosen region), go to Customer managed keys and select Create key. Then, fill in the following fields:

  1. For Key type, enter Symmetric.
  2. For usage, select Encrypt and decrypt. Click Next.
  3. For Alias, enter crusoe-CMEK.
  4. Assign yourself as key administrator and user.
  5. Click Finish.
  6. Open the key and copy its ARN: arn:aws:kms:<region>:<account-id>:key/<key-uuid>.

2. Create the IAM role (trust and KMS policy)​

  1. In the IAM console, go to Roles → Create role → Custom trust policy, then paste the following and replace the ExternalId with your Crusoe project ID:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": { "AWS": "arn:aws:iam::180590199243:role/CrusoeCMEK" },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": { "sts:ExternalId": "<your-crusoe-project-id>" }
          }
        }
      ]
    }

  2. Click Next (skip Attaching managed policies), name the role CrusoeCMEKKmsAccess, and click Create role.

  3. Open the role → Add permissions → Create inline policy → JSON, and paste the following, replacing <your-kms-key-arn> with your key ARN:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:GenerateDataKey",
            "kms:ReEncrypt*"
          ],
          "Resource": "<your-kms-key-arn>"
        }
      ]
    }

  4. Name it KmsAccess and click Create policy. Copy the role ARN from the role summary.

3. Register the key with Crusoe​

To register your key with Crusoe:

  1. From the Crusoe console, click Encryption Keys. If you have multiple projects, select a project in the top-left corner first, then click Encryption Keys.
  2. Click Register Key.
  3. Fill in the Key ARN (from step 1) and Role ARN (from step 2).
note

A project may register at most one active external key. A second registration returns 409 Conflict. Delete the existing key first (a soft-deleted key doesn't block a new one).

Crusoe returns an external_key_id (a Crusoe-side identifier) and validates the setup before activating it: CMEK assumes your role, using your Crusoe project ID as the ExternalId, and performs a no-op Encrypt and Decrypt round trip on the key. If validation fails—for example, if the trust policy or ExternalId doesn't match, or the role can't call kms:Encrypt or kms:Decrypt on the key—the registration is rejected with an error describing what failed, so you can fix the trust or key policy and retry. On success, the registration is active and ready for CMEK-protected workloads.

note

CMEK currently doesn't support key replacement. Registering a new key doesn't re-encrypt data that was encrypted under a previous key. See Revoking access before deleting a registered key.

To use the same key from another Crusoe project, add that project's ID to the sts:ExternalId list in the role's trust policy, then repeat this step from the other project.

Automatic fine-tuning job encryption​

When you register a CMEK for a project in Crusoe, all future jobs will automatically use the CMEK for encryption and decryption. To create a fine-tuning job, see Fine-tune a model.

Rotation behavior​

Underlying KMS key​

Nothing changes on your side. AWS KMS embeds the key version in the ciphertext, so CMEK transparently uses the new version after rotation. No re-registration is required.

CrusoeCMEK role​

The CrusoeCMEK role ARN is intentionally stable and won't change. If a migration is ever required, Crusoe will provide explicit migration instructions with a notice.

Revoking access​

Delete the role or detach the KMS policy:

aws iam delete-role-policy --role-name CrusoeCMEKKmsAccess --policy-name KmsAccess
aws iam delete-role --role-name CrusoeCMEKKmsAccess

Alternatively, unregister the key through the Crusoe console. This leaves your AWS resources in place and CMEK stops calling them.

warning

Deleting the KMS key causes permanent data loss. CMEK doesn't currently support key replacement: files uploaded to the project are encrypted under the registered key. If that key is deleted in AWS, those files are permanently unrecoverable. Crusoe can't decrypt them, and registering a new key doesn't re-encrypt or recover existing data.

If the key stops working without being deleted (for example, the key is disabled, the role is deleted, or the trust or key policy is broken), data isn't lost. Decryption fails until you restore access, and existing files decrypt again when access is restored.

Reporting​

You can audit key usage from your own account. Every CMEK call assumes your role and reaches your KMS key, so it appears in your AWS CloudTrail. The STS role session name is CMEK-<crusoe-project-id>, which lets you attribute each call to the Crusoe project that made it.

Troubleshooting​

AccessDenied on AssumeRole when CMEK tries to use the key​

  • Confirm the ExternalId in your trust policy is the Crusoe project ID the key is registered in (every project ID, if shared across projects).
  • Confirm the Principal in your trust policy is arn:aws:iam::180590199243:role/CrusoeCMEK (exact, no typos).

Role can be assumed but the KMS call fails​

  • Check that kms.json was attached and references the right key ARN. Run aws kms describe-key --key-id <arn> from a session assumed into the role to verify access.
  • Don't add Condition blocks (for example, kms:EncryptionContext:*) to the role's KMS policy or the key policy. Registration validation doesn't send encryption context, so such conditions reject it, and condition denials during later operation surface as opaque failures rather than actionable errors.