EdDSA Cryptosuite v2022

W3C First Public Working Draft

More details about this document
This version:
https://www.w3.org/TR/2023/WD-vc-di-eddsa-20230418/
Latest published version:
https://www.w3.org/TR/vc-di-eddsa/
Latest editor's draft:
https://w3c.github.io/vc-di-eddsa/
History:
https://www.w3.org/standards/history/vc-di-eddsa
Commit history
Editors:
Manu Sporny (Digital Bazaar)
Dmitri Zagidulin (MIT Digital Credentials Consortium)
Authors:
Dave Longley (Digital Bazaar)
Manu Sporny (Digital Bazaar)
Feedback:
GitHub w3c/vc-di-eddsa (pull requests, new issue, open issues)

Abstract

This specification describes a Data Integrity cryptographic suite for use when creating or verifying a digital signature using the twisted Edwards Curve Digital Signature Algorithm (EdDSA) and Curve25519 (ed25519).

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

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

This document was published by the Verifiable Credentials Working Group as a First Public Working Draft using the Recommendation track.

Publication as a First Public Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

This specification defines a cryptographic suite for the purpose of creating, verifying proofs for Ed25519 EdDSA signatures in conformance with the Data Integrity [VC-DATA-INTEGRITY] specification. The approach is accepted by the U.S. National Institute of Standards in the latest FIPS 186-5 publication and meets U.S. Federal Information Processing requirements when using cryptography to secure digital information.

The suites described in this specification use the RDF Dataset Normalization Algorithm [RDF-CANON] or the JSON Canonicalization Scheme [RFC8785] to transform an input document into its canonical form. The canonical representation is then hashed and signed with a detached signature algorithm.

1.1 Terminology

This section defines the terms used in this specification. A link to these terms is included whenever they appear in this specification.

data integrity proof
A set of attributes that represent a digital proof and the parameters required to verify it.
private key
Cryptographic material that can be used to generate digital proofs.
challenge
A random or pseudo-random value used by some authentication protocols to mitigate replay attacks.
domain
A string value that specifies the operational domain of a digital proof. This could be an Internet domain name like example.com, an ad-hoc value such as mycorp-level3-access, or a very specific transaction value like 8zF6T8J34qP3mqP. A signer could include a domain in its digital proof to restrict its use to particular target, identified by the specified domain.
cryptographic suite
A specification defining the usage of specific cryptographic primitives in order to achieve a particular security goal. These documents are often used to specify verification methods, digital signature types, their identifiers, and other related properties.
decentralized identifier (DID)
A globally unique persistent identifier that does not require a centralized registration authority and is often generated and/or registered cryptographically. The generic format of a is defined in [DID-CORE]. Many—but not all—methods make use of distributed ledger technology (DLT) or some other form of decentralized network.
controller
An entity that has the capability to make changes to a controller document.
controller document
A set of data that specifies one or more relationships between a controller and a set of data, such as a set of public cryptographic keys.
subject
The entity identified by the id property in a controller document. Anything can be a subject: person, group, organization, physical thing, digital thing, logical thing, etc.
distributed ledger (DLT)
A non-centralized system for recording events. These systems establish sufficient confidence for participants to rely upon the data recorded by others to make operational decisions. They typically use distributed databases where different nodes use a consensus protocol to confirm the ordering of cryptographically signed transactions. The linking of digitally signed transactions over time often makes the history of the ledger effectively immutable.
verification method

A set of parameters that can be used together with a process to independently verify a proof. For example, a cryptographic public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated cryptographic private key.

"Verification" and "proof" in this definition are intended to apply broadly. For example, a cryptographic public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof."

1.2 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, and MUST NOT 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 proof 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. Data Model and 3. Algorithms of this document MUST be enforced.

A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming proof. 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.

2. Data Model

The following sections outline the data model that is used by this specification for verification methods and signature formats.

2.1 Verification Methods

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 generation and verification, according to [RFC8032].

This suite MAY be used to verify Data Integrity Proofs [VC-DATA-INTEGRITY] produced by Ed25519 public key material encoded as either a Ed25519VerificationKey2020 or Multikey. Loss-less key transformation processes that result in equivalent cryptographic material MAY be utilized.

2.1.1 Multikey

Issue 1

This definition should go in the Data Integrity specification and referenced from there.

The type of the verification method MUST be Multikey.

The controller of the verification method MUST be a URL.

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. The 34 byte value is then encoded using base58-btc (z) as the prefix. Any other encoding MUST NOT be allowed.

Developers are advised to not accidentally publish a representation of a private key. Implementations of this specification will raise errors in the event of a [MULTICODEC] value other than 0xed01 being used in a publicKeyMultibase value.

Example 1: An Ed25519 public key encoded as a Multikey
{
  "id": "https://example.com/issuer/123#key-0",
  "type": "Multikey",
  "controller": "https://example.com/issuer/123",
  "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
}
Example 2: An Ed25519 public key encoded as a Multikey in a controller document
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/data-integrity/v1"
  ],
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#key-0",
    "type": "Multikey",
    "controller": "did:example:123",
    "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
  }],
  "authentication": [
    "did:example:123#key-0"
  ],
  "assertionMethod": [
    "did:example:123#key-0"
  ],
  "capabilityDelegation": [
    "did:example:123#key-0"
  ],
  "capabilityInvocation": [
    "did:example:123#key-0"
  ]
}

2.1.2 Ed25519VerificationKey2020

Issue 2

We need to add documentation to note that this key format is deployed and widely used in production, but is deprecated. Multikey and JsonWebKey2020 supersede it.

The type of the verification method MUST be Ed25519VerificationKey2020.

The controller of the verification method MUST be a URL.

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. The 34 byte value is then encoded using base58-btc (z) as the prefix. Any other encoding MUST NOT be allowed.

Developers are advised to not accidentally publish a representation of a private key. Implementations of this specification will raise errors in the event of a [MULTICODEC] value other than 0xed01 being used in a publicKeyMultibase value.

Example 3: An Ed25519 public key encoded as an Ed25519VerificationKey2020
{
  "id": "https://example.com/issuer/123#key-0",
  "type": "Ed25519VerificationKey2020",
  "controller": "https://example.com/issuer/123",
  "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
}
Example 4: An Ed25519 public key encoded as an Ed25519VerificationKey2020 in a controller document.
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#key-0",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:example:123",
    "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
  }],
  "authentication": [
    "did:example:123#key-0"
  ],
  "assertionMethod": [
    "did:example:123#key-0"
  ],
  "capabilityDelegation": [
    "did:example:123#key-0"
  ],
  "capabilityInvocation": [
    "did:example:123#key-0"
  ]
}

2.2 Proof Representations

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

2.2.1 DataIntegrityProof

The verificationMethod property of the proof MUST be a URL. Dereferencing the verificationMethod MUST result in an object containing a type property with the value set to Ed25519VerificationKey2020.

The type property of the proof MUST be DataIntegrityProof.

The cryptosuite property of the proof MUST be eddsa-2022.

The created property of the proof MUST be an [XMLSCHEMA11-2] formated date string.

The proofPurpose property of the proof MUST be a string, and MUST 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] using the base58-btc base encoding.

Example 5: An Ed25519 digital signature expressed as a DataIntegrityProof
{
  "@context": [
    {"title": "https://schema.org/title"},
    "https://w3id.org/security/data-integrity/v1"
  ],
  "title": "Hello world!",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-2022",
    "created": "2020-11-05T19:23:24Z",
    "verificationMethod": "https://ldi.example/issuer#z6MkjLrk3gKS2nnkeWcmcxi
      ZPGskmesDpuwRBorgHxUXfxnG",
    "proofPurpose": "assertionMethod",
    "proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQA
      VHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
  }
}

2.2.2 Ed25519Signature2020

The verificationMethod property of the proof MUST be a URL. Dereferencing the verificationMethod MUST result in an object containing a type property with the value set to Ed25519VerificationKey2020.

The type property of the proof MUST be Ed25519Signature2020.

The created property of the proof MUST be an [XMLSCHEMA11-2] formated date string.

The proofPurpose property of the proof MUST be a string, and MUST 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] using the base58-btc base encoding.

Example 6: An Ed25519 digital signature expressed as a Ed25519Signature2020
{
  "@context": [
    {"title": "https://schema.org/title"},
    "https://w3id.org/security/data-integrity/v1"
  ],
  "title": "Hello world!",
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2020-11-05T19:23:24Z",
    "verificationMethod": "https://di.example/issuer#z6MkjLrk3gKS2nnkeWcmcxi
      ZPGskmesDpuwRBorgHxUXfxnG",
    "proofPurpose": "assertionMethod",
    "proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQA
      VHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
  }
}

3. Algorithms

The following section describes multiple Data Integrity cryptographic suites that utilize the twisted Edwards Curve Digital Signature Algorithm.

3.1 eddsa-2022

The eddsa-2022 cryptographic suite takes an input document, canonicalizes the document using the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof. The algorithms in this section also include the verification of such a data integrity proof.

3.1.1 Add Proof (eddsa-2022)

To generate a proof, the algorithm in Section 4.1: Add Proof in the Data Integrity [VC-DATA-INTEGRITY] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section 3.1.3 Transformation (eddsa-2022), the hashing algorithm is defined in Section 3.1.4 Hashing (eddsa-2022), and the proof serialization algorithm is defined in Section 3.1.6 Proof Serialization (eddsa-2022).

3.1.2 Verify Proof (eddsa-2022)

To verify a proof, the algorithm in Section 4.2: Verify Proof in the Data Integrity [VC-DATA-INTEGRITY] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section 3.1.3 Transformation (eddsa-2022), the hashing algorithm is defined in Section 3.1.4 Hashing (eddsa-2022), and the proof verification algorithm is defined in Section 3.1.7 Proof Verification (eddsa-2022).

3.1.3 Transformation (eddsa-2022)

The following algorithm specifies how to transform an unsecured input document into a transformed document that is ready to be provided as input to the hashing algorithm in Section 3.1.4 Hashing (eddsa-2022).

Required inputs to this algorithm are an unsecured data document (unsecuredDocument) and transformation options (options). The transformation options MUST contain a type identifier for the cryptographic suite (type) and a cryptosuite identifier (cryptosuite). A transformed data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.

  1. If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string eddsa-2020 then a PROOF_TRANSFORMATION_ERROR MUST be raised.
  2. Let canonicalDocument be the result of applying the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON] to the unsecuredDocument.
  3. Set output to the value of canonicalDocument.
  4. Return canonicalDocument as the transformed data document.

3.1.4 Hashing (eddsa-2022)

The following algorithm specifies how to cryptographically hash a transformed data document and proof configuration into cryptographic hash data that is ready to be provided as input to the algorithms in Section 3.1.6 Proof Serialization (eddsa-2022) or Section 3.1.7 Proof Verification (eddsa-2022).

The required inputs to this algorithm are a transformed data document (transformedDocument) and proof configuration (proofConfig). A single hash data value represented as series of bytes is produced as output.

  1. Let transformedDocumentHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) cryptographic hashing algorithm [RFC6234] to the transformedDocument. transformedDocumentHash will be exactly 32 bytes in size.
  2. Let proofConfigHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) cryptographic hashing algorithm [RFC6234] to the proofConfig. proofConfigHash will be exactly 32 bytes in size.
  3. Let hashData be the result of joining proofConfigHash (the first hash) with transformedDocumentHash (the second hash).
  4. Return hashData as the hash data.

3.1.5 Proof Configuration (eddsa-2022)

The following algorithm specifies how to generate a proof configuration from a set of proof options that is used as input to the proof hashing algorithm.

The required inputs to this algorithm are proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MUST contain a cryptosuite identifier (cryptosuite). A proof configuration object is produced as output.

  1. Let proofConfig be an empty object.
  2. Set proofConfig.type to options.type.
  3. If options.cryptosuite is set, set proofConfig.cryptosuite to its value.
  4. If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-2020, an INVALID_PROOF_CONFIGURATION error MUST be raised.
  5. Set proofConfig.created to options.created. If the value is not a valid [XMLSCHEMA11-2] datetime, an INVALID_PROOF_DATETIME error MUST be raised.
  6. Set proofConfig.verificationMethod to options.verificationMethod.
  7. Set proofConfig.proofPurpose to options.proofPurpose.
  8. Return proofConfig.

3.1.6 Proof Serialization (eddsa-2022)

The following algorithm specifies how to serialize a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData) and proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single digital proof value represented as series of bytes is produced as output.

  1. Let privateKeyBytes be the result of retrieving the private key bytes associated with the options.verificationMethod value as described in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Retrieving Cryptographic Material.
  2. Let proofBytes be the result of applying the Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032], using the Ed25519 variant (Pure EdDSA), with hashData as the data to be signed using the private key specified by privateKeyBytes. proofBytes will be exactly 64 bytes in size.
  3. Return proofBytes as the digital proof.

3.1.7 Proof Verification (eddsa-2022)

The following algorithm specifies how to verify a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData), a digital signature (proofBytes) and proof options (options). A verification result represented as a boolean value is produced as output.

  1. Let publicKeyBytes be the result of retrieving the public key bytes associated with the options.verificationMethod value as described in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Retrieving Cryptographic Material.
  2. Let verificationResult be the result of applying the verification algorithm for the Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032], using the Ed25519 variant (Pure EdDSA), with hashData as the data to be verified against the proofBytes using the public key specified by publicKeyBytes.
  3. Return verificationResult as the verification result.

3.2 jcs-eddsa-2022

Issue 3: Cryptosuite naming convention is disputed

The naming convention utilized by this cryptosuite is disputed. An alternative of json-eddsa-2022 was originally suggested for this cryptography suite to convey that it is a cryptography suite for securing JSON data utilizing the Twisted Edwards Curve Digital Signature Algorithm. The counter-argument to the original proposal was that expressing the canonicalization mechanism in the cryptosuite string clearly conveys to a developer that the thing that differentiates this cryptosuite from the eddsa-2022 one is the use of JSON Canonicalization Scheme [RFC8785]. Other options include "cryptosuite": "json-sign-2022", and "cryptosuite": "json-2022". This topic is currently being debated in the Data Integrity work item..

The jcs-eddsa-2022 cryptographic suite takes an input document, canonicalizes the document using the JSON Canonicalization Scheme [RFC8785], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof. The algorithms for this cryptographic suite are the same as the ones in Section 3.1 eddsa-2022 except for the following modifications:

In Section 3.1.3 Transformation (eddsa-2022), step 1) and step 2) are replaced by the following text:

  1. If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string jcs-eddsa-2022 then a PROOF_TRANSFORMATION_ERROR MUST be raised.
  2. Let canonicalDocument be the result of applying the JSON Canonicalization Scheme [RFC8785] to the unsecuredDocument.

In Section 3.1.5 Proof Configuration (eddsa-2022), step 4) is replaced by the following text:

4) If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to json-eddsa-2020, an INVALID_PROOF_CONFIGURATION error MUST be raised.

3.3 Ed25519Signature2020

The Ed25519Signature2020 cryptographic suite takes an input document, canonicalizes the document using the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof. The algorithms in this section also include the verification of such a data integrity proof.

3.3.1 Add Proof (Ed25519Signature2020)

To generate a proof, the algorithm in Section 4.1: Add Proof in the Data Integrity [VC-DATA-INTEGRITY] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section 3.3.3 Transformation (Ed25519Signature2020), the hashing algorithm is defined in Section , and the proof serialization algorithm is defined in Section 3.3.6 Proof Serialization (Ed25519Signature2020).

3.3.2 Verify Proof (Ed25519Signature2020)

To verify a proof, the algorithm in Section 4.2: Verify Proof in the Data Integrity [VC-DATA-INTEGRITY] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section 3.3.3 Transformation (Ed25519Signature2020), the hashing algorithm is defined in Section 3.3.4 Hashing (Ed25519Signature2020), and the proof verification algorithm is defined in Section 3.3.7 Proof Verification (Ed25519Signature2020).

3.3.3 Transformation (Ed25519Signature2020)

The following algorithm specifies how to transform an unsecured input document into a transformed document that is ready to be provided as input to the hashing algorithm in Section 3.3.4 Hashing (Ed25519Signature2020).

Required inputs to this algorithm are an unsecured data document (unsecuredDocument) and transformation options (options). The transformation options MUST contain a type identifier for the cryptographic suite (type) and a cryptosuite identifier (cryptosuite). A transformed data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.

  1. If options.type is not set to the string Ed25519Signature2020, then a PROOF_TRANSFORMATION_ERROR MUST be raised.
  2. Let canonicalDocument be the result of applying the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON] to the unsecuredDocument.
  3. Set output to the value of canonicalDocument.
  4. Return canonicalDocument as the transformed data document.

3.3.4 Hashing (Ed25519Signature2020)

The following algorithm specifies how to cryptographically hash a transformed data document and proof configuration into cryptographic hash data that is ready to be provided as input to the algorithms in Section 3.3.6 Proof Serialization (Ed25519Signature2020) or Section 3.3.7 Proof Verification (Ed25519Signature2020).

The required inputs to this algorithm are a transformed data document (transformedDocument) and proof configuration (proofConfig). The proof configuration MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single hash data value represented as series of bytes is produced as output.

  1. Let transformedDocumentHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) cryptographic hashing algorithm [RFC6234] to the transformedDocument. transformedDocumentHash will be exactly 32 bytes in size.
  2. Let proofConfigHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) cryptographic hashing algorithm [RFC6234] to the proofConfig. proofConfigHash will be exactly 32 bytes in size.
  3. Let hashData be the result of joining proofConfigHash (the first hash) with transformedDocumentHash (the second hash).
  4. Return hashData as the hash data.

3.3.5 Proof Configuration (Ed25519Signature2020)

The following algorithm specifies how to generate a proof configuration from a set of proof options that is used as input to the proof hashing algorithm.

The required inputs to this algorithm are proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A proof configuration object is produced as output.

  1. Let proofConfig be an empty object.
  2. Set proofConfig.type to options.type.
  3. If options.cryptosuite is set, set proofConfig.cryptosuite to its value.
  4. If options.type is not set to Ed25519Signature2020, an INVALID_PROOF_CONFIGURATION error MUST be raised.
  5. Set proofConfig.created to options.created. If the value is not a valid [XMLSCHEMA11-2] datetime, an INVALID_PROOF_DATETIME error MUST be raised.
  6. Set proofConfig.verificationMethod to options.verificationMethod.
  7. Set proofConfig.proofPurpose to options.proofPurpose.
  8. Return proofConfig.

3.3.6 Proof Serialization (Ed25519Signature2020)

The following algorithm specifies how to serialize a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData) and proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single digital proof value represented as series of bytes is produced as output.

  1. Let privateKeyBytes be the result of retrieving the private key bytes associated with the options.verificationMethod value as described in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Retrieving Cryptographic Material.
  2. Let proofBytes be the result of applying the Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032], using the Ed25519 variant (Pure EdDSA), with hashData as the data to be signed using the private key specified by privateKeyBytes. proofBytes will be exactly 64 bytes in size.
  3. Return proofBytes as the digital proof.

3.3.7 Proof Verification (Ed25519Signature2020)

The following algorithm specifies how to verify a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData), a digital signature (proofBytes) and proof options (options). A verification result represented as a boolean value is produced as output.

  1. Let publicKeyBytes be the result of retrieving the public key bytes associated with the options.verificationMethod value as described in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Retrieving Cryptographic Material.
  2. Let verificationResult be the result of applying the verification algorithm for the Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032], using the Ed25519 variant (Pure EdDSA), with hashData as the data to be verified against the proofBytes using the public key specified by publicKeyBytes.
  3. Return verificationResult as the verification result.

4. 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-CANON].

Note

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

Issue 4

There are known mis-implementation attacks against multiple flavors of EdDSA implementations. We might want to warn about what to look out for and how to mitigate the attacks.

5. Privacy Considerations

The following section describes privacy considerations that developers implementing this specification should be aware of in order to avoid violating privacy assumptions.

Issue 5

This cryptography suite does not provide for selective disclosure or unlinkability. If signatures are re-used, they can be used as correlatable data.

A. Test Vectors

A.1 Representation: Ed25519Signature2020

The signer needs to generate a private/public key pair with the private key used for signing and the public key made available for verification. The [MULTIBASE]/[MULTICODEC] representation for the public key, ed25519-pub, and the representation for the private key, ed25519-priv, are shown below.

Example 7: Private and Public keys for Signature
{
    publicKeyMultibase: "z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
    privateKeyMultibase: "z3u2en7t5LR2WtQH5PfFqMqwVHBeXouLzo6haApm8XHqvjxq"
}

Signing begins with a credential without an attached proof, which is converted to canonical form, and then hashed, as shown in the following three examples.

Example 8: Credential without Proof
{
  "@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.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "issuer": "https://example.edu/issuers/565049",
  "issuanceDate": "2010-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  }
}
Example 9: Canonical Credential without Proof
<did:example:ebfeb1f712ebc6f1c276e12ec21> <https://example.org/examples#degree> _:c14n0 .
<http://example.edu/credentials/3732> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://example.org/examples#UniversityDegreeCredential> .
<http://example.edu/credentials/3732> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#credentialSubject> <did:example:ebfeb1f712ebc6f1c276e12ec21> .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#issuanceDate> "2010-01-01T00:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<http://example.edu/credentials/3732> <https://www.w3.org/2018/credentials#issuer> <https://example.edu/issuers/565049> .
_:c14n0 <http://schema.org/name> "Bachelor of Science and Arts"^^<http://www.w3.org/1999/02/22-rdf-syntax-ns#HTML> .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://example.org/examples#BachelorDegree> .
Example 10: Hash of Canonical Credential without Proof (hex)
6c6b2795e7fa33a9fb28062527142b3c6edf7ba239942439b6f0bb0851b3cce3

The next step is to take the proof options document, convert it to canonical form, and obtain its hash, as shown in the next three examples.

Example 11: Proof Options Document
{
  "type": "Ed25519Signature2020",
  "created": "2022-12-07T21:31:08Z",
  "verificationMethod": "https://example.edu/issuers/565049#key-1",
  "proofPurpose": "assertionMethod",
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ]
}
Example 12: Canonical Proof Options Document
_:c14n0 <http://purl.org/dc/terms/created> "2022-12-07T21:31:08Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/security#Ed25519Signature2020> .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <https://example.edu/issuers/565049#key-1> .
Example 13: Hash of Canonical Proof Options Document (hex)
565a2884ebb2d38aa34871108074ab51631ec812d33eb2473178bce19937ad09

Finally, we combine the two hashes, use the private key with the combined hash to compute the Ed25519 signature, and then base58-btc encode the signature.

Example 14: Combine hashes of Proof Options and Credential (hex)
565a2884ebb2d38aa34871108074ab51631ec812d33eb2473178bce19937ad096c6b2795e7fa33a9fb28062527142b3c6edf7ba239942439b6f0bb0851b3cce3
Example 15: Signature of Combined Hashes (hex)
473fb02a4aaf5863a2ef33f104bd55617e40907bc311e29e87278d15d7596f201639f41ec0e00db11159e9139f673d9257558e1f0134e1f67ac73f91ed89670b
Example 16: Signature of Combined Hashes base58-btc
z2RczMj342tVhAjgjEPV4TeHbi2ggnTRKTc5BFQCgaWJ3nhcg5HgCeC2eV4Lc1fYdhfoLyPjxoq4BtqrsyNvxZ8nE

Assemble the signed credential with the following two steps:

  1. Add the proofValue field with the previously computed base58-btc value to the proof options document.
  2. Set the proof field of the credential to the augmented proof option document.
Example 17: Signed Credential
{
  "@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.edu/credentials/3732",
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "issuer": "https://example.edu/issuers/565049",
  "issuanceDate": "2010-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2022-12-07T21:31:08Z",
    "verificationMethod": "https://example.edu/issuers/565049#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z2RczMj342tVhAjgjEPV4TeHbi2ggnTRKTc5BFQCgaWJ3nhcg5HgCeC2eV4Lc1fYdhfoLyPjxoq4BtqrsyNvxZ8nE"
  }
}

B. References

B.1 Normative references

[DID-CORE]
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/
[MULTIBASE]
Multibase. URL: https://datatracker.ietf.org/doc/html/draft-multiformats-multibase-01
[MULTICODEC]
Multicodec. URL: https://github.com/multiformats/multicodec/
[RDF-CANON]
RDF Dataset Canonicalization. Gregg Kellogg; Dave Longley; Manu Sporny. W3C RDF Dataset Canonicalization and Hash Working Group. W3C Editor's Draft. URL: https://www.w3.org/TR/rdf-canon/
[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
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[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
[RFC8785]
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman. IETF. June 2020. Informational. URL: https://www.rfc-editor.org/rfc/rfc8785
[VC-DATA-INTEGRITY]
Verifiable Credential Data Integrity. Manu Sporny; Dave Longley; Mike Prorock. Verifiable Credentials Working Group. W3C Editor's Draft. URL: https://w3c.github.io/vc-data-integrity/
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

B.2 Informative references

[VC-DATA-MODEL-2]
Verifiable Credentials Data Model v2.0. Manu Sporny; Dave Longley; Grant Noble; Dan Burnett; Ted Thibodeau; Brent Zundel; David Chadwick; Kyle Den Hartog. W3C Verifiable Credentials Working Group. Working Draft. URL: https://www.w3.org/TR/vc-data-model-2.0/