Merge ade7301a67
into ecf996389f
commit
b71e09b171
@ -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…
Reference in New Issue