Skip to content

KMS Release v0.6.4

Choose a tag to compare

@github-actions github-actions released this 12 Nov 15:30
bb80091

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 DstackKms proxy, then each DstackApp proxy you control, with
    the storage-layout-checked scripts in dstack/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, and allowAnyDevice for every
    epoch.

  • Point new app deployments at the new implementation: deploy the current
    DstackApp implementation and call setAppImplementation
    (Manage.s.sol:SetAppImplementation).

  • Register the existing roots as root epoch 0 with
    registerRootEpoch(caPubkey, k256Pubkey, evidenceUrl)
    (Manage.s.sol:RegisterRootEpoch; with dstack-auth, a rootEpochs entry in
    its config). The keys must be the ones already in
    kmsInfo. If kmsInfo holds 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 with Root 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, addDevice and
    removeDevice are removed, and an upgraded app no longer reports
    IAppAuthBasicManagement (0x8fd37527). Use addComposeHashAtEpoch(0, hash)
    and the other *AtEpoch / *AtEpochs setters (IAppEpochManagement,
    0x8c0524c4).
  • DstackKms: addOsImageHash, removeOsImageHash, addKmsAggregatedMr,
    removeKmsAggregatedMr, addKmsDevice and removeKmsDevice are removed;
    use *AtEpochs(0, 0, value). setKmsInfo, setKmsQuote and
    setKmsEventlog are removed; roots are set with registerRootEpoch.
  • Approvals are per epoch. To revoke a value everywhere, use
    remove*AtEpochs(0, latestRootEpoch, value) on DstackKms and
    remove*AtEpochs(0, currentAppEpoch, value) on DstackApp.
  • DstackKms reverts with custom errors (for example InvalidAppId(),
    AppImplementationNotSet()) instead of revert strings; decode them instead
    of matching strings.
  • Proxies upgraded from v0.5.9 transfer ownership in two steps:
    transferOwnership nominates, the new owner calls acceptOwnership.
  • Optional: TEE platform allowlists (setAllowAnyTeeVariant(false) plus
    setAllowedTeeVariants). A restricted contract refuses the legacy
    isAppAllowed / isKmsAllowed calls.

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 (formerly auth-eth-bun, now published as
    ghcr.io/dstack-tee/dstack-kms-auth-eth). It requires teeVariant on
    /authorizeKms and /authorizeApp.
  • Custom webhook backends must serve GET /app/:appId, which reports the app's
    current app epoch.
  • auth-eth now reads policy at the finalized block, so on-chain changes,
    revocations included, take effect only after finality. Set
    ETH_BLOCK_TAG=latest only 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_hash keeps it out of
    the public compose), or set core.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 ABI
  • DstackApp.json - Application contract ABI