DID Controller and DID Resolver
3.3.1 DID Controller
As described in W3C, the DID Controller is an entity that has the capability to make changes to a DID document. A DID Controller is not a central registration authority, subjects can be identified by multiple DIDs issued by different DID Controllers. Initially the DID Controller is required to create an identity for itself. The process describe here is the same required for an external Subject DID Creation: the DID controller requires an issuance transaction Tx0’, locked to its own public key PKC0 and the “subject” public key PKCD. In this case, the subject is the controller itself. The transaction ID of Tx0’, TxID0’ becomes the DID of the Controller. To generate the subsequent transaction that will contain the Controllers DID Document, the controller will sign the transaction using two public keys: PKCD and PKC0, both of which belong to the Controller. Tx1’ input spends the output of Tx0’.
When requested by the subject, the DID Controller issues a new DID by creating and broadcasting two blockchain transactions: an Issuance and DID Document transaction. The issuance transaction, Tx0 is created by the DID Controller and provisioned (funded) by controller. UTXO of Tx0 should provide enough funds to cover the mining fee for the next transaction. The transaction ID of Tx0, TxID0 becomes the DID of the Subject. The DID Document is contained in the subsequent transaction Tx1, linked to the issuance transaction Tx0 by spending its output. Tx1 has a single output; that contains a payload with the DID Document and the minimal required funding to cover the mining fee of the next transaction.
3.3.2. DID Resolver
As described by the W3C, the DID resolver will resolve the DID to a DID Document. To read the DID Document, the DID resolver will search for the corresponding transactions in the ledger. The DID contains the transaction ID of the issuance transaction, Tx0. The transaction spending its output, Tx1, contains the first version of the DID Document. The most recent DID document is the document contained in the last transaction in the chain, Txn, of which UTXO is not spent.
The DID document versionId is the transaction ID of the transaction containing it.
The DID document versionTime is the timestamp of the blockchain block containing the transaction containing the DID it.
The verifier uses the DID method specific part of the DID identifier to search for the transaction in the ledger and find the linked transactions that contain the DID Document to perform status checks on their outputs. The verifier can request DID status using a DID resolver. Verifiers can build and run an independent DID resolver, create their own implementation (abiding by this specification), or use a service provided by a third party that runs an implementation of the UTXO DID method.
Figure 2: DID Creation
3.4 DID Operations
In this section, we will cover specifications to Create, Update, Read, and Revoke a DID. We included implementation examples as references. Please note that some specifications are optional and serve only to illustrate potential implementations.
3.4.1 Create
In previous sections, we have explained how the DID and DID document are related through two transactions, and how the Controller issues a DID to itself. This section explains in detail the process of a DID Controller creating a DID and a DID Document for Subject, including the digital signatures and the transaction specification required. It also explains the use of signatures in blockchain transactions to bind the Subject and the Controller public keys to the DID and the DID Document.
Recall that the DID Controller possesses two keys:
PKCD. Which serves as the Controller’s master key. It is only used to establish the Controllers DID.
PKC0. Which is used to create/sign DIDs for DID subjects. The Subject has a single key.
PKS0. This key is always in possession of the subject.
A) TxID0: Issuance Transaction. When a new DID is requested by the subject, the Controller will create an issuance transaction. This transaction locks the output to two public keys: the Controller's public key and the subject's public key. This initial transaction is necessary to initiate the DID Document process. The transaction ID of this transaction is used in the DID string: did:bsv:TxID0 as the Subject’s DID. Tx0 has a single input and a single output. The DID Document is published via a subsequent transaction Tx1 that spends the output of Tx0. See Figure 3. Note that when the Controller is required to issue a DID for itself, the Issuance transaction locks the output to both controller’s public keys (PKCD and PKC0). See Section 3.3. DID Controller .
B) TxID1: DID Document transaction This is a subsequent transaction that spends the output of the issuance transaction Tx0. This transaction has a single input and a single output. This output contains a data payload with the DID Document. Tx1 output is locked to a one-of-two multi-sig script signed either by Subject public key or the Controller public key. Once the input of Tx1 is signed by both keys, the transaction is broadcast to the network. When validated by miners it will read as resolved by the DID Resolver.
Figure 3: TX Anatomy
Figure 4: How the Subject and the Controller keys are linked to the DID.
C) Data payloads in the transaction outputs. After OP_RETURN we can find a data payload. This data does not affect the spending conditions, and it is described below:
BSV DIDIdentifier specifying this is a transaction associated with the BSV DID Method.Identity CodeDID Controller configuration identifier.DID Document JSON DID Documentor type transaction indicator <1/2/3>: Issuance, Update or key rotation and Revoke respectively.
D) Implementation Example Below we provide a detailed implementation of the BSV DID Method as a reference example for DID issuance. This specification covers the process of requesting a DID from the subject to the DID controller. It includes two specific examples of the implementation:
DID Controller Role: The DID controller can be run by any entity. It is important to note that the BSV DID method does not require a centralized controller. Any organization or entity can run a DID controller and create a DID for itself, as specified in See Section 3.3. DID Controller.
Database Persistence: We demonstrate database persistence in this implementation as an example, although this is optional based on implementation preferences
Figure 5: Create DID
F) Key Considerations
Proving Ownership: The DID Subject demonstrates ownership of their private key by signing transaction Tx1 and sending it to the DID Controller.
Transaction Tx0: The output of Tx0 is locked by the public keys of both the DID Controller and the DID Subject.
Transaction Tx1: The input of Tx1 requires signatures from both the Subject and the Controller. The output will contain the Controller-generated DID Document. This output is locked using a one-of-two multi-signature, allowing either the Controller or the Subject to spend the output.
Contents of the DID Document:
DID of the Subject.
Public Key associated with the DID Subject.
DID of the Controller (this identifies the DID Controller by resolving their DID).
Authentication method for the DID Controller (public key that can be verified on the signature input signing Tx1).
3.4.2 Resolve
The resolver uses the DID (TxID) to find the transaction in the ledger and identify the linked transactions containing the DID Document. Once the DID Document Tx has been identified the resolver does a status check on the output of the Tx via the DID Resolver. Who will find the TxID given and track UTXO status until the last UTXO update is found. The DID Resolver can be independently built and operated, implemented according to this specification, or provided by a third party that supports the UTXO-DID method. This method permits the use of different resolvers, ensuring the users are not required to rely on or trust our specific implementation.
3.4.3 Update
A) DID Document Status Update
In this section we explain how to change the content of the DID Document. The DID controller can change or update the status of the DID Document by creating a new transaction that spends the output of the latest transaction referring to the DID Document status.
Figure 6: Status Update
B) Rotation of Keys Both subject and controller can initiate rotation of keys. How the rotation is performed depends on who is initiating and for what reason. Scheduled or voluntary rotations are different from rotations forced because keys have been compromised.
Below we listed a series of use cases:
User Key Rotation with Valid Subject's Key
User Key Rotation upon Compromised Subject's Key
User Key Rotation because controller rotated its N key (user does not know if N was compromised or rotated regularly)
Controller rotation of valid or compromised M key
Controller rotation to update a valid key
Controller rotation upon key compromised
C) Subject Key Rotation There are many reasons a Subject key need to be rotated: either regular operating reasons like voluntary, scheduled rotation to comply with policies, security reason like a key being compromised or to keep a valid controller attestation because the controller key has been rotated.
Subject Key’s compromised: In case the subject’s key was compromised, it cannot be used to attest the rights, and the DID controller will have to establish some authentication process of the subject that does not refer to the compromised keys. Once the DID Subject is authenticated, the DID controller will discover that “PKS0” has been compromised and will sign a new issuance transaction using its PKC0 key. The output spent from the transaction referring to the latest DID Document transaction: TXn becomes the input of TXf (funding Tx). This transaction locked the new output to the controller’s unchanged public key and the subject’s new public key.
Subject Key’s not compromised: In all other cases the authentication of the subject via an external channel is not necessary as the old key is considered secure and DID Subject will have to use both old and new keys to attesting that it is authorized to rotate the key as well as prove that it owns the new key.
D) Controller Key Rotation There are many reasons a Controller key needs to be rotated: either regular operating reasons like voluntary, scheduled rotation to comply with policies, security reason like any of the Controller keys: PKCD or PKC0 has been compromised. The Controller can lose any of the following keys.
PKCD: Master Key which changes their own DID Authentication as well as all the issued DIDs.PKC0: Public Key associated with their DID document, i.e. the Root key for all their DID Issuance.
Only in the scenario in which the Controller losses his master key PKCD’, would require a different process for Key rotation. When changing PKC0 the Controller will just be able to update the keys themselves.
E) Compromised PKCD:
The process begins with the DID Controller performing a Master Key update, during which the Controller updated its key to the new Master Public Key PKCD’. Subsequently, the controller generates a new DID for itself TxID0’ , linking the previous public key to the new one, and then creates and publishes a new DID Document TxID1’ spending TxID0’ unique output. As a result of the controller keys being updated, the DID Document of all subjects that were co-signed by the Controller Key’s needs to be updated. In order to do so, the Controller will be required the DID Document controller keys of all subjects to be rotated. The DID Subject accepts the key rotation request. The DID Controller then generates a Key Rotation transaction, that the Subject must sign to spend the output of the TxIDn that contains the last status of the DID Document. See Figure 8.
A new DID issuance and DID Document transaction is funded using a new Master Key. Afterwards, the Rotation Transaction is sent to the DID Subject for signing. Once signed, it is returned to the controller. The Rotation Transaction is then stored and broadcast on the blockchain. Following this, a new DID Document for the user is generated, incorporating a new derivation factor and updated keys. A Publish Transaction is created for the DID Subject, which is also signed and returned after signing. This Publish Transaction is then stored and broadcast on the blockchain. Finally, the updated DID Document is confirmed to have been successfully created and recorded on the blockchain.
* Figure 8: Notification of key rotation of end-user is a user experience decision, configurable and not mandatory. Invalid signatures will be rejected by blockchain
F) Compromised PKC0.
When a Controller needs to execute the rotation of their Controller Key associated with their DID document. (A specific example could be to change the Root key for all their DID Issuance). For this scenario the controller will have the same flow presented inside the “loop” of the above diagram, except, the Controller can perform the steps to create the Rotation Tx and publish it on chain by itself. They would still require the Subject to sign the updated DID Document. So will create a new linked Publish Tx to the Rotation Tx. See Figure 9.
Figure 9: Tx Anatomy
3.4.4 Revoke
In this section we explain how to revoke a DID. This method uses the spent status of the latest UTXO in the DID Document to indicate the active status of a DID. When the last transaction in the chain is spent, the DID is revoked. See section 3.4.2, DID and DID Document Status. A DID can be revoked by either the DID Subject or the DID Controller. Here are three ways the DID Subject can revoke its DID:
Subject is still in control of the private key and decides to revoke its DID, through the DID controller by calling the controller's DID revocation service. Bellow we provide an implementation example. See Figure 10
Subject is not in control of the private key (A specific example might be when the subject lost his/her device) and decides to revoke their DID.
Subject asks DID Controller to revoke on its behalf. Note that to secure subject request we advise Controllers to apply a mandatory, strong authentication of DID Subject before executing any changes. Bellow we provide an implementation example. This will be signified by the transaction type indicator, as described in section 3.4.1. See figure 11
In all cases the revocation is initiated by the DID Subject.
Figure 10: DID Revocation initiated by DID Subject
Figure 11: DID Revocation initiated by DID Controller
Last updated