Aries RFC 0234: Signature Decorator¶
- Authors: Kyle Den Hartog
- Status: RETIRED
- Since: 2020-10-14
- Status Note: This decorator is retired, replaced with the use of the signed form of the attachment decorator (RFC 0017)
- Supersedes: this HIPE (never merged)
- Start Date: 2019-01-07
- Tags: feature, decorator
RFC ARCHIVED¶
DO NOT USE THIS RFC.
Use the signed form of the attachment decorator (RFC 0017) instead of this decorator.
Summary¶
The ~sig
field-level decorator enables non-repudiation by allowing an Agent to add a digital signature over a portion of a DIDComm message.
Motivation¶
While today we support a standard way of authenticating messages in a repudiable way, we also see the need for non-repudiable digital signatures for use cases where high authenticity is necessary such as signing a bank loan. There's additional beneficial aspects around having the ability to prove provenance of a piece of data with a digital signature. These are all use cases which would benefit from a standardized format for non-repudiable digital signatures.
This RFC outlines a field-level decorator that can be used to provide non-repudiable digital signatures in DIDComm messages. It also highlights a standard way to encode data such that it can be deterministically verified later.
Tutorial¶
This RFC introduces a new field-level decorator named ~sig
and maintains a registry of standard Signature Schemes applicable with it.
The ~sig
field decorator may be used with any field of data. Its value MUST match the json object format of the chosen signature scheme.
We'll use the following message as an example:
{
"@type": "https://didcomm.org/example/1.0/test_message",
"@id": "df3b699d-3aa9-4fd0-bb67-49594da545bd",
"msg": {
"text": "Hello World!",
"speaker": "Bob"
}
}
Digitally signing the msg
object with the ed25519sha256_single
scheme results in a transformation of the original message to this:
{
"@type": "https://didcomm.org/example/1.0/test_message",
"@id": "df3b699d-3aa9-4fd0-bb67-49594da545bd",
"msg~sig": {
"@type": "https://didcomm.org/signature/1.0/ed25519Sha512_single",
"sig_data": "base64URL(64bit_integer_from_unix_epoch|msg_object)",
"signature": "base64URL(digital signature function output)",
"signer": "base64URL(inlined_signing_verkey)"
}
}
The original msg
object has been replaced with its ~sig
-decorated counterpart in order to prevent message bloat.
When an Agent receives a DIDComm message with a field decorated with ~sig
, it runs the appropriate signature scheme algorithm and restores the DIDComm message's structure back to its original form.
Reference¶
Applying the digital signature¶
In general, the steps to construct a ~sig
are:
- Choose a signature scheme. This determines the
~sig
decorator's message type URI (the@type
seen above) and the signature algorithm. - Serialize the JSON object to be authenticated to a sequence of bytes (
msg
in the example above). This will be the plaintext input to the signature scheme. - Construct the contents of the new
~sig
object according to the chosen signature scheme with the plaintext as input. - Replace the original object (
msg
in the example above) with the new~sig
object. The new object's label MUST be equal to the label of the original object appended with "~sig".
Verifying the digital signature¶
The outcome of a successful signature verification is the replacement of the ~sig
-decorated object with its original representation:
- Select the signature scheme according to the message type URI (
ed25519sha256_single
in the example above) - Run the signature scheme's verification algorithm with the
~sig
-decorated object as input. - The software MUST cease further processing of the DIDComm message if the verification algorithm fails.
- Replace the
~sig
-decorated object with the output of the scheme's verification algorithm.
The end result MUST be semantically identical to the original DIDComm message before application of the signature scheme (eg. the original example message above).
Additional considerations¶
The data to authenticate is base64URL-encoded and then embedded as-is so as to prevent false negative signature verifications that could potentially occur when sending JSON data which has no easy way to canonicalize the structure. Rather, by including the exact data in Base64URL encoding, the receiver can be certain that the data signed is the same as what was received.
Signature Schemes¶
This decorator should support a specific set of signatures while being extensible. The list of current supported schemes are outlined below.
Signature Scheme | Scheme Spec |
---|---|
ed25519Sha512_single | spec |
TODO provide template in this RFC directory.
To add a new signature scheme to this registry, follow the template provided to detail the new scheme as well as provide some test cases to produce and verify the signature scheme is working.
Drawbacks¶
Since digital signatures are non-repudiable, it's worth noting the privacy implications of using this functionality. In the event that a signer has chosen to share a message using a non-repudiable signature, they forgo the ability to prevent the verifier from sharing this signature on to other parties. This has potentially negative implications with regards to consent and privacy.
Therefore, this functionality should only be used if non-repudiable digital signatures are absolutely necessary.
Rationale and alternatives¶
JSON Web Signatures are an alternative to this specification in widespread use. We diverged from this specification for the following reasons:
- Does not support our need for message decorators (sign only parts of a DIDComm message)
- Does not support signature-aggregation featured in schemes like BLS signatures.
Prior art¶
IETF RFC 7515 (JSON Web Signatures)
Unresolved questions¶
Does there need to be an signature suite agreement protocol similar to TLS cipher suites? - No, rather the receiver of the message can send an error response if they're unable to validate the signature.
How should multiple signatures be represented?
- While not supported in this version, one solution would be to support [digital_sig1, digital_sig2]
for signature
and [verkey1, verkey2]
for signer
.
Implementations¶
The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.
Name / Link | Implementation Notes |
---|---|
Aries Static Agent - Python | ed25519sha256_single |
Aries Framework - .NET | ed25519sha256_single |
Aries Framework - Go | ed25519sha256_single |