This page describes the complete lifecycle of a 3ID DID, including how the DID document is created, how keys are managed, and how 3ID Connect uses these building blocks. Most of the logic described here is implemented in the 3id-did-provider package.
3ID DID provider lifecycle¶
Every 3ID has a seed which is the secret used to update the 3ID, sign messages, and decrypt messages as the 3ID. The 3ID DID provider manages this seed using authSecrets. Each
authSecret can be used to authenticate to the 3ID and thus get access to the seed.
Creating a 3ID¶
To create a 3ID the 3id-did-provider accepts an
authSecret and an
authId. It roughly follows the following algorithm.
- We have an
authSecret Athat is used to create
- A deterministic TileDocument, referred to as AuthLink, is created. If this is a new
authSecretthe loaded AuthLink will be empty
- A seed for the 3ID is randomly generated; two asymmetric keys (
encryption), and a
did:key:management-1are derived from the seed. A stream for the 3ID DID document is created with
did:key:management-1as the controller, the
encryptionpublic keys are stored in the streams content
- The seed is encrypted to
- The encrypted seed is put into the 3ID Keychain, which is an IDX record associated with the 3ID from step 3
- The AuthLink document is updated to contain the 3ID from step 3.
Loading an existing 3ID¶
authSecret has already been associated with a 3ID then this 3ID will be loaded instead of a new one created. Once authenticated the user can make updates to the 3ID document itself, as well author signatures and decrypt messages as the 3ID.
authSecret Ais used to create
- A deterministic TileDocument, referred to as AuthLink, is created. If this is an existing
authSerectthe loaded AuthLink contain a 3ID
- Using the 3ID from the previous step we can deterministically load the 3ID keychain
- Decrypt the seed in the 3ID Keychain that was encrypted to
Adding a new
We can add a new
authSecret with two simple steps.
authSecret Bis used to create
seedis encrypted to
did:key:Band stored in the 3ID Keychain
- An AuthLink stream is created for
did:key:Band updated to link to the 3ID
Assume that we have
authSecret A and
authSecret B associated to our 3ID, and we want to revoke
authSecret A. Lets refer to the current seed as
seed 1. Note that you should always end up with at least one
authSecret in the end. It doesn't make sense to revoke all authSecrets as there no longer would be a way to authenticate to this 3ID.
- Randomly generate a new seed,
- Two asymmetric keys (
encryption), and a
did:key:management-2are derived from
seed 2. The 3ID stream for the 3ID DID document is updated with
did:key:management-2as the controller, the
encryptionpublic keys in the content
seed 1is encrypted to
seed 2and stored in the 3ID Keychain, so that we can use it to decrypt any message encrypted to the previous version of the 3ID document
seed 2is encrypted to
authSecret Bbut not to
- The encrypted
seed 2is stored in the 3ID keychain
After these steps are taken,
authSecret A can no longer be used to authenticate to the 3ID.
Usage in 3ID Connect¶
A natural question at this point is: Where does these authSecrets come from? In 3ID Connect normal blockchain wallets are used to create these secrets in the following way.
- A signature of some static message is requested from the users wallet, e.g. MetaMask
- If the user accepts a signature is returned
- The entropy (randomness) of the signature is now used as an
authSecret(we take the hash of the signature to get the
authSecret), in addition 3ID Connect will use the wallet AccountID as the
Note that this relies on the wallet making deterministic signatures, such that we can get the same
authSecret every time.
In addition to the authentication flow, 3ID Connect also creates a Caip10Link from the wallet AccountID to the 3ID. This allows application developers to query the users 3ID using an Ethereum address for example. The Caip10Link is also stored in the users CryptoAccounts IDX definition.