Repository navigation
KMS Release v0.6.4
Upgrade notes — read before upgrading
KMS 0.6.4 introduces root and app key epochs. The DstackKms and DstackApp
contracts, the auth backend, the KMS nodes and the guests must be upgraded in
this order, and existing roots must be registered as root epoch 0 before the
new KMS serves keys.
1. Upgrade the contracts first
-
Upgrade the
DstackKmsproxy, then eachDstackAppproxy you control, with
the storage-layout-checked scripts indstack/kms/auth-eth:KMS_CONTRACT_ADDR=0x... forge script script/Upgrade.s.sol:UpgradeKms --broadcast --rpc-url $RPC_URL --ffi APP_CONTRACT_ADDR=0x... forge script script/Upgrade.s.sol:UpgradeApp --broadcast --rpc-url $RPC_URL --ffi
App contracts that are not upgraded (deployed with v0.5.x or v0.6.0) keep
working, but are authorized for app epoch 0 only. An upgraded app keeps its
compose hashes and devices as app epoch 0, andallowAnyDevicefor every
epoch. -
Point new app deployments at the new implementation: deploy the current
DstackAppimplementation and callsetAppImplementation
(Manage.s.sol:SetAppImplementation). -
Register the existing roots as root epoch 0 with
registerRootEpoch(caPubkey, k256Pubkey, evidenceUrl)
(Manage.s.sol:RegisterRootEpoch; with dstack-auth, arootEpochsentry in
its config). The keys must be the ones already in
kmsInfo. IfkmsInfoholds a legacy quote and event log, convert them with
dstack-kms legacy-attestation --quote <hex> --eventlog <hex>and publish
the result as the evidence first. Until epoch 0 is registered the KMS denies
key release withRoot epoch not registered. -
Keep root and app epochs at 0 until every KMS node and every guest runs
0.6.4. Activating a later root epoch stops KMS binaries that do not report
a root epoch.
2. Breaking contract API changes
Update scripts, dashboards and other tooling that call the contracts:
DstackApp:addComposeHash,removeComposeHash,addDeviceand
removeDeviceare removed, and an upgraded app no longer reports
IAppAuthBasicManagement(0x8fd37527). UseaddComposeHashAtEpoch(0, hash)
and the other*AtEpoch/*AtEpochssetters (IAppEpochManagement,
0x8c0524c4).DstackKms:addOsImageHash,removeOsImageHash,addKmsAggregatedMr,
removeKmsAggregatedMr,addKmsDeviceandremoveKmsDeviceare removed;
use*AtEpochs(0, 0, value).setKmsInfo,setKmsQuoteand
setKmsEventlogare removed; roots are set withregisterRootEpoch.- Approvals are per epoch. To revoke a value everywhere, use
remove*AtEpochs(0, latestRootEpoch, value)onDstackKmsand
remove*AtEpochs(0, currentAppEpoch, value)onDstackApp. DstackKmsreverts with custom errors (for exampleInvalidAppId(),
AppImplementationNotSet()) instead of revert strings; decode them instead
of matching strings.- Proxies upgraded from v0.5.9 transfer ownership in two steps:
transferOwnershipnominates, the new owner callsacceptOwnership. - Optional: TEE platform allowlists (
setAllowAnyTeeVariant(false)plus
setAllowedTeeVariants). A restricted contract refuses the legacy
isAppAllowed/isKmsAllowedcalls.
3. Upgrade the auth backend
- KMS nodes still on 0.6.3 or earlier keep using
/bootAuth/*, which the new
backend still serves while epoch 0 is current and no TEE platform
restriction is set. - Use the 0.6.4
auth-eth(formerlyauth-eth-bun, now published as
ghcr.io/dstack-tee/dstack-kms-auth-eth). It requiresteeVarianton
/authorizeKmsand/authorizeApp. - Custom webhook backends must serve
GET /app/:appId, which reports the app's
current app epoch. auth-ethnow reads policy at thefinalizedblock, so on-chain changes,
revocations included, take effect only after finality. Set
ETH_BLOCK_TAG=latestonly if you accept that a reorg can roll back a change
the KMS already acted on (an OP-stack chain read through Helios requires it).
4. Then the KMS nodes, then guests
- The KMS refuses to start without a key handover path: enable
[core.admin]
with[core.admin.tls]and an admin token (auth_token_hashkeeps it out of
the public compose), or setcore.onboard.public_key_handover = true. - Upgrade every KMS before deploying 0.6.4 guests: 0.6.4 guests use
self-issued RA-TLS client certificates that older KMS versions do not accept.
See docs/deployment.md (Rotating KMS Root Keys), dstack/kms/auth-eth/script/README.md
and the 0.6.4 changelog.
Docker Image Information
Image: ghcr.io/dstack-tee/dstack-kms:0.6.4
Digest (SHA256): sha256:3c8746c4a638e0a96e69f19d8830f9c560466ee26e733a5c6c81e6ca2e213784
Verification: Verify on Sigstore
Contract ABIs
This release includes the compiled contract ABIs:
DstackKms.json- Main KMS contract ABIDstackApp.json- Application contract ABI