Data Integrity EdDSA Cryptosuites v1.0

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).

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.

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."

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 contains examples of JSON and JSON-LD data. Some of these examples are invalid JSON, as they include features such as inline comments (//) explaining certain portions and ellipses (...) indicating the omission of information that is irrelevant to the example. These parts would have to be removed in order to treat the examples as valid JSON or JSON-LD.

The following sections outline the data model that is used by this specification to express verification methods, such as cryptographic public keys, and data integrity proofs, such as digital signatures.

This cryptographic suite is used to verify Data Integrity Proofs [VC-DATA-INTEGRITY] produced using Edwards Curve cryptographic key material. The encoding formats for those key types are provided in this section. Lossless cryptographic key transformation processes that result in equivalent cryptographic key material MAY be used for the processing of digital signatures.

The Multikey format, defined in [VC-DATA-INTEGRITY], is used to express public keys for the cryptographic suites defined in this specification.

The publicKeyMultibase value of the verification method MUST be 35 bytes in length and starts with the base-58-btc prefix (z), as defined in the Multibase section of [VC-DATA-INTEGRITY]. A Multibase-encoded Multikey value follows, which MUST consist of a binary value that starts with the two-byte prefix 0xed01, which is the Multikey header for an Ed25519 public key, followed by the 32-byte public key data, all of which is then encoded using base-58-btc. 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 if they encounter a Multikey prefix value other than 0xed01 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"
  ]
}

The secretKeyMultibase property represents a Multibase-encoded Multikey expression of an Ed25519 secret key (sometimes also referred to as a private key). The value starts with the two-byte prefix 0x8026, followed by the 32-byte Ed25519 secret key data. The combined 34-byte value is then base58-btc encoded and z is added as the prefix on the encoded value.

Developers are advised to prevent accidental publication of a representation of a secret key, and to not export the secretKeyMultibase property by default, when serializing key pairs to Multikey.

This section details the proof representation formats that are defined by this specification.

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 Multikey.

The type property of the proof MUST be DataIntegrityProof.

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

The created property of the proof MUST be an [XMLSCHEMA11-2] formatted 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 using the base-58-btc header and alphabet as described in the Multibase section of [VC-DATA-INTEGRITY].

Example 3: An Ed25519 digital signature expressed as a DataIntegrityProof

{
  "@context": [
    {"title": "https://schema.org/title"},
    "https://www.w3.org/ns/credentials/v2"
  ],
  "title": "Hello world!",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1
      cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
    "proofPurpose": "assertionMethod",
    "proofValue": "z5C5b1uzYJN6pDR3aWgAqUMoSB1JY29epA74qyjaie9qh4okm9DZP6y77eTNq
      5NfYyMwNu9bpQQWUHKH5zAmEtszK"
  }
}

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

The eddsa-rdfc-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.

When the RDF Dataset Canonicalization Algorithm [RDF-CANON] is used, implementations will detect dataset poisoning by default, and abort processing upon such detection.

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-rdfc-2022), the hashing algorithm is defined in Section 3.1.4 Hashing (eddsa-rdfc-2022), and the proof serialization algorithm is defined in Section 3.1.6 Proof Serialization (eddsa-rdfc-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-rdfc-2022), the hashing algorithm is defined in Section 3.1.4 Hashing (eddsa-rdfc-2022), and the proof verification algorithm is defined in Section 3.1.7 Proof Verification (eddsa-rdfc-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-rdfc-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.

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

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-rdfc-2022) or Section 3.1.7 Proof Verification (eddsa-rdfc-2022).

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

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.
Let proofConfigHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) cryptographic hashing algorithm [RFC6234] to the canonicalProofConfig. proofConfigHash will be exactly 32 bytes in size.
Let hashData be the result of joining proofConfigHash (the first hash) with transformedDocumentHash (the second hash).
Return hashData as the hash data.

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.

Let proofConfig be an empty object.
Set proofConfig.type to options.type.
If options.cryptosuite is set, set proofConfig.cryptosuite to its value.
If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-rdfc-2022, an INVALID_PROOF_CONFIGURATION error MUST be raised.
Set proofConfig.created to options.created. If the value is not a valid [XMLSCHEMA11-2] datetime, an INVALID_PROOF_DATETIME error MUST be raised.
Set proofConfig.verificationMethod to options.verificationMethod.
Set proofConfig.proofPurpose to options.proofPurpose.
Set proofConfig.@context to unsecuredDocument.@context
Let canonicalProofConfig be the result of applying the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON] to the proofConfig.
Return canonicalProofConfig.

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.

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.
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.
Return proofBytes as the digital proof.

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.

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.
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.
Return verificationResult as the verification result.

The eddsa-jcs-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-rdfc-2022 except for the following modifications:

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

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

In Section 3.1.5 Proof Configuration (eddsa-rdfc-2022), step 8) is not performed, and steps 4) and 9) are replaced by the following text:

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

9) Let canonicalProofConfig be the result of applying the JSON Canonicalization Scheme [RFC8785] to the proofConfig.

Before reading this section, readers are urged to familiarize themselves with general security advice provided in the Security Considerations section of the Data Integrity specification.

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

This section is non-normative.

Ed25519 signatures (EdDSA algorithm with edwards25519 curve) have been widely adopted, due both to the compact size of the keys and signatures and to the speed at which signatures can be produced and verified. Many libraries exist that can create and verify Ed25519 signatures. Since the publication of [RFC8032], security properties of Ed25519 signatures have been rigorously proven (see [Provable_Ed25519] and [Taming_EdDSAs]). However, it has been observed that a significant number of libraries do not achieve these security levels, due to missing input validity checks during the signature verification process. In this section, we summarize the security levels achievable with Ed25519 signatures, and indicate how one can determine whether a library will support those levels.

Digital signatures may exhibit a number of desirable cryptographic properties [Taming_EdDSAs] among these are:

EUF-CMA (existential unforgeability under chosen message attacks) is usually the minimal security property required of a signature scheme. It guarantees that any efficient adversary who has the public key $\begin{matrix} p k \end{matrix}$ of the signer and received an arbitrary number of signatures on messages of its choice (in an adaptive manner): $\begin{matrix} {m_{i}, σ_{i}}_{i = 1}^{N} \end{matrix}$ , cannot output a valid signature $\begin{matrix} σ^{*} \end{matrix}$ for a new message $\begin{matrix} m^{*} \notin {m_{i}}_{i = 1}^{N} \end{matrix}$ (except with negligible probability). In case the attacker outputs a valid signature on a new message: $\begin{matrix} (m^{*}, σ^{*}) \end{matrix}$ , it is called an existential forgery.

SUF-CMA (strong unforgeability under chosen message attacks) is a stronger notion than EUF-CMA. It guarantees that for any efficient adversary who has the public key $\begin{matrix} p k \end{matrix}$ of the signer and received an arbitrary number of signatures on messages of its choice: $\begin{matrix} {m_{i}, σ_{i}}_{i = 1}^{N} \end{matrix}$ , it cannot output a new valid signature pair $\begin{matrix} (m^{*}, σ^{*}) \end{matrix}$ , such that $\begin{matrix} (m^{*}, σ^{*}) \notin {m^{i}, σ^{i}}_{i = 1}^{N} \end{matrix}$ (except with negligible probability). Strong unforgeability implies that an adversary cannot only sign new messages, but also cannot find a new signature on an old message. See [Provable_Ed25519] for a real world attack that would have been circumvented with SUF-CMA security over EUF-CMA security.

Binding signature (BS) We say that a signature scheme is binding if no efficient signer can output a tuple $\begin{matrix} [p k, m, m^{'}, σ] \end{matrix}$ , where both $\begin{matrix} (m, σ) \end{matrix}$ and $\begin{matrix} (m^{'}, σ) \end{matrix}$ are valid message signature pairs under the public key $\begin{matrix} p k \end{matrix}$ and $\begin{matrix} m \neq m^{'} \end{matrix}$ (except with negligible probability). A binding signature makes it impossible for the signer to claim later that it has signed a different message, the signature binds the signer to the message.

Strongly Binding signature (SBS) Certain applications may require a signature to not only be binding to the message but also be binding to the public key. We say that a signature scheme is strongly-binding if any efficient signer can not output a tuple $\begin{matrix} [p k, m, p k^{'}, m^{'}, σ] \end{matrix}$ , where $\begin{matrix} (m, σ) \end{matrix}$ is a valid signature for the public key $\begin{matrix} p k \end{matrix}$ and $\begin{matrix} (m^{'}, σ) \end{matrix}$ is a valid signature for the public key $\begin{matrix} p k^{'} \end{matrix}$ and either $\begin{matrix} m^{'} \neq m \end{matrix}$ or $\begin{matrix} p k \neq p k^{'} \end{matrix}$ , or both (except with negligible probability). See [Provable_Ed25519] for real world attacks that would have been circumvented with the SBS property.

Note that the BS and SBS properties are forms of non-repudiation.

As pointed on in [Taming_EdDSAs] flaws in Ed25519 libraries primarily occur on the signature verification side where sometimes edge cases are not properly checked. An Ed25519 signature library that is in conformance with [RFC8032] or [FIPS-186-5], i.e., one that performs all specified validation checks, will have the SUF-CMA property in addition to EUF-CMA.

Reference [Taming_EdDSAs] achieves the BS and SBS properties along with SUF-CMA in their "signature verification algorithm 2" where an additional check is performed against the public key A to make sure that it is not one of eight "small order points". These additional checks incur minimal processing overhead.

Reference [Taming_EdDSAs] included a set of twelve test vectors to test various Ed25519 libraries available at the time of publication. They found that a significant portion missed edge cases and hence did not achieve SUF-CMA (just EUF-CMA) and only two libraries out of sixteen achieved all the security properties. Since the time of publication more Ed25519 libraries have been created and some of the libraries have been updated to include all verification checks. Implementers are recommended to test the Ed25519 library they are using against the test vectors of [Taming_EdDSAs].

Ed25519Signature2020 is an earlier version of a cryptographic suite for the usage of the EdDSA algorithm and Curve25519. While it has been used in production systems, new implementations should use edssa-2022 instead. It has been kept in this specification to provide a stable reference.

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.

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 Multikey header value other than 0xed01 being used in a publicKeyMultibase value.

Example 4: 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 5: 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"
  ]
}

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] formatted date string.

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

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#z6MkjLrk3gKS2nnkeWcmcxiZPGskmesDpuwRBorgHxUXfxnG",
    "proofPurpose": "assertionMethod",
    "proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
  }
}

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.

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 A.2.1.3 Transformation (Ed25519Signature2020), the hashing algorithm is defined in Section A.2.1.4 Hashing (Ed25519Signature2020), and the proof serialization algorithm is defined in Section A.2.1.6 Proof Serialization (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 A.2.1.3 Transformation (Ed25519Signature2020), the hashing algorithm is defined in Section A.2.1.4 Hashing (Ed25519Signature2020), and the proof verification algorithm is defined in Section A.2.1.7 Proof Verification (Ed25519Signature2020).

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

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 A.2.1.6 Proof Serialization (Ed25519Signature2020) or Section A.2.1.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.

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.
Let proofConfigHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) cryptographic hashing algorithm [RFC6234] to the canonicalProofConfig. proofConfigHash will be exactly 32 bytes in size.
Let hashData be the result of joining proofConfigHash (the first hash) with transformedDocumentHash (the second hash).
Return hashData as the hash data.

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.

Let proofConfig be an empty object.
Set proofConfig.type to options.type.
If options.cryptosuite is set, set proofConfig.cryptosuite to its value.
If options.type is not set to Ed25519Signature2020, an INVALID_PROOF_CONFIGURATION error MUST be raised.
Set proofConfig.created to options.created. If the value is not a valid [XMLSCHEMA11-2] datetime, an INVALID_PROOF_DATETIME error MUST be raised.
Set proofConfig.verificationMethod to options.verificationMethod.
Set proofConfig.proofPurpose to options.proofPurpose.
Set proofConfig.@context to unsecuredDocument.@context
Let canonicalProofConfig be the result of applying the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON] to the proofConfig.
Return canonicalProofConfig.

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.
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.
Return proofBytes as the digital proof.

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.
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.
Return verificationResult as the verification result.

This section is non-normative.

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 representation of the public key and the representation of the private key 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/ns/credentials/v2",
        "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33",
    "type": ["VerifiableCredential", "AlumniCredential"],
    "name": "Alumni Credential",
    "description": "A minimum viable example of an Alumni Credential.",
    "issuer": "https://vc.example/issuers/5678",
    "validFrom": "2023-01-01T00:00:00Z",
    "credentialSubject": {
        "id": "did:example:abcdefgh",
        "alumniOf": "The School of Examples"
    }
}

Example 9: Canonical Credential without Proof

<did:example:abcdefgh> <https://www.w3.org/ns/credentials/examples#alumniOf> "The School of Examples" .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/ns/credentials/examples#AlumniCredential> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://schema.org/description> "A minimum viable example of an Alumni Credential." .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://schema.org/name> "Alumni Credential" .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://www.w3.org/2018/credentials#credentialSubject> <did:example:abcdefgh> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://www.w3.org/2018/credentials#issuer> <https://vc.example/issuers/5678> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://www.w3.org/2018/credentials#validFrom> "2023-01-01T00:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

Example 10: Hash of Canonical Credential without Proof (hex)

517744132ae165a5349155bef0bb0cf2258fff99dfe1dbd914b938d775a36017

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": "DataIntegrityProof",
  "cryptosuite": "eddsa-rdfc-2022",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
  "proofPurpose": "assertionMethod",
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ]
}

Example 12: Canonical Proof Options Document

_:c14n0 <http://purl.org/dc/terms/created> "2023-02-24T23:36:38Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://w3id.org/security#DataIntegrityProof> .
_:c14n0 <https://w3id.org/security#cryptosuite> "eddsa-rdfc-2022" .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2> .

Example 13: Hash of Canonical Proof Options Document (hex)

2be46f84ea6a1f078d128fa0f234b4abb76d1ae1efac14d0e62557163a871621

Finally, we concatenate the hash of the proof options followed by the hash of the credential without proof, 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)

2be46f84ea6a1f078d128fa0f234b4abb76d1ae1efac14d0e62557163a871621517744132ae165a5349155bef0bb0cf2258fff99dfe1dbd914b938d775a36017

Example 15: Signature of Combined Hashes (hex)

d4b317e2998933e56318d8f342708f35a130db9a9f8b89eca6f82f5e623ed865c8524868d90d780f3e48c51702068cae19c4091b1df63400e50b3dff2b8d8801

Example 16: Signature of Combined Hashes base58-btc

z5FeZk5LdY7e43JhL1iSnoMHDQFsUims41vu9h4T6ESpdfbGYbvkRb7D53d1f9PbL1dTnFJ42wtdBYjS66HTKFHCt

Assemble the signed credential with the following two steps:

Add the proofValue field with the previously computed base58-btc value to the proof options document.
Set the proof field of the credential to the augmented proof option document.

Example 17: Signed Credential

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33",
  "type": [
    "VerifiableCredential",
    "AlumniCredential"
  ],
  "name": "Alumni Credential",
  "description": "A minimum viable example of an Alumni Credential.",
  "issuer": "https://vc.example/issuers/5678",
  "validFrom": "2023-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:abcdefgh",
    "alumniOf": "The School of Examples"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
    "proofPurpose": "assertionMethod",
    "proofValue": "z5FeZk5LdY7e43JhL1iSnoMHDQFsUims41vu9h4T6ESpdfbGYbvkRb7D53d1f9PbL1dTnFJ42wtdBYjS66HTKFHCt"
  }
}

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 representation of the public key, and the representation of the private key are shown below.

Example 18: 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 19: Credential without Proof

{
    "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33",
    "type": ["VerifiableCredential", "AlumniCredential"],
    "name": "Alumni Credential",
    "description": "A minimum viable example of an Alumni Credential.",
    "issuer": "https://vc.example/issuers/5678",
    "validFrom": "2023-01-01T00:00:00Z",
    "credentialSubject": {
        "id": "did:example:abcdefgh",
        "alumniOf": "The School of Examples"
    }
}

Example 20: Canonical Credential without Proof

{"@context":["https://www.w3.org/ns/credentials/v2","https://www.w3.org/ns/credentials/examples/v2"],"credentialSubject":{"alumniOf":"The School of Examples","id":"did:example:abcdefgh"},"description":"A minimum viable example of an Alumni Credential.","id":"urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33","issuer":"https://vc.example/issuers/5678","name":"Alumni Credential","type":["VerifiableCredential","AlumniCredential"],"validFrom":"2023-01-01T00:00:00Z"}

Example 21: Hash of Canonical Credential without Proof (hex)

59b7cb6251b8991add1ce0bc83107e3db9dbbab5bd2c28f687db1a03abc92f19

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 22: Proof Options Document

{
  "type": "DataIntegrityProof",
  "cryptosuite": "eddsa-jcs-2022",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
  "proofPurpose": "assertionMethod"
}

Example 23: Canonical Proof Options Document

{"created":"2023-02-24T23:36:38Z","cryptosuite":"eddsa-jcs-2022","proofPurpose":"assertionMethod","type":"DataIntegrityProof","verificationMethod":"https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2"}

Example 24: Hash of Canonical Proof Options Document (hex)

56d860737b1bc788da1f5c5a506115278314559a680f37976502c9b3ed1f38f4

Example 25: Combine hashes of Proof Options and Credential (hex)

56d860737b1bc788da1f5c5a506115278314559a680f37976502c9b3ed1f38f459b7cb6251b8991add1ce0bc83107e3db9dbbab5bd2c28f687db1a03abc92f19

Example 26: Signature of Combined Hashes (hex)

7717cab27b6a4d91a472922d0ec071ead8297ce65c47436ca95b98c646d109abbd0c52cab09e83af605e2d896f29a30bbf81cbe0c2089a7193d908c96eaf6106

Example 27: Signature of Combined Hashes base58-btc

z3P6rHMUaWG6e3Ac6xYFht8aEvoVXndgKTtEY8kzWYXzk8dKmAo2GJeZiJw4qoZ2PGp4ugdaHx3oQiLpeFBLDqP2M

Assemble the signed credential with the following two steps:

Add the proofValue field with the previously computed base58-btc value to the proof options document.
Set the proof field of the credential to the augmented proof option document.

Example 28: Signed Credential

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33",
  "type": [
    "VerifiableCredential",
    "AlumniCredential"
  ],
  "name": "Alumni Credential",
  "description": "A minimum viable example of an Alumni Credential.",
  "issuer": "https://vc.example/issuers/5678",
  "validFrom": "2023-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:abcdefgh",
    "alumniOf": "The School of Examples"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3P6rHMUaWG6e3Ac6xYFht8aEvoVXndgKTtEY8kzWYXzk8dKmAo2GJeZiJw4qoZ2PGp4ugdaHx3oQiLpeFBLDqP2M"
  }
}

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 representation of the public key, and the representation of the private key, are shown below.

Example 29: 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 30: Credential without Proof

{
    "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33",
    "type": ["VerifiableCredential", "AlumniCredential"],
    "name": "Alumni Credential",
    "description": "A minimum viable example of an Alumni Credential.",
    "issuer": "https://vc.example/issuers/5678",
    "validFrom": "2023-01-01T00:00:00Z",
    "credentialSubject": {
        "id": "did:example:abcdefgh",
        "alumniOf": "The School of Examples"
    }
}

Example 31: Canonical Credential without Proof

<did:example:abcdefgh> <https://www.w3.org/ns/credentials/examples#alumniOf> "The School of Examples" .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/ns/credentials/examples#AlumniCredential> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://schema.org/description> "A minimum viable example of an Alumni Credential." .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://schema.org/name> "Alumni Credential" .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://www.w3.org/2018/credentials#credentialSubject> <did:example:abcdefgh> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://www.w3.org/2018/credentials#issuer> <https://vc.example/issuers/5678> .
<urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33> <https://www.w3.org/2018/credentials#validFrom> "2023-01-01T00:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

Example 32: Hash of Canonical Credential without Proof (hex)

517744132ae165a5349155bef0bb0cf2258fff99dfe1dbd914b938d775a36017

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 33: Proof Options Document

{
  "type": "Ed25519Signature2020",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
  "proofPurpose": "assertionMethod",
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ]
}

Example 34: Canonical Proof Options Document

_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/ns/credentials/examples#Ed25519Signature2020> .
_:c14n0 <https://www.w3.org/ns/credentials/examples#created> "2023-02-24T23:36:38Z" .
_:c14n0 <https://www.w3.org/ns/credentials/examples#proofPurpose> "assertionMethod" .
_:c14n0 <https://www.w3.org/ns/credentials/examples#verificationMethod> "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2" .

Example 35: Hash of Canonical Proof Options Document (hex)

7094c8ac655f5d26034b866d14cd99eba3d32562408d9c286b64a65fb79e0b2d

Example 36: Combine hashes of Proof Options and Credential (hex)

7094c8ac655f5d26034b866d14cd99eba3d32562408d9c286b64a65fb79e0b2d517744132ae165a5349155bef0bb0cf2258fff99dfe1dbd914b938d775a36017

Example 37: Signature of Combined Hashes (hex)

4527642e1538a97ef38db08fd45cf2d4d04d510231bb83c5991d7a74bcfe9cc5213f956537cc3a7eda1e372e184a9f32285808a0d1ec75db3dc5268727ed0a01

Example 38: Signature of Combined Hashes base58-btc

z2PC6JBDG1otY3PfnxGnvHCuh8tEqPPNpDggvsnzjr2yKxszQg5bJXsQhV1ZUTG6KBNGdvWVzVqFxtLagbdoRUjf6

Assemble the signed credential with the following two steps:

Add the proofValue field with the previously computed base58-btc value to the proof options document.
Set the proof field of the credential to the augmented proof option document.

Example 39: Signed Credential

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "urn:uuid:58172aac-d8ba-11ed-83dd-0b3aef56cc33",
  "type": [
    "VerifiableCredential",
    "AlumniCredential"
  ],
  "name": "Alumni Credential",
  "description": "A minimum viable example of an Alumni Credential.",
  "issuer": "https://vc.example/issuers/5678",
  "validFrom": "2023-01-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:abcdefgh",
    "alumniOf": "The School of Examples"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "https://vc.example/issuers/5678#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
    "proofPurpose": "assertionMethod",
    "proofValue": "z2PC6JBDG1otY3PfnxGnvHCuh8tEqPPNpDggvsnzjr2yKxszQg5bJXsQhV1ZUTG6KBNGdvWVzVqFxtLagbdoRUjf6"
  }
}

Data Integrity EdDSA Cryptosuites v1.0

Achieving Data Integrity using EdDSA with Edwards curves

Abstract

Status of This Document

1. Introduction

1.1 Terminology

1.2 Conformance

2. Data Model

2.1 Verification Methods

2.1.1 Multikey

2.2 Proof Representations

2.2.1 DataIntegrityProof

3. Algorithms

3.1 eddsa-rdfc-2022

3.1.1 Add Proof (eddsa-rdfc-2022)

3.1.2 Verify Proof (eddsa-rdfc-2022)

3.1.3 Transformation (eddsa-rdfc-2022)

3.1.4 Hashing (eddsa-rdfc-2022)

3.1.5 Proof Configuration (eddsa-rdfc-2022)

3.1.6 Proof Serialization (eddsa-rdfc-2022)

3.1.7 Proof Verification (eddsa-rdfc-2022)

3.2 eddsa-jcs-2022

4. Security Considerations

4.1 Security Properties of Ed25519 Implementations

4.1.1 Signature Security Properties

4.1.2 Achieving Ed25519 Security Properties

5. Privacy Considerations

A. The Ed25519Signature2020 Suite

A.1 Data Model

A.1.1 Verification Methods

A.1.1.1 Ed25519VerificationKey2020

A.1.2 Proof representations

A.1.2.1 Ed25519Signature2020

A.2 Algorithms

A.2.1 Ed25519Signature2020

A.2.1.1 Add Proof (Ed25519Signature2020)

A.2.1.2 Verify Proof (Ed25519Signature2020)

A.2.1.3 Transformation (Ed25519Signature2020)

A.2.1.4 Hashing (Ed25519Signature2020)

A.2.1.5 Proof Configuration (Ed25519Signature2020)

A.2.1.6 Proof Serialization (Ed25519Signature2020)

A.2.1.7 Proof Verification (Ed25519Signature2020)

B. Test Vectors

B.1 Representation: eddsa-rdfc-2022

B.2 Representation: eddsa-jcs-2022

B.3 Representation: Ed25519Signature2020

C. Revision History

D. References

D.1 Normative references

D.2 Informative references