pull/1781/merge
Friedger 1 month ago committed by GitHub
commit b71e09b171
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

@ -0,0 +1,132 @@
# Proposal to associate DIDs and DID names
In (MSC1768)[https://github.com/matrix-org/matrix-doc/pull/1768] it was assumed
that a user can associate public keys with matrix accounts using the methods
described in the [specification for
IS](https://matrix.org/docs/spec/identity_service/r0.1.0.html#establishing-associations).
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.
## Proposal
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)[https://github.com/matrix-org/matrix-doc/pull/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
````
### Request Token
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.
### Encrypted Token
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.
### Submit Token
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.
## Tradeoffs
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.
## Potential issues
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](https://github.com/decentralized-identity/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.
## Security considerations
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.
## Conclusion
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.
Loading…
Cancel
Save