Skip to content

Latest commit

 

History

History
121 lines (78 loc) · 11.7 KB

jwm.md

File metadata and controls

121 lines (78 loc) · 11.7 KB
Raw

Note: This file has served as a reference, but is not part of the compiled spec. Any changes to this document should also be made to a file that is included in the compiled spec.

DIDComm Messaging

DIDComm messaging is a secure messaging protocol built atop of decentralized identifiers. DIDComm messages are JSON based leveraging the secure messaging format of JWM, which is an IETF draft to expand the JOSE (Javascript object signing and encryption) family of specifications for the purposes of secure messaging.

Terminology

Message Payload In reference to JWMs, message payload refers to the JWM Attribute Set.

JWM Profile

The following section defines a JWM profile for DIDComm messages. This profile defines the usage of the JWM attributes defined by the specification as well as defines some attributes that are unique to DIDComm messaging.

  • id - REQUIRED. Message ID. The id attribute value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to another DIDComm message.
  • type - REQUIRED. Message Type. The type attribute value MUST be a valid MTURI, that when resolved gives human readable information about the message. The attributes value also informs the content of the message, for example the presence of other attributes and how they should be processed.
  • to - OPTIONAL. Recipient(s) identifier. The to attribute MUST be an array of strings where each element is a valid DID URL without the Fragment component which identifies the recipients of the message.
  • from - OPTIONAL. Sender identifier. The from attribute MUST be a string that is a valid DID URL without the Fragment component which identifies the sender of the message. The from field MUST be included if authentication of the DIDComm message is needed. See the message authentication section for additional details.
  • reply_url - OPTIONAL. Reply url. The reply_url attribute value MUST be a string that is a valid URL which identifies where the sender wishes the recipient(s) to send a reply.
  • reply_to - OPTIONAL. Reply to. The reply_to attribute value MUST be an array of strings where each element is a valid DID URL without the Fragment component which identifies the recipients of the reply to the message.
  • created_time - OPTIONAL. Message Created Time. The created_time attribute is used for the sender to express when they created the message.
  • expires_time - OPTIONAL. Message Expired Time. The expires_time attribute is used for the sender to express when they consider the message to be expired.
  • thid - OPTIONAL. Identifier for the current protocol's thread. If the thid is defined, the thid MUST be the value given. But if the thid is not defined, the thid MUST be implicitly defined as the id of the given message and that message MUST be regarded the first message of a new thread.
  • pthid - OPTIONAL. Identifier for the parent thread from which this one branched off from.

Example JWM Message Payload

{
    "id":"ef5a7369-f0b9-4143-a49d-2b9c7ee51117",
    "type":"https://didcomm.org/didexchange/1.0/invitation",
    "from":"did:example:12345912948",
    "expires_time":1516239022,
    "created_time":1516269022,
    "reply_url": "https://agents-r-us.com/12345",
    "thid": "51c4f434-2c7b-499d-8f22-9edbd889b257",
    "pthid": "b7c217c1-7074-4b38-b0c8-287d3e594d0d"
}

Usage of JOSE headers

Key Identifier (kid)

Usage of this field is REQUIRED, the value used in this field should be a valid DID URL which identifies the key(s) required to either decrypt and or verify a message.

Example did:example:123#key1

JWA Usage

The JOSE family defines JSON Web Algorithms (JWAs) which standardize certain cryptographic operations that are related to preparing JOSE structures. For the purposes of interoperability, DIDComm messaging does not support all JWAs, rather it takes a subset of the supported algorithms that are applicable for the following cases around secure messaging.

Sender Authenticated Encryption

When a sender would like to encrypt a message for a recipient or multiple recipients and also be authenticated such that the recipients can determine they were the party that encrypted the message, the JWA of ECDH-1PU defined by draft SHOULD be used within the structure of a JWE.

For the keys involved in key agreement, the following elliptic curves MUST be supported.

Curve Description
X25519 The underlying curve is actually Curve25519, however when used in the context of diffie helman the identifier of X25519 is used
P-256 NIST defined P-256 elliptic curve

For content encryption of the message, the following algorithms MUST be supported.

Algorithm(JWA) Description
C20P ChaCha20Poly1305
AES-GCM Advanced Encryption Standard with galois/counter mode

Anonymous Encryption

When a sender would like to encrypt a message for a recipient or multiple recipients but not be authenticated by the recipients as the party who encrypted the message, the JWA of ECDH-ES defined by RFC 7518 SHOULD be used within the structure of a JWE.

For the keys involved in key agreement, the following elliptic curves MUST be supported.

Curve Description
X25519 The underlying curve is actually Curve25519, however when used in the context of diffie helman the identifier of X25519 is used
P-256 NIST defined P-256 elliptic curve

For content encryption of the message, the following algorithms MUST be supported.

Algorithm(JWA) Description
C20P ChaCha20Poly1305
AES-GCM Advanced Encryption Standard with galois/counter mode

Signing

When a sender would like for a message to feature a non-repudiable digital signature the JWA's defined below can be used within the structure of a JWS.

For digital signatures the following algorithms MUST be supported.

Algorithm(JWA) Description
EdDSA (with crv=Ed25519) Elliptic curve digital signature with Edwards curves and SHA-512
ES256 Elliptic curve digital signature with NIST p-256 curve and SHA-256

Signed and Encrypted

When a sender would like for their message to feature both a non-repudiable digital signature and be encrypted to a recipient or multiple recipients. They can combine the encryption and signing operations defined earlier in this section by creating a nested JWM.

Message Authentication

Message authentication is a necessary property used to establish the identity of the parties sending and receiving messages. This is done through a variety of cryptographic methods, most commonly being the use of authenticated encryption with the secret key derived from the senders static public key and the recipients static public key. These checks are handled via the selection of different JWE and JWS algorithms and by making sure that the keys used are contained with the DID documents of the associated identities.

So, in order to validate the authenticity of the message, the recipient MUST validate that the keys used by the sender in the JWE and/or JWS are valid and within the DID document of the expected decentralized identifier.

To verify the authenticity of the message, the recipient MUST resolve a valid DID document associated with the DID in the from field of the JWM message.

In the case where Sender Authenticated Encryption is used, the recipient MUST then validate that the keys and key ids (kid) used in the JWE matches the keys and identifiers associated (via the DID document) with the DID. Additionally, when checking the keys in the DID document, the recipient MUST also verify that the key is authorized by checking that the key identifier is located within the verification relationship property named keyAgreement in the DID document.

In the case of a signed message, the recipient MUST then validate that the keys and key ids (kid) used in the JWS matches the keys and identifiers associated (via the DID document) with the DID. Additionally, when checking the keys in the DID document, the recipient MUST also verify that the key is authorized by checking that the key identifier is located within the verification relationship property named authentication in the DID document.

In the case of a nested message the associated keys and key ids used in the JWS and JWE MUST be valid for the message to be considered authenticated. The recipient MUST validate that the key used for signing is authorized in the authentication section of the DID document and the key used for authenticated encryption (JWE ECDH-1PU) is authorized in the keyAgreement section of the DID document.

While checking the authorization of the keys used, if the keys are not contained within the DID document then the message SHOULD NOT be considered authenticated, even if the cryptographic operations succeeds.

Note In general this check should always return an error when the keys cannot be authorized in the appropriate sections of the DID document. This may present a problem if the recipient is trying to check the message when the sender has already updated their DID document to remove and invalidate the keys used in the message. In this case, two approaches make sense. The recipient can return an error saying they weren't able to validate the message with the id of the message included in the error report and await the sender to resend the message. Alternatively, the recipient can resolve the DID document of the message at the time the message was sent. The first approach is preferred because the recipient cannot be certain why the sender invalidated the keys.