Customer-managed encryption keys

Joring encrypts each team's stored content under a data key that belongs to that team. By default Joring holds the key that wraps it. On Enterprise, you can supply a KMS key in your own AWS account instead, and Joring's copy of your team's data key is wrapped under yours.

The practical consequence is the one that matters: disabling or deleting your key ends Joring's ability to read your team's stored content, immediately and without Joring's cooperation.

This is separate from LLM keys, which decide whose provider account inference runs against. The two are independent and can be used together.

What this protects, and what it does notCopy Anchor Link

Joring is not zero-knowledge. To score a conversation, coach a prompt, or build a trail, Joring decrypts content in memory in its own environment. Prompt text is also sent to OpenAI and Anthropic for inference, under agreements that exclude customer data from training. A customer-managed key does not change either of those facts.

It changes what happens after the relationship ends, and what happens outside the running system. A backup, a snapshot, a subpoena served on Joring, or a Joring acquirer yields no readable content once the key is revoked, and the decision to revoke sits with the key holder rather than in a contract term.

Before you startCopy Anchor Link

• An AWS account you control, and permission to create a KMS key in it.
• Your Joring team ID, shown on the setup screen. Copy it rather than retyping it. It is written into the key policy as a case-sensitive condition value.

The key can be created in any AWS region. Joring reads the region from the key ARN and calls KMS there, so no additional configuration is needed.

Set up the keyCopy Anchor Link

https://joring-byok-templates-800153535945.s3.us-east-1.amazonaws.com/joring-byok-key.yaml

The key policyCopy Anchor Link

The key policy has four statements. Two of them carry the security properties described above.

Joring is granted six actions and no others: kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, kms:DescribeKey, kms:ReEncryptFrom, and kms:ReEncryptTo. There is no kms:* anywhere in Joring's grant.

The tenant conditionCopy Anchor Link

The five cryptographic actions carry a condition:

"Condition": {
  "StringEquals": {
    "kms:EncryptionContext:joring:tenant": "<your team id>"
  }
}

Joring's encryption layer binds the tenant into the KMS encryption context on every wrap and unwrap. This condition requires that value to be yours. A request from Joring that named another tenant, through a bug, a misrouted job, or a deliberate act, is refused by KMS before any cryptography happens.

Without the condition, cross-tenant use of your key is prevented by Joring's code. With it, it is refused by AWS, evaluated in your account, under a policy only you can change.

Joring does not assume the condition is present. During validation it attempts a decrypt with a deliberately wrong tenant value and requires the call to fail with AccessDenied. The distinction is exact: a wrong encryption context fails on its own cryptographic merits and returns InvalidCiphertext, which proves nothing about your policy. Only AccessDenied proves the condition is there and enforced. If Joring sees the weaker result, it accepts the key but records that the condition is absent and says so on the setup screen.

kms:DescribeKey sits in its own statement without the condition, because DescribeKey carries no encryption context and a condition on one could never match it.

The administration denyCopy Anchor Link

The policy then denies Joring, by name, every key-administration action: kms:ScheduleKeyDeletion, kms:CancelKeyDeletion, kms:DisableKey, kms:EnableKey, kms:PutKeyPolicy, kms:CreateGrant, kms:RetireGrant, kms:RevokeGrant, kms:TagResource, kms:UntagResource, the rotation controls, alias management, replication, and key material import.

The grant already omits all of these, so nothing in the deny list is reachable today. The deny exists so that it stays unreachable through a future policy edit that widens the grant, a change to Joring's own IAM, a support engineer with elevated access, or a change of ownership of Joring.

An explicit deny in a key policy cannot be overridden by any allow, in any policy, in either account. So Joring cannot cancel a deletion you schedule or re-enable a key you disable. And because kms:CreateGrant is denied, Joring cannot mint a grant to widen its own access or escape the tenant condition.

Revoking accessCopy Anchor Link

Disable or delete the key in KMS. Nothing is required from Joring, and Joring cannot delay it.

Joring probes your key every 60 seconds and locks the team after three consecutive failures, so a revocation is confirmed in about three minutes. Errors that indicate a temporary problem rather than a revoked key, such as throttling or a network fault, do not count toward that total, so a passing outage does not lock your team.

Unwrapped key material is cached for up to 300 seconds on top of that, so the lock is fully in effect within roughly ten minutes at worst, and usually much sooner.

While a team is locked:

• The API returns 423 for any request that would read or write protected content.
• Capture clients pause until the team is unlocked.
• Sign-in and team administration keep working, so you can see the state and act on it.

RotationCopy Anchor Link

Three different things get called rotation. They have different effects, and only one of them needs anything from you.

AWS rotates your key automaticallyCopy Anchor Link

Nothing happens on Joring's side. Automatic rotation changes the backing material behind the same key, and the ARN does not change. KMS selects the correct backing key when decrypting older ciphertext. Joring does not need to know it happened, and there is nothing to do.

You replace the key with a different oneCopy Anchor Link

Enter the new ARN in Settings → Encryption. Joring validates it the same way, then rewraps your team's data key from the old key to the new one using ReEncryptFrom and ReEncryptTo.

Your data is not migrated or re-encrypted. Only the wrapped data key changes, which is a few hundred bytes, so the operation completes in under a second regardless of how much content the team has.

Joring rotates the team data keyCopy Anchor Link

Joring can issue a new version of your team's data key, wrapped under your current key. New content uses the new version. Existing content keeps the version it was written under and stays readable, because every stored value records which version encrypted it. Nothing is rewritten and no content becomes unreadable.

What is recordedCopy Anchor Link

Every change to this configuration lands in the audit log:

encryption.tenant.locked is the one to alert on. It means Joring can no longer reach your key, whether or not anyone intended that.