Skip to main content

Module account_recovery_v2_upgrade

Module account_recovery_v2_upgrade 

Source
Expand description

Updating members’ account recovery keys after their V1 to V2 upgrade.

A V1 to V2 upgrade rotation does not re-encapsulate the member’s account recovery key, because that requires trusting a server-supplied organization public key and the upgrade shows the member no prompt. The rotation writes a V2 upgrade token to the membership instead, and the organization keeps an account recovery key that wraps the member’s V1 user key.

The token carries both user keys, each one wrapped with the other, so opening the V1 user key yields the V2 one:

OrganizationPrivateKey -> AccountRecovery       -> V1 user key
V1 user key            -> V2UpgradeToken        -> V2 user key
V2 user key            +  OrganizationPublicKey -> new AccountRecovery

An owner or admin runs OrganizationUsersManagementClient::upgrade_pending_account_recovery_keys for each organization whose key it holds. The server returns the pending memberships one page at a time. The client sends the upgrades of each page to the server before it reads the next page. For each membership, the client:

  1. decapsulates the stored account recovery key into the member’s V1 user key,
  2. unwraps the V2 user key from the upgrade token, which cross-validates both halves,
  3. compares the key id of that user key with the one the server reported,
  4. encapsulates the V2 user key to the organization.

The server reports the user key id and can name any key. It holds none of the member’s user keys, so step 3 takes the key id of the user key the client recovered and compares it against the reported one. A mismatch means the membership names a user key the upgrade token does not carry.

A membership is sent to the server without a key when its account recovery key or upgrade token is missing, malformed, does not decrypt, or carries a user key other than the reported one. That unenrolls the member from account recovery and drops a key that no longer opens the member’s vault. A retry would read the same keys and fail again, so the membership would otherwise stay pending on every run. A membership that fails for any other reason is not sent and stays pending.

Structs§

PendingPage 🔒
One page of pending memberships.

Enums§

AccountRecoveryV2UpgradeError
Errors returned when upgrading members’ account recovery keys.
PendingMembershipError 🔒
Errors that stop one pending membership from being upgraded. They do not fail the organization’s upgrade: the membership is either unenrolled from account recovery or left pending.

Functions§

fetch_pending 🔒
Reads one page of pending memberships.
has_account_recovery_permissions 🔒
Whether the account’s role lets it read the organization’s private key and set members’ account recovery keys. The server accepts only owners and admins.
make_new_account_recovery_key 🔒
Reads the V2 user key out of the membership’s upgrade token and encapsulates it to the organization as the member’s new account recovery key.