In (MSC1768)[matrix-org#1768] it was assumed that a user can associate public keys with matrix accounts using the methods described in the specification for IS.
This proposal explains how to associate Distributed Identifiers (DIDs) and their human-friendly names (DID names) with matrix accounts. DIDs and DID names come with public/private key pairs that can then be used during login following the flow described in MSC1768.
Similar to email and phone association endpoints are defined that allow to request and submit a token. The token is provided via another endpoint in encrypted form using the public key of the DID or DID name. Only the owner of the private key can decrypt and, hence, submit the token correctly.
A DID is a user-owned identifier that can be used by third-parties to verify ownership of a public cryptographic key without relying on another third-party (like email provider). DIDs are specified by the Credential Community Group of W3C. There are different methods to create DIDs. Some DID method allow to define human-friendly names (DID names).
Distributed apps and users share DIDs and DID names to interact with each other, therefore, these are good candidates to associate them as 3PIDs as explained in (MSC1762)[matrix-org#1762].
In order to associate a DID or DID name the following endpoints are defined
POST /_matrix/identity/api/v1/validate/did/requestToken
POST /_matrix/identity/api/v1/validate/did/encryptedToken
GET /_matrix/identity/api/v1/validate/did/submitToken
POST /_matrix/identity/api/v1/validate/did/submitToken
Create a session for validating a DID or DID name.
The identity server will create a token and make it available in encrypted from
via the proof/encryptedToken endpoint. The identity server resolves the DID
or DID name and uses the associated public key and cryptographic method to
encrypt the token. If that token is presented to the identity server in the
future, it indicates that user was able to decrypt the token for this DID or DID
name, and so we validate ownership of the DID or DID name.
The parameters of the request call should be
client_secret, medium, address, next_link
medium must start with m.did and be a valid medium. address is the
DID or DID name (that is part of the namespace of the given medium). The other parameters and response should
have the same meaning as for phone and email validation.
Status code can be 200 if a session and an encrypted token could be created. Status code can be 4xx if the address could not be resolved to a public key or the associated cryptographic method is not supported by the identity server.
Provides an encrypted token for the given session.
The identity server will response with the encrypted token that was stored in the session provided by the caller.
The parameter is
client_secret, sid
where client_secret is the client secret using the request token call and
the sid the session id of created previously by the identity server.
The response consists the encrypted token, e.g.
{ "encrypted_token": "A_TOKEN_FROM_THE_SERVER"}
Status code can be 200 if the parameters correspond to a valid session or 4xx if the session and client secret is invalid.
Validate ownership of a DID or DID name.
If the three parameters are consistent with a set generated by a requestToken
call, ownership of the DID or DID name is considered to have been validated.
This does not publish any information publicly, or associate a DID or DID name
with any Matrix user ID. Specifically, calls to /lookup will not show a binding.
The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification.
The response and response code should have the same meaning as for phone and email validation.
A parameter for send_attempts as for phone or email is not needed as the user is pulling the encrypted token (in contrast to sending the token via other communication means).
Instead of providing an encrypted token, a challenge could be published that needs to be signed. Similar to the login method described in MSC1768. However, the proposed endpoints follow the same pattern as for email and phone validation.
This proposal requires that the identity server implements cryptographic methods which requires a certain level of knowledge. This could reduce adoption.
This proposal requires to resolve a DID or DID name to a public key. This requires a so-called universal resolver). This adds a dependency to a third-party service or requires maintenance of an implementation of such resolver that requires a certain knowledge of decentralized identifier management. This could reduce adoption.
Identity servers should only accept DID or DID names that are not known to be vunerable in the cryptographic sense.
Identity servers should choose universal resolver services or universal resolver implmentations that are trustworthy. Identity servers should choose public nodes to resolve DID names that are trustworthy.
This MSC provides details about how to associate DID and DID names. It follows the patterns of email and phone validation as close as possible.
Together with MSC1762, MSC1768 and MSC1780 this provides an important step towards adoption of decentralized identifiers in the matrix ecosystem.