Operate HYOK: upgrades, health, and access

Upgrades

Corsa publishes new HYOK releases for security fixes and features. Upgrading is optional:

There’s no support window. Older releases keep working, and Corsa never blocks decryption because your stack runs an older release.
Each release is labeled Security or Feature. Corsa emails your workspace Owners and shows an in-app notification when a release ships, and sends reminders for security releases.
You decide when to upgrade, and you run the upgrade yourself.

Only a workspace Owner can upgrade. Users with the Support role can review releases and diffs.

Stack managed with Terraform? Corsa hides Upgrade stack and shows Get Terraform template instead. See Install HYOK with Terraform → Upgrade.

See that an update is available

Settings → Encryption shows the installed and latest releases, with the latest release’s label and changelog, under Update available.

Review the source diff

Open the diff in Source audit to see the files added, removed, and changed since your installed release. You can also check the new release with the verification kit.

Click Upgrade stack

Corsa verifies the new release again (its digest, signature, and every file’s SHA-256), then prepares the update for your workspace, your identity provider settings, and the new release. Your stack already authenticates to Corsa with its signing key, so there’s no new callback token. Corsa records the upgrade as pending and opens the CloudFormation change set page for your stack, in its account and region.The link expires after a few hours. If it does, click Upgrade stack again.

Create the change set

Keep the existing parameter values and create the change set. Don’t execute it yet.

Run the pre-upgrade check

Copy the pre-upgrade command from the app and run it in AWS CloudShell, in the stack’s account and region. The check fails if the change set would replace your HYOK key, your stack’s signing key, or your Cognito users. If the check fails, don’t execute the change set. Delete it and contact Corsa. The stack’s built-in protection blocks such a change anyway.

Execute the change set

Execute the change set in the console and wait for UPDATE_COMPLETE. The stack downloads the new release once and checks it before it installs anything.

Wait for completion

When the update finishes, the stack sends its signed details to Corsa. When the reported release digest matches the pending upgrade, Settings → Encryption shows the new release as installed. Any other digest shows as release mismatch drift.

Verify

Run the running-stack check for the new release, then open an encrypted field to confirm that decryption works.

An upgrade never replaces your keys or your Cognito users. Existing encrypted values, including values encrypted by earlier releases, keep decrypting after an upgrade.

Roll back

If the update fails, CloudFormation rolls the stack back automatically. The stack keeps a copy of the previously installed release in your account and reinstalls it from there, without downloading anything. An expired release link can’t block the rollback. If the update completed but you want the previous release back:

Click Roll back

In Settings → Encryption, click Roll back. Corsa prepares an update to the release you ran immediately before the current one.

Check and execute the change set

Follow the same steps as an upgrade: create the change set, run the pre-upgrade check, and execute it. The stack restores the previous release from the copy it keeps in your account.

Verify

Run the running-stack check for the previous release digest.

You can roll back one release only. Corsa refuses to prepare an update to any older release.

Health checks

Your stack exposes a public health endpoint. Settings → Encryption shows its URL. You can call it yourself:

curl -i <your-health-url>

{
  "status": "ok",
  "checks": {
    "kms": true,
    "cognito": true,
    "oidc": null,
    "stackPolicy": true,
    "codeSigning": true
  },
  "releaseDigest": "9f2c…",
  "stackPolicySha256": "4b1e…",
  "identityProvider": "cognito",
  "timestamp": "2026-10-09T12:00:00.000Z"
}

Field	Meaning
`status`	`ok` when every check that applies is `true`, `degraded` when any is `false`
`checks.kms`	Your HYOK key and the stack’s signing key are enabled and usable
`checks.cognito`	Cognito sign-in is reachable. `null` when you use your own identity provider
`checks.oidc`	Your identity provider’s issuer is reachable. `null` when you use Cognito
`checks.stackPolicy`	The stack’s built-in protection for your keys and Cognito users is in place
`checks.codeSigning`	The stack only accepts Corsa-signed code
`releaseDigest`	The release your stack runs
`stackPolicySha256`	A fingerprint of the stack’s current protection settings. The Verify page shows the expected value
`identityProvider`	`cognito` or `oidc`

The response carries X-Corsa-Timestamp and X-Corsa-Signature headers: an ECDSA-SHA256 signature by your stack’s signing key over <timestamp>.<body>. Corsa polls the endpoint every 5 minutes, verifies the signature against the key your stack registered, and rejects responses more than 5 minutes old. The result appears in Settings → Encryption and as healthStatus and lastHealthAt in the encryption configuration. A false for stackPolicy or codeSigning also appears as drift. The health endpoint reveals no keys, users, or data.

Drift

Corsa compares what your stack reports with what it expects and shows any difference as a drift badge in Settings → Encryption. Drift doesn’t stop decryption. It tells you that your stack no longer matches the release and guardrails you installed.

Drift	Meaning	What to do
Release mismatch (`release_mismatch`)	The stack reports a release digest that is neither your installed release nor a pending upgrade	Run the running-stack check. In CloudTrail, find who updated the stack. If nobody in your team made the change, treat it as a security incident. Then upgrade or roll back from the app to get back to a known release
Stack policy missing (`stack_policy_missing`)	The stack’s built-in protection for your keys was removed or changed	In CloudTrail, find who changed it. Don’t update the stack outside Upgrade stack or Roll back until it’s fixed. The stack restores its protection during its next update. Contact Corsa if you need it restored sooner
Code signing off (`code_signing_off`)	The stack no longer refuses code that Corsa didn’t sign	Run the running-stack check to see whether any code changed, and contact Corsa to restore the protection. If code changed, disable your HYOK key until you restore the release, and treat it as a security incident
Account mismatch (`account_mismatch`)	A stack reported its details from a different AWS account than the one you declared. Corsa rejected them	Deploy the stack in the declared account. See Troubleshooting
Region mismatch (`region_mismatch`)	A stack reported its details from a different region than the one you declared. Corsa rejected them	Deploy the stack in the declared region. See Troubleshooting

Control access to decryption

Goal	Action in your AWS account or identity provider	Effect
Remove one person’s access	With Cognito, remove them from `hyok-decryptors` or disable their Cognito user. With your own identity provider, remove them from the decryptor group or disable their account	Their next unwrap fails. With your own identity provider, tokens already issued stay valid until they expire
Pause all decryption (kill switch)	Disable your HYOK key in AWS KMS (`aws kms disable-key --key-id <your-hyok-key-arn>`). Settings → Encryption shows the key ARN	Nobody can decrypt, including your users. Health becomes `degraded`. Re-enable the key to resume
Investigate access	Read your stack’s decryption audit log and the CloudTrail `Decrypt` events for your HYOK key. Settings → Encryption → Review resources shows where the audit log is	One audit line per unwrap: user, Corsa token ID, field, outcome

While decryption is paused, Corsa keeps working on everything else. Exact search and exact-match screening also keep working, because they use the keyed index rather than decryption.

Never schedule your HYOK key for deletion while HYOK data exists. Deleted keys can’t be restored, and the data becomes permanently unreadable.

Incident settings

Your stack has a few settings that Corsa may ask you to change during an incident, for example to keep older encrypted values readable. Change them only when Corsa support asks you to, and follow the instructions Corsa gives you. Leave them unchanged otherwise.

Overview

Compliance

Platform Security

Customer-managed encryption

Single Sign-On

AI Security

Vulnerability Disclosure

Operate HYOK: upgrades, health, and access

Upgrades

Roll back

Health checks

Drift

Control access to decryption

Incident settings

​Upgrades

​Roll back

​Health checks

​Drift

​Control access to decryption

​Incident settings

Upgrades

Roll back

Health checks

Drift

Control access to decryption

Incident settings