Skip to main content
Version: 0.6

Authentication

info

The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at GitHub #464.

  • Version: 0.1
  • Status: IN-PROGRESS
  • Last Updated: 2021-10-29

Overview​

This protocol allows two parties to mutually authenticate by disclosing and verifying the DID of each other. On successful completion of this protocol, it is expected that sender authenticated encryption may be used between the parties for continuous authentication.

Relationships​

Example Use-Cases​

  • A connected sensor wants to make sure only valid well-known parties connect to it, before allowing access.
  • A customer wants to make sure they are actually connecting to their bank, before presenting information.
  • An organisation wants to verify the DID of the employer before issuing access credentials.

Roles​

  • Requester: initiates the authentication.
  • Responder: responds to the authentication request.

Interaction​

AuthenticationDiagram

For guidance on diagrams see the corresponding section in the overview.

Messages​

1. authentication-request​

  • Type: iota/authentication/0.1/authentication-request
  • Role: requester

Sent to initiate the authentication process. This MUST be a signed DIDComm message to provide some level of trust to the responder. However, even when signed it is possible to replay an authentication-request, so this message alone is insufficient to prove the DID of the requester. In addition to a unique requesterChallenge, the created_time and expires_time DIDComm message headers SHOULD be used to mitigate such replay attacks. Note that even a successful replay would only reveal the DID of the responder, authentication of a malicious requester will still fail without access to the original requester's private keys due to the use of challenges.

Structure​

{
  "did": DID,                   // REQUIRED
  "requesterChallenge": string, // REQUIRED
  "upgradeEncryption": string,  // REQUIRED
}
FieldDescriptionRequired
didDID of the requester.1✔
requesterChallengeA random string unique per authentication-request by a requester to help mitigate replay attacks.✔
upgradeEncryptionA string indicating whether sender authenticated encryption should be used in the following messages. One of ["required", "optional", "unsupported"].2✔

1 The signing key used for the signed DIDComm envelope wrapping this message MUST be an authentication method in the DID document corresponding to did, as per the DIDComm specification.

2 The upgradeEncryption field allows negotiation of whether or not to use sender authenticated encryption for the authentication protocol and for all messages that follow it. It is RECOMMENDED to specify "required" as it offers various guarantees of continuous authentication and payload integrity for every message. The available options are:

Examples​

  1. Request payload requiring encryption:
{
  "did": "did:iota:9rK6DPF46MCEzgfLD8AHFsaTuMqvmRo6kbXfjqQJPJmC",
  "requesterChallenge": "81285532-b72a-4a99-a9bd-b470475bc24f",
  "upgradeEncryption": "required"
}

2. authentication-response​

  • Type: iota/authentication/0.1/authentication-response
  • Role: responder

Sent in response to an authentication-request, proving the DID of the responder. Optionally establishes sender authenticated encryption based on the value of upgradeEncryption in the preceding authentication-request. If upgradeEncryption was "required" and this message is not encrypted, or "unsupported" and this message is encrypted, the requester MUST issue a problem-report and abort the authentication.

This message MUST be a signed DIDComm message, even if sender authenticated encryption is used. This is to ensure an authentication key is used to sign the challenge, in accordance with the DID specification, and because there may be increased security controls or guarantees compared to the keyAgreement keys used for sender authenticated encryption.

Structure​

{
  "did": DID,                   // REQUIRED
  "requesterChallenge": string, // REQUIRED
  "responderChallenge": string, // REQUIRED
}
FieldDescriptionRequired
didDID of the responder.1✔
requesterChallengeMust match the requesterChallenge in the preceding authentication-request.✔
responderChallengeA random string unique per authentication-response by a responder to help mitigate replay attacks.✔

1 The signing key used for the signed DIDComm envelope wrapping this message MUST be an authentication method in the DID document corresponding to the did, as per the DIDComm specification.

Examples​

  1. Responder presenting their DID and offering a challenge to the requester:
{
  "did": "did:iota:8cU6DPF56MDEugfLF8AHFaaTuMQvmRo6kbxfjqQJpJmC",
  "requesterChallenge": "81285532-b72a-4a99-a9bd-b470475bc24f",
  "responderChallenge": "b1f0dc02-85a3-4438-8786-b625f11f1be4"
}

3. authentication-result​

  • Type: iota/authentication/0.1/authentication-result
  • Role: requester

This message finalises the mutual authentication, proving control over the DID of the requester to the responder. Similar to authentication-response, this message MUST be a signed DIDComm message.

This MUST or MUST NOT use sender authenticated encryption depending on the outcome of the upgradeEncryption negotiation in the preceding authentication-response message, otherwise resulting in a problem-report and failure of the authentication protocol. For example, if upgradeEncryption was optional and the authentication-response used sender authenticated encryption, then the authentication-result MUST be encrypted to be valid.

Structure​

{
  "responderChallenge": string // REQUIRED
}
FieldDescriptionRequired
responderChallengeMust match the challenge in the preceding authentication-response.1✔

1 The signing key used for the signed DIDComm envelope wrapping this message MUST be an authentication method in the DID document corresponding to the did of the requester in the authentication-request, as per the DIDComm specification.

Examples​

  1. Requester responding with the responder's challenge from the previous message:
{
  "responderChallenge": "0768e82d-f498-4f38-8686-918325f9560d"
}

Problem Reports​

The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports.

For guidance on problem-reports and a list of general codes see problem reports.

CodeMessageDescription
e.p.msg.iota.authentication.reject-authenticationauthentication-request, authentication-response, authentication-resultThe party rejects an authentication request/response/result for any reason.
e.p.msg.iota.authentication.reject-authentication.missing-keysauthentication-request, authentication-response, authentication-resultThe party rejects an authentication request/response due to the other party lacking a supported keyAgreement section in the DID document.
e.p.msg.iota.authentication.reject-authentication.untrusted-identityauthentication-request, authentication-responseThe party rejects an authentication request/response due to the claimed DID of the other party.
e.p.msg.iota.authentication.reject-authentication.encyption-requiredauthentication-request, authentication-response, authentication-resultThe party rejects an authentication request/response/result due to the lack of sender authenticated encryption.
e.p.msg.iota.authentication.reject-authentication.encyption-unsupportedauthentication-request, authentication-response, authentication-resultThe party rejects an authentication request/response/result because it does not support sender authenticated encryption.

Considerations​

This section is non-normative.

  • Trust: this authentication protocol only verifies that both parties have access to the necessary private keys (which could become compromised) associated with their DID documents. Verifying whether a DID document is bound to a physical identity may require additional interactions. Verifying whether a DID can be trusted can be achieved by, for instance:
    • requesting a verifiable presentation of credentials issued by a trusted third party, such as a government,
    • using the Well Known DID Configuration or embedding the DID in a DNS record to tie an identity to a website or domain,
    • using an allowlist of trusted DIDs,
    • exchanging DIDs out-of-band in a secure manner (note that some connection invitations could be altered by malicious parties depending on the medium).
  • Authorisation: the permissions and capabilities of either party may still need to be established after authentication, either by verifiable presentation as mentioned above or other methods such as JWT tokens
  • Privacy: the responder may be subject to probing whereby their DID may be revealed even with the use of sender authenticated encryption, as the skid message header is linked to their DID. This is possible if the responder chooses to accept the authentication-request of an unknown requester, or the requester successfully replays an authentication-request from a DID the requester trusts.

Unresolved Questions​