Skip to main content
With HYOK (Tier 2), you host the decryption side of Corsa’s field-level encryption in your own AWS account. Sensitive client fields are encrypted under an RSA key in your AWS KMS. Corsa stores only ciphertext and a keyed search index. To see a value, a user signs in to your own identity pool with a passkey, and the value is decrypted in their browser. HYOK is for workspaces where stored sensitive fields must stay unreadable to Corsa. You keep exact-match search and exact-match sanctions screening on those fields. Fuzzy features don’t work on them: review features lost with HYOK before you choose this tier. If you only need to own and revoke the key, BYOK keeps every feature.

​
How it works

You install one CloudFormation stack, provided by Corsa, in your AWS account. It gives you:
  • Your HYOK key. An RSA key in your AWS KMS wraps and unwraps the data key of each value. The private key never leaves KMS.
  • Your sign-in. Your users sign in before they can decrypt, either with passkeys in a user directory in your account (Cognito, the default) or with your own identity provider. Only members of your decryptor group can decrypt.
  • The Secure Viewer. The page your users’ browsers load inside Corsa to sign in and see decrypted fields. It’s served from your account.
  • A decryption check. The only path to your key. It checks your user’s sign-in and a Corsa authorization before it unwraps anything.
  • A signed link to Corsa. Your stack signs everything it reports to Corsa, such as its setup details and health, with its own signing key.
Settings → Encryption → Review resources lists everything the stack creates, so your AWS and security teams can review it before you deploy.

​
What happens when a user views a field

  1. The user opens a client in the Corsa app. The page embeds the Secure Viewer from your account.
  2. The user signs in with your sign-in (once per session).
  3. Corsa checks that the user may view this client, then issues a Corsa unwrap token: a short-lived (at most 5 minutes) signed token that names the user’s email, your stack, and the exact fields being displayed.
  4. The Secure Viewer sends the wrapped data key to the decryption check in your account, with both the user’s sign-in token and the Corsa token.
  5. Your stack checks that:
    • the user’s sign-in is valid, and the user is in your decryptor group;
    • the Corsa token is signed by Corsa, is unexpired, targets your stack and your workspace, and names the requested field;
    • the email in both tokens matches.
  6. Only then does your stack use your KMS key to unwrap the data key. The browser decrypts the value and displays it inside the Secure Viewer frame. The plaintext isn’t sent back to Corsa.
This is a dual-token design. Corsa can’t decrypt alone: decryption needs your user’s sign-in and your key, both in your account. A user of your sign-in can’t decrypt alone either: they also need a Corsa token issued after Corsa’s access check. Every unwrap, allowed or denied, is logged in your AWS account with the user, the token ID, the field, and the outcome. Plaintext and keys are never logged.

​
Envelope encryption with resource binding

Each value is encrypted with its own random AES-256-GCM data key. The data key is wrapped with your RSA key (RSA-OAEP-SHA256) together with a hash of the value’s resource:
The resource is also the additional authenticated data of the AES-GCM encryption. Your stack refuses to return a data key when the resource in the request doesn’t match the resource bound inside the wrapped key, or isn’t listed in the Corsa token. So a token issued for one field type can’t unwrap a different field type, and ciphertext copied to another field or workspace doesn’t decrypt. Today the binding covers the workspace, entity type, and field. It doesn’t bind to an individual record: per-record access is enforced by Corsa’s access check before it issues the token.

​
Trust model

HYOK limits what Corsa can read. It doesn’t make Corsa unable to learn anything about your data. Be precise about these points with your security and legal teams:
If your HYOK key is deleted, HYOK-encrypted data is permanently unrecoverable. Deleting the stack doesn’t delete the key, but anyone with permission can still schedule the key for deletion in KMS. Neither you nor Corsa can restore a deleted key.

​
Next steps

Set up HYOK

Install the stack from the app with a launch link and invite your decryptors.

Verify the release

Review the source, check the signed release, and confirm the code running in your account.

Features lost with HYOK

What works differently on HYOK-encrypted fields.

Encrypt with the SDK

Encrypt on your side with a pinned public key.