Browse the docs
Guides
Rotate environment keys
Give an environment a new encryption key after someone loses access or a device is compromised. What rotation protects, what it can't, and how to finish it.
Last updated
On this page
Rotating an environment key creates a new encryption key for the environment and saves its contents as a new version under it. Only those who have access right now get the new key. People and machines who lost access can't read any version saved after that.
Rotation changes Crunu's encryption keys. It doesn't change the values inside: passwords and tokens are reissued at their providers.
When to rotate
- Someone lost access: a member was removed from the environment or the organization, a machine was revoked, a service token was revoked. Crunu marks such environments rotation needed by itself.
- A device was lost or compromised on which the environment was opened.
- As a routine, for example once a quarter for production.
Rotate one environment
You need to be an owner or admin. For a personal environment, its owner.
Open the project's Project settings, find the environment and choose Rotate keys…. An environment marked rotation needed also offers Rotate… on its card. From the environment's Access page, Rotate key… does the same.
The window shows:
- who gets the new key: members, machines and tokens with the environment key, and the organization recovery key;
- who gets a new copy of their selected files;
- in a network-restricted environment, any recipient who has never received the key or the files before. Delivering to them needs your explicit confirmation.
Owners and admins always get the key, through the organization key. Choose Rotate. Your browser creates the new key, re-encrypts the current contents as a new version, seals the key to each recipient and rebuilds the file copies, all in one request.
In a network-restricted environment, a rotation writes contents, so do it from inside the allowed networks or with break-glass access.
Rotations that wait for a key holder
The person who triggers a removal doesn't always hold the key of every environment involved. In that case the rotation is queued as waiting for a key holder, and it shows up in Pending actions under Environment key rotation needed.
To finish it, ask someone who holds the key of that environment to open the web app. The rotation runs in their browser. An owner can also do it through the organization recovery key, if the environment is under recovery.
Do everything I can in Pending actions runs the queued tasks your keys allow, such as key deliveries and certificate renewals. Network-restricted environments are never handled in the background: each needs your explicit action.
What rotation protects, and what it doesn't
| After rotation | |
|---|---|
| New versions | readable only by current recipients |
| Old versions | still readable by anyone who had the old key, so history keeps working |
| Values already seen | still known to whoever saw them |
| Running programs on a revoked machine | keep their variables until they restart |
That's why rotation goes together with reissuing values at their providers whenever someone may have kept them. The member removal wizard gives you a reissue checklist with the values the person received that are still in use.
Rotating the organization keys
When an owner or admin leaves or is demoted, or replaces their keys after a stolen device, they knew the organization's signing and recovery keys. The organization then needs a new key generation: new organization keys, reissued certificates for every member and machine, a new revocation list and new keys for every shared environment.
The member removal wizard does this when it removes an admin or owner. Otherwise a banner asks owners and admins to rotate the organization keys, and Pending actions lists it. Agents and devices accept the new generation only through a chain signed by the previous one.
How to check
- The environment no longer shows rotation needed.
- Pending actions has nothing left for it.
- The audit log shows Environment key rotated.
- Machines pick up the new key at their next check, within a minute by default.