[[LD-SIGNATURES]] provide an ability to embed integrity and authentication cryptographic capabilities inside [[JSON]] documents. This property is desirable, especially when compared to the opaque nature of string based representations such as [[JWT]].

Some implementers do not desire to leverageg [[JSON-LD]], or other properties of RDF and Linked Data Formats. The purpose of this suite is to define a Linked Data Suite that does not use [[RDF-DATASET-NORMALIZATION]], but that produces [[JSON]] documents that look like [[JSON-LD]] documents with [[LD-SIGNATURES]].

Because this suite cannot assume JSON-LD features such as documentLoaders or canonicalization algorithm. Extra guidance is required for implementers who wish to use this suite without these features.

This suite is not compatible with JSON-LD.

DID Configuration is a draft specification being developed within the Decentralized Identity Foundation (DIF), and intended for registration with W3C CCG Linked Data Crypto Suite Registry. This spec will be updated to reflect relevant changes, and participants are encouraged to contribute at the following repository location: https://github.com/decentralized-identity/JcsEd25519Signature2020

Terminology

The following terms are used to describe concepts involved in the generation and verification of the JCS Ed25519 Signature 2020 signature suite.

signature suite
A specified set of cryptographic primitives typically consisting of a canonicalization algorithm, a message digest algorithm, and a signature algorithm that are bundled together by cryptographers for developers for the purposes of safety and convenience.
canonicalization algorithm
An algorithm that takes an input document that has more than one possible representation and always transforms it into a canonical form. This process is sometimes also called normalization.
message digest algorithm
An algorithm that takes an input message and produces a cryptographic output message that is often many orders of magnitude smaller than the input message. These algorithms are often 1) very fast, 2) non-reversible, 3) cause the output to change significantly when even one bit of the input message changes, and 4) make it infeasible to find two different inputs for the same output.
signature algorithm
An algorithm that takes an input message and produces an output value where the receiver of the message can mathematically verify that the message has not been modified in transit and came from someone possessing a particular secret.
controller

See the normative definition here, [[vc-data-model]].

documentLoader

See the normative definition here, [[json-ld11-api]].

verificationMethod

See the normative definition here, [[json-ld11-api]].

Key Format

Ed25519 2018 Signature Verification Key

The key format is Ed25519VerificationKey2018.

An Ed25519VerificationKey2018 using this suite MUST contain a publicKeyBase58 property. 

{
  "id": "did:example:123",
  "publicKey": [
    {
      "id": "did:example:123#key-1",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:example:123",
      "publicKeyBase58": "4CcKDtU1JNGi8U4D8Rv9CHzfmF7xzaxEAPFA54eQjRHF"
    }
  ]
}

Resolving Key Material

When the suite is used with [[JSON]] a verifier MUST derefence the controller referenced by verificationMethod. Iterate the properties of the controller and find the key material matching the verificationMethod property value in the proof.

The JCS Ed25519 Signature 2020 Signature Suite

This signature suite MUST be used in conjunction with the signing and verification algorithms in the Linked Data Signatures [[LD-SIGNATURES]] specification. The suite consists of the following algorithms:

Parameter Value Specification
canonicalizationAlgorithm JSON Canonicalization Scheme (JCS) [[JCS]]
digestAlgorithm SHA-256 [[RFC6234]]
signatureAlgorithm Ed25519 [[RFC8032]]

Modification to Algorithms

The Create Verify Data Algorithm has been replaced with a deterministic transformation of document to be signed and proof object.

JCS Ed25519 Signature 2020

A document signed with JCS Ed25519 Signature 2020 MUST contain a proof property.

Proof Generation Algorithm

Proofs are generated using the following algorithm:

  1. Take the input document, embeded with a proof block containing all values except the signatureValue
  2. Canonicalize the document using JCS
  3. Apply the SHA-256 Hash Algorithm.
  4. Sign the result with the private key
  5. Base58 encode the result and set it as the signatureValue on the document

{
  "id": "did:test:36FC2p3yXoxcoVBn73qxPx",
  "publicKey": [
    {
      "id": "did:test:36FC2p3yXoxcoVBn73qxPx#key-1",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:test:36FC2p3yXoxcoVBn73qxPx",
      "publicKeyBase58": "295nPvQHCdfXT8N275Hme434Z2NqZY5y3NN7rdts8Ew1"
    }
  ],
  "authentication": null,
  "service": [
    {
      "id": "test-service-1",
      "type": "test-service",
      "serviceEndpoint": "https://test-service.com/test-service"
    }
  ],
  "proof": {
    "created": "2020-09-24T16:43:29Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:test:36FC2p3yXoxcoVBn73qxPx#key-1",
    "nonce": "fd2ccdaa-a9eb-4927-9ad2-3c0ad84546d5",
    "signatureValue": "2Ha72f5KqowpAeLxF2UvDBYgknLiHeBk9W6g7FHhPTd26M5qDgSfmWrpJareNp3bb9apwfUKysjFmbFcEN4LXLg7",
    "type": "JcsEd25519Signature2020"
  }
}

Security Considerations

The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.

TODO: We need to add a complete list of security considerations.

This document contains examples that contain [[JSON]] and [[JSON-LD]] content. Some of these examples contain characters that are invalid, such as inline comments (//) and the use of ellipsis (...) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid [[JSON]], or [[JSON-LD]].