What changed
- The KMS root key was rotated. Every key derived from the old root changed.
- 0.5.x CVMs were updated to dstack 0.5.15.
- Data disks and sealed environments were re-encrypted automatically at boot.
- Application keys from
getKey()were not migrated. Your app has to fetch them.
getKey() now returns keys from the new root.
When you need this
Use the recovery tool if all of these are true:- Your app called
getKey()before the migration. - You still need the old key: a wallet, an encrypted record, a signing key, or a database key.
- You have not re-encrypted or moved that data to the new key.
When you don’t
You can skip this page if any of these apply:- Your app never called
getKey(). TLS certificates fromgetTlsKey()are issued fresh and are not affected. - Your app derives a key at runtime and does not persist anything tied to it.
- You already re-encrypted your data or moved your assets to the new key.
- You only need the data disk or sealed environment. Those are re-encrypted automatically at boot and do not need this tool.
How recovery works
The recovery tool asks the KMS for the epoch-0 app root and re-applies the same derivation your app used, so you get the exact old key back. It runs as a sidecar inside your CVM, and your app calls it over HTTP.Recover a 0.5.x key
Most apps use the 0.5.x API:getKey(path, purpose?, algorithm?).
1. Add the sidecar
Add this to yourdocker-compose.yml:
The sidecar needs the quote device, the boot event log and the host vsock service. The full passthrough table is in the tool README.
2. Call it from your app
name is the same path you passed to getKey().
3. Check the result
Comparekey with the old key you recorded before the migration. If you did not record it, check that the key still derives the address or decrypts the data you expect.
0.6.x apps
On 0.6.x the API isgetKey(domain, algorithm). The tool reads the guest version and uses the v1 derivation automatically, so the same call works:
/v0/key?path=…&purpose=… or /v1/key?domain=…&algorithm=….
Verify the image
Details
The tool also has a CLI, aninfo command and the full passthrough reference: dstack-key-recovery README.
