Skip to main content
Version: 0.6

Signing

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​

Allows a trusted-party to request the signing of an unsigned verifiable credential by an issuer.

Relationships​

Example Use-Cases​

  • A separate department requests a signature by the legal department of a company.
  • A subsidiary requests the parent company to sign a credential.
  • An IOT device generates an unsigned credential and requests a secure server to sign it.

Roles​

  • Trusted-Party: trusted by the issuer to generate unsigned credentials asserting claims about one or more subjects.
  • Issuer: has the capability to cryptographically sign credentials.

Interaction​

SigningDiagram

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

Messages​

1. signing-request​

Request by a trusted-party for an issuer to sign a credential.

To authenticate the trusted-party, this SHOULD be sent using sender authenticated encryption established in a preceding authentication protocol. For non-repudiation or auditing, the issuer MAY enforce that the signing-request be a signed DIDComm message.

Structure​

{
  "unsignedCredential": Credential // REQUIRED
}
FieldDescriptionRequired
unsignedCredentialUnsigned verifiable credential requested to be signed by the issuer.1✔

1 The initial credential MUST NOT have a proof section.

Examples​

  1. Request to sign a bachelors degree.
{
  "unsignedCredential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f",
    "issuanceDate": "2021-05-03T19:73:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  }
}

2. signing-response​

  • Type: iota/signing/0.1/signing-response
  • Role: issuer

Response from the issuer returning the signed credential back to the trusted-party.

Structure​

{
  "signedCredential": Credential // REQUIRED
}
FieldDescriptionRequired
signedCredentialSigned verifiable credential matching the signing-request.1✔

1 The trusted-party MUST validate the signature in the proof section and issue a problem-report if invalid. The trusted-party SHOULD also verify that the contents of the signedCredential sent back by the issuer are complete and unaltered from the signing-request.

The issuer may request in turn that the credential be signed by a different issuer unknown to the trusted-party, by repeating this protocol or through alternative means. In such a case, it is up to the initial trusted-party whether or not to accept the final signature if not signed by the initial issuer they requested.

Examples​

  1. Respond with a signed a bachelors degree.
{
  "signedCredential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f",
    "issuanceDate": "2021-05-03T19:73:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    },
    "proof": {...}
  }
}

3. signing-acknowledgement​

  • Type: iota/signing/0.1/signing-acknowledgement
  • Role: trusted-party

Acknowledgement by the trusted-party that the credential was received and accepted. The issuer MAY revoke the credential if no acknowledgement is received. For auditing or non-repudiation the issuer MAY require that the signing-acknowledgement be a signed DIDComm message.

Structure​

{
  "accepted": bool // REQUIRED
}
FieldDescriptionRequired
acceptedIndicates that the signedCredential was received and validated by the trusted-party.1✔

1 accepted MUST be true. Invalid signatures or credentials SHOULD result in problem-reports by the trusted-party.

Examples​

  1. Accept the credential.
{
  "accepted": true
}

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.signing.reject-requestsigning-requestThe issuer rejects a signing request for any reason, e.g. malformed credential, unrecognised credential type, or unwillingness to sign the specific credential for the trusted-party.
e.p.msg.iota.signing.reject-responsesigning-responseThe trusted-party rejects a signing response for any reason, e.g. mismatch between request and response credentials.

Unresolved Questions​

  • Using a signed DIDComm message for auditing requires retaining the entire message including the credential itself. While this may be desired or required for some purposes, it could complicate or violate GDPR laws. Should an explicit signature of the credential hash be used instead, similar to the issuance protocol?

Considerations​

This section is non-normative.

  • Security: implementors SHOULD transmit credentials over an encrypted channel to prevent leaking sensitive information on subjects. See sender-authenticated encryption.
  • Authentication: it is RECOMMENDED to use sender-authenticated encryption for continuous authentication of both parties in the DIDComm thread. Anonymous encryption and/or once-off authentication may be insufficient.
  • Authorisation: the issuer should establish whether a trusted-party is allowed to request signing of a particular credential or at all.
  • Validation: apart from verifying the proof on the signed credential returned in the signing-response, how the issuer validates the contents of a well-formed credential from a trusted-party and chooses whether or not to sign it is out-of-scope.

Further Reading​