Overview
DuoKey for Atlassian Cloud
Atlassian customer-managed keys (CMK) backed by an AWS KMS key in a DuoKey external key store
What is Atlassian CMK?
Atlassian Cloud encrypts data at rest with Atlassian-managed keys by default. Customer-managed keys (CMK) let an organization admin protect the data of new Atlassian Cloud sites with AWS KMS keys that live in the customer's own AWS account. Atlassian creates one CMK encryption policy per organization; it covers all data in scope for the new sites enrolled under it (Atlassian: Use customer-managed keys).
With DuoKey, the AWS KMS key you give Atlassian is created in an AWS KMS external key store (XKS). AWS KMS forwards every cryptographic operation on that key to the DuoKey XKS proxy, and the key material stays in your DuoKey vault. Neither Atlassian nor AWS ever holds it.
Key outside AWS and Atlassian
The KMS key ARN Atlassian uses points to a key whose material sits in DuoKey, not in AWS KMS.
Your kill switch
Disable the key in AWS KMS or block it in DuoKey, and Atlassian loses access to the plaintext.
Two audit trails
AWS CloudTrail on the AWS side, the DuoKey journal on yours, both carrying Atlassian's encryption context.
Architecture
Architecture
Atlassian Cloud CMK with a DuoKey external key
Atlassian calls AWS KMS in your account. Because the key lives in an external key store, every operation is forwarded to the DuoKey XKS proxy, and the key material stays in your vault.
| Layer | Component | Role |
|---|---|---|
| Atlassian Cloud | CMK-enabled apps | Application-level encryption before persistence, and server-side encryption by AWS-managed services |
| Atlassian Cloud | RDS, OpenSearch, EBS | Use the KMS key through grants scoped by Atlassian's key policy |
| Your AWS account | AWS KMS key | Symmetric, single-Region key in the realm's region, created in an external key store |
| Your AWS account | External key store | Connects AWS KMS to the DuoKey XKS proxy over HTTPS with SigV4 authentication |
| DuoKey | XKS proxy | Answers the XKS API, enforces policy, records every request |
| DuoKey | MPC vault or HSM | Holds the key material; it is never exported |
How a request flows
Sequence
One Atlassian request through DuoKey
The encryption context Atlassian sends travels with the request and appears in CloudTrail and in the DuoKey journal.
- An Atlassian service needs to encrypt or decrypt and calls AWS KMS with your key ARN and Atlassian's encryption context (a tenant identifier and the tag you chose at enrollment).
- Because the key's origin is an external key store, AWS KMS forwards the operation to the DuoKey XKS proxy, signed with SigV4.
- The proxy checks the request, has the DuoKey vault perform the operation with the key material, and returns the result.
- AWS KMS returns the result to Atlassian. CloudTrail records the call with the encryption context; DuoKey records it in its journal.
Encryption context
At enrollment, Atlassian generates a unique encryption context identifier that includes the tag you choose (up to 12 alphanumeric characters). It is used as additional authenticated data (AAD), appears in CloudTrail, and lets you add conditions on it to the key policy (Atlassian: What is CMK encryption).
Key requirements
| Requirement | Atlassian CMK | DuoKey XKS key |
|---|---|---|
| Key type | Symmetric, encrypt and decrypt | Symmetric encryption only |
| Regionality | Single-Region, one key per region of the realm | Single-Region (multi-Region keys are not supported in an external key store) |
| Key policy | Atlassian template (grants for RDS, OpenSearch, EBS; DescribeKey) | Attach the Atlassian template when creating the key |
| Grants | Required (kms:CreateGrant) | Supported for keys in an external key store |
| Automatic rotation | Enabled by the Atlassian CloudFormation template | Not supported: rotate manually by moving to a new key |
Create the key with the manual setup (AWS CLI or console), not with Atlassian's CloudFormation template: the template enables automatic key rotation, which AWS KMS does not support for keys in an external key store.
Realms and regions
You create one KMS key per region of the realm you choose at enrollment. A dual-region realm needs two keys, so two external key stores, one in each region (Atlassian: Set up your AWS account).
| Realm | AWS regions |
|---|---|
| Europe (dual-region) | eu-central-1, eu-west-1 |
| United States (dual-region) | us-east-1, us-west-2 |
| Switzerland | eu-central-2 |
| Germany | eu-central-1 |
| United Kingdom | eu-west-2 |
| Australia, Canada, India, Japan, South Korea, Singapore | ap-southeast-2, ca-central-1, ap-south-1, ap-northeast-1, ap-northeast-2, ap-southeast-1 |
The realm is fixed at enrollment: Atlassian cannot migrate the data out of the chosen realm afterwards.
Availability
With an external key store, the availability of the DuoKey XKS proxy becomes the availability of your Atlassian data. AWS KMS waits at most 250 milliseconds for the proxy; failures return KMSInvalidStateException. When Atlassian loses access to the key, it starts its revocation process and suspends the CMK-enabled sites.
Design the XKS proxy for high availability before enrolling: several MPC nodes, health monitoring, low latency to the realm's AWS regions, and alerting on XKS errors in CloudTrail. See AWS XKS Getting Started, pattern 3 (high availability).
Revocation and restore
State machine
Revocation and restore
Revocation is an emergency lever: Atlassian suspends the CMK-enabled sites once it loses access to the key, and restores them after the key is re-enabled.
- Revoke: disable the KMS key in AWS KMS (both keys for a dual-region realm), or block the key in DuoKey. Atlassian suspends the sites, typically within 30 minutes to one hour, with potential data loss of up to one hour before the revocation event (Atlassian: Revoke access).
- Restore: enable the key again, then reply to the Atlassian support ticket. Atlassian can reinstate suspended sites within 10 days; beyond 20 days it may be unable to fully recover the data. Restoration generally completes within two business days after the ticket is addressed (Atlassian: Restore access).
Revocation is an emergency measure. Do not disable keys during an Atlassian re-encryption process: data access can end up uneven across sites.
Costs
You pay for the KMS key storage; KMS API request costs are billed to Atlassian. The DuoKey XKS proxy and vault are part of your DuoKey subscription.