EdDSA Cryptosuite v2020

Final Community Group Report

This version:
https://www.w3.org/community/reports/credentials/CG-FINAL-di-eddsa-2020-20220724/
Latest published version:
https://www.w3.org/community/reports/credentials/CG-FINAL-di-eddsa-2020-20220724/
Latest editor's draft:
https://w3c-ccg.github.io/di-eddsa-2020/
Editors:
Orie Steele (Transmute)
Manu Sporny (Digital Bazaar)
Tobias Looker (MATTR)
Feedback:
GitHub w3c-ccg/di-eddsa-2020 (pull requests, new issue, open issues)
public-credentials@w3.org with subject line [di-eddsa-2020] … message topic … (archives)

Copyright © 2022 the Contributors to the EdDSA Cryptosuite v2020 Specification, published by the Credentials Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.

Abstract

This specification describes a Data Integrity Cryptosuite for use when creating or verifying a digital signature using the twisted Edwards Curve Digital Signature Algorithm (EdDSA) and Curve25519 (ed25519). The approach is accepted by the U.S. National Institute of Standards in the latest FIPS 186-5 draft and, after ratification, is expected to meet U.S. Federal Information Processing requirements when using cryptography to secure digital information.

Status of This Document

This specification was published by the Credentials Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.

This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-credentials@w3.org (subscribe, archives).

1. Introduction

This specification defines a cryptographic suite for the purpose of creating, verifying proofs for Ed25519 EdDSA signatures in conformance with the Linked Data Proofs [LD-PROOFS] specification.

In general the suites uses the RDF Dataset Normalization Algorithm [RDF-DATASET-NORMALIZATION] to transform an input document into its canonical form. The cannonical representation is then hashed and signed with a detached signature algorithm.

2. Terminology

The following terms are used to describe concepts involved in the generation and verification of the Linked Data Proof 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 a message, prefferably in some canonical form and produces a cryptographic output called a digest 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.
canonical form
The output of applying a canonicalization algorithm to an input document.
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.
Ed25519VerificationKey2020
The type of the verification method for the signature suite Ed25519Signature2020.
Ed25519Signature2020
The type of the linked data proof for the signature suite Ed25519Signature2020.

3. Suite Definition

The Ed25519 signature suite 2020 MUST be used in conjunction with the signing and verification algorithms in the Linked Data Proofs [LD-PROOFS] specification. The suite consists of the following algorithms:

Parameter Value Specification
canonicalization algorithm https://w3id.org/security#URDNA2015 [RDF-DATASET-NORMALIZATION]
message digest algorithm SHA-256 [RFC6234]
signature algorithm Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]

3.1 Verification Method

The cryptographic material used to verify a linked data proof is called the verification method.

This suite relies on public key material represented using [MULTIBASE] and [MULTICODEC].

This suite supports public key use for both digital signature verification, according to [RFC8032].

This suite MAY be used to verify linked data proofs produced by key material in any representation that can be converted to publicKeyMultibase>, however it is RECOMMENDED that this suite be used with verification method's of type Ed25519VerificationKey2020.

3.1.1 Ed25519VerificationKey2020

The id of the verification method SHOULD be the JWK thumbprint calculated from the publicKeyMultibase property value according to [MULTIBASE].

The type of the verification method SHOULD be Ed25519VerificationKey2020.

The controller of the verification method SHOULD be a URI.

The publicKeyMultibase property of the verification method MUST be a public key encoded according to [MULTICODEC] and formatted according to [MULTIBASE]. The multicodec encoding of a Ed25519 public key is the two-byte prefix 0xed01 followed by the 32-byte public key data.

Be careful not to accidentally publish a representation of a private key.

Example 1 
{
  "id": "https://example.com/issuer/123#key-0",
  "type": "Ed25519VerificationKey2020",
  "controller": "https://example.com/issuer/123",
  "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
}
Example 2: Example in DID Document. 
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    {
      "@base": "did:example:123"
    }
  ],
  "id": "did:example:123",
  "publicKey": [
    {
      "id": "#key-0",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:example:123",
      "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
    }
  ],
  "authentication": [
    "#key-0"
  ],
  "assertionMethod": [
    "#key-0"
  ],
  "capabilityDelegation": [
    "#key-0"
  ],
  "capabilityInvocation": [
    "#key-0"
  ]
}

3.2 Proof Representation

The cryptographic material used to represent a linked data proof is called the proof type.

This suite relies on detached digital signatures represented using [MULTIBASE] and [MULTICODEC].

3.2.1 Ed25519 Signature 2020

The verificationMethod property of the proof SHOULD be a URI. Dereferencing the verificationMethod SHOULD result in an object of type Ed25519VerificationKey2020.

The type property of the proof MUST be Ed25519Signature2020.

The created property of the proof MUST be an [ISO_8601] formated date string.

The proofPurpose property of the proof MUST be a string, and SHOULD match the verification relationship expressed by the verification method controller.

The proofValue property of the proof MUST be a detached EdDSA produced according to [RFC8032], encoded according to [MULTIBASE].

4. Test Vectors

The following test vectors are provided to assist with implementers.

Example 3 
{
  "seed_0": "9b937b81322d816cfab9d5a3baacc9b2a5febe4b149f126b3630f93a29527017"
}
Example 4 
{
  "keypair_0": {
    "id": "https://example.com/issuer/123#key-0",
    "type": "Ed25519VerificationKey2018",
    "controller": "https://example.com/issuer/123",
    "publicKeyBase58": "dbDmZLTWuEYYZNHFLKLoRkEX4sZykkSLNQLXvMUyMB1",
    "privateKeyBase58": "47QbyJEDqmHTzsdg8xzqXD8gqKuLufYRrKWTmB7eAaWHG2EAsQ2GUyqRqWWYT15dGuag52Sf3j4hs2mu7w52mgps"
  },
  "keypair_1": {
    "id": "https://example.com/issuer/123#key-0",
    "type": "Ed25519KeyPair2020",
    "controller": "https://example.com/issuer/123",
    "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP",
    "privateKeyMultibase": "zrv3kJcnBP1RpYmvNZ9jcYpKBZg41iSobWxSg3ix2U7Cp59kjwQFCT4SZTgLSL3HP8iGMdJs3nedjqYgNn6ZJmsmjRm"
  }
}
Example 5 
{
  "issuer_0": {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1",
      {
        "@base": "https://example.com/issuer/123"
      }
    ],
    "id": "https://example.com/issuer/123",
    "verificationMethod": [
      {
        "id": "#key-0",
        "type": "Ed25519VerificationKey2020",
        "controller": "https://example.com/issuer/123",
        "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
      }
    ],
    "assertionMethod": ["#key-0"],
    "authentication": ["#key-0"]
  }
}
Example 6 
{
  "vc_template_0": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1",
    ],
    "id": "http://example.gov/credentials/3732",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "https://example.com/issuer/123",
    "issuanceDate": "2020-03-10T04:24:12.164Z",
    "credentialSubject": {
      "id": "did:example:456",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  },
  "vc_0": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "http://example.gov/credentials/3732",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "https://example.com/issuer/123",
    "issuanceDate": "2020-03-10T04:24:12.164Z",
    "credentialSubject": {
      "id": "did:example:456",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2019-12-11T03:50:55Z",
      "proofValue": "z5SpZtDGGz5a89PJbQT2sgbRUiyyAGhhgjcf86aJHfYcfvPjxn6vej5na6kUzmw1jMAR9PJU9mowshQFFdGmDN14D",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "https://example.com/issuer/123#key-0"
    }
  },
  "vp_0": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "type": ["VerifiablePresentation"],
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://www.w3.org/2018/credentials/examples/v1",
          "https://w3id.org/security/suites/ed25519-2020/v1"
        ],
        "id": "http://example.gov/credentials/3732",
        "type": ["VerifiableCredential", "UniversityDegreeCredential"],
        "issuer": "https://example.com/issuer/123",
        "issuanceDate": "2020-03-10T04:24:12.164Z",
        "credentialSubject": {
          "id": "did:example:456",
          "degree": {
            "type": "BachelorDegree",
            "name": "Bachelor of Science and Arts"
          }
        },
        "proof": {
          "type": "Ed25519Signature2020",
          "created": "2019-12-11T03:50:55Z",
          "proofValue": "z5SpZtDGGz5a89PJbQT2sgbRUiyyAGhhgjcf86aJHfYcfvPjxn6vej5na6kUzmw1jMAR9PJU9mowshQFFdGmDN14D",
          "proofPurpose": "assertionMethod",
          "verificationMethod": "https://example.com/issuer/123#key-0"
        }
      }
    ],
    "id": "urn:uuid:83895ddf-52ee-4408-8796-51a1856dbbec",
    "holder": "did:ex:12345",
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2021-06-04T20:50:09Z",
      "verificationMethod": "https://example.com/issuer/123#key-0",
      "proofPurpose": "authentication",
      "challenge": "123",
      "proofValue": "z2y3UBXAiToXLzQqeMnHiMozJ3hKxcMgLm7p8GRQA92F6JSYu49RxHQf6k1CMKnMdpj3BLRSH69b9qA9cfjE3oS7q"
    }
  }
}

5. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A conforming document is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections 2. Terminology and 3. Suite Definition of this document MUST be enforced.

A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming document. Conforming processors MUST produce errors when non-conforming documents are consumed.

This document also contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid JSON, 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.

6. Security Considerations

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

Note

This specification relies on URDNA2015, please review [RDF-DATASET-NORMALIZATION].

Note

This specification relies on [MULTIBASE], [MULTICODEC] and [RFC8032].

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

A. References

A.1 Normative references

[ISO_8601]
ISO_8601. URL: https://en.wikipedia.org/wiki/ISO_8601
[LD-PROOFS]
Linked Data Proofs 1.0. David Longley; Manu Sporny. Web Payments Community Group. CGDRAFT. URL: https://w3c-ccg.github.io/ld-proofs
[MULTIBASE]
Multibase. URL: https://tools.ietf.org/html/draft-multiformats-multibase-01
[MULTICODEC]
Multicodec. URL: https://github.com/multiformats/multicodec/
[RDF-DATASET-NORMALIZATION]
RDF Dataset Normalization 1.0. David Longley; Manu Sporny. JSON-LD Community Group. CGDRAFT. URL: http://json-ld.github.io/normalization/spec/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC6234]
US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF). D. Eastlake 3rd; T. Hansen. IETF. May 2011. Informational. URL: https://www.rfc-editor.org/rfc/rfc6234
[RFC8032]
Edwards-Curve Digital Signature Algorithm (EdDSA). S. Josefsson; I. Liusvaara. IETF. January 2017. Informational. URL: https://www.rfc-editor.org/rfc/rfc8032
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174