+This specification describes Data Integrity cryptographic suites for use when
+creating or verifying a digital signature using the the Ed25519 instantiation
+of the Edwards-Curve Digital Signature Algorithm (EdDSA).
+
+
+
+
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 standards and drafts index.
+
+Comments regarding this specification are welcome at any time.
+Please file issues directly on
+GitHub,
+or send them to
+public-vc-comments@w3.org
+if that is not possible.
+(subscribe,
+archives).
+
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 a 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 that the individual believes contains
+ Essential Claim(s)
+ must disclose the information in accordance with
+ section 6 of the W3C Patent Policy.
+
+
+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 Canonicalization
+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.
+
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, MUST NOT, 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 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.
+
+
+
+
+
+
2. Data Model
+
+
+
+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.
+
+
+
2.1 Verification Methods
+
+
+
+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.
+
+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
+
+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.
+
+
+
+
+
+
+
2.2 Proof Representations
+
+
+
+This section details the proof representation formats that are defined by
+this specification.
+
+
+
2.2.1 DataIntegrityProof
+
+
+
+A proof contains the attributes specified in the
+Proofs section
+of [VC-DATA-INTEGRITY] with the following restrictions.
+
+
+The type property MUST be DataIntegrityProof.
+
+
+The cryptosuite property of the proof MUST be eddsa-rdfc-2022 or eddsa-jcs-2022.
+
+
+The proofValue property of the proof MUST be a detached EdDSA signature
+produced according to [RFC8032], encoded using the base-58-btc header and
+alphabet as described in the
+Multibase section of
+Controlled Identifiers v1.0.
+
+
+
+
+ Example 3: An Ed25519 digital signature expressed as a
+ DataIntegrityProof
+
+The eddsa-rdfc-2022 cryptographic suite takes an input document, canonicalizes
+the document using the 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.
+
+Let transformedData be the result of running the algorithm in Section 3.2.3 Transformation (eddsa-rdfc-2022) with unsecuredDocument,
+proofConfig, and options passed as parameters.
+
+
+Let hashData be the result of running the algorithm in Section
+3.2.4 Hashing (eddsa-rdfc-2022) with transformedData and proofConfig
+passed as a parameters.
+
+Let transformedData be the result of running the algorithm in Section 3.2.3 Transformation (eddsa-rdfc-2022) with unsecuredDocument and
+proofOptions passed as parameters.
+
+
+Let proofConfig be the result of running the algorithm in Section 3.2.5 Proof Configuration (eddsa-rdfc-2022) with unsecuredDocument and
+proofOptions passed as parameters.
+
+
+Let hashData be the result of running the algorithm in Section
+3.2.4 Hashing (eddsa-rdfc-2022) with transformedData and proofConfig
+passed as a parameters.
+
+if verified is true, unsecuredDocument;
+otherwise, Null
+
+
+
+
+
+
+
3.2.3 Transformation (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.2.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,
+an error MUST be raised that SHOULD convey an error type of
+PROOF_TRANSFORMATION_ERROR.
+
+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 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 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 hashData be the result of concatenating proofConfigHash
+(the first hash produced above) followed by transformedDocumentHash
+(the second hash produced above).
+
+
+Return hashData as the hash data.
+
+
+
+
+
+
3.2.5 Proof Configuration (eddsa-rdfc-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 the document
+(unsecuredDocument) and the proof options
+(options). The proof optionsMUST 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 a clone of the options object.
+
+
+If proofConfig.type is not set to DataIntegrityProof and/or
+proofConfig.cryptosuite is not set to eddsa-rdfc-2022, an
+error MUST be raised and SHOULD convey an error type of
+PROOF_GENERATION_ERROR.
+
+
+If proofConfig.created is present and set to a value that is not a
+valid [XMLSCHEMA11-2] datetime, an error MUST be
+raised and SHOULD convey an error type of
+PROOF_GENERATION_ERROR.
+
+
+Set proofConfig.@context to
+unsecuredDocument.@context.
+
+
+Let canonicalProofConfig be the result of applying the
+RDF Dataset Canonicalization Algorithm
+[RDF-CANON] to the proofConfig.
+
+
+Return canonicalProofConfig.
+
+
+
+
+
+
3.2.6 Proof Serialization (eddsa-rdfc-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 optionsMUST 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 (or a signing interface enabling the use of the private key
+bytes) associated with the verification method identified by the
+options.verificationMethod value.
+
+
+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.
+
+
+
+
+
+
3.2.7 Proof Verification (eddsa-rdfc-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.
+
+
+
+
+Let publicKeyBytes be the result of retrieving the
+public key bytes associated with the
+options.verificationMethod value as described in the
+Retrieve
+Verification Method section of the Controlled Identifiers v1.0 specification.
+
+
+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.
+
+
+
+
+
+
+
3.3 eddsa-jcs-2022
+
+
+
+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.
+
+Let transformedData be the result of running the algorithm in Section
+3.3.3 Transformation (eddsa-jcs-2022) with unsecuredDocument
+and options passed as parameters.
+
+
+Let hashData be the result of running the algorithm in Section
+3.3.4 Hashing (eddsa-jcs-2022) with transformedData and proofConfig
+passed as a parameters.
+
Note: Not implementing step 2 can lead to interoperability failures
+Implementers are warned that while step 2 is not strictly necessary when
+generating proofs that will not be included in a proof set or a proof chain,
+that it is not always possible to be certain of where generated proofs will be
+used, or how they might be combined with other proofs at the application layer.
+It is strongly advised to always implement step 2, though some implementers have
+signaled that their software might not always implement step 2.
+
+Check that the securedDocument.@context starts with all values
+contained in the proofOptions.@context in the same order.
+Otherwise, set verified to false and skip to the last step.
+
+
+Set unsecuredDocument.@context equal to
+proofOptions.@context.
+
+
+
+
+Let transformedData be the result of running the algorithm in Section
+3.3.3 Transformation (eddsa-jcs-2022) with unsecuredDocument and
+proofOptions passed as parameters.
+
+Let hashData be the result of running the algorithm in Section
+3.3.4 Hashing (eddsa-jcs-2022) with transformedData and proofConfig passed as
+a parameters.
+
+if verified is true, unsecuredDocument;
+otherwise, Null
+
+
+
+
+
3.3.3 Transformation (eddsa-jcs-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.3.4 Hashing (eddsa-jcs-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-jcs-2022,
+an error MUST be raised that SHOULD convey an error type of
+PROOF_VERIFICATION_ERROR.
+
+
+Let canonicalDocument be the result of applying the
+JSON Canonicalization Scheme [RFC8785] to a JSON serialization of the
+unsecuredDocument.
+
+
+Return canonicalDocument as the transformed data document.
+
+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.
+
+
+
+
+
3.3.5 Proof Configuration (eddsa-jcs-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 optionsMUST 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 a clone of the options object.
+
+
+If proofConfig.type is not set to DataIntegrityProof or
+proofConfig.cryptosuite is not set to eddsa-jcs-2022,
+an error MUST be raised that SHOULD convey an error type of
+PROOF_GENERATION_ERROR.
+
+
+If proofConfig.created is set to a value that is not a
+valid [XMLSCHEMA11-2] datetime, an error MUST be
+raised and SHOULD convey an error type of
+PROOF_GENERATION_ERROR.
+
+
+Let canonicalProofConfig be the result of applying the
+JSON Canonicalization Scheme [RFC8785] to the proofConfig.
+
+
+Return canonicalProofConfig.
+
+
+
+
+
3.3.6 Proof Serialization (eddsa-jcs-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 optionsMUST 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 (or a signing interface enabling the use of the private key
+bytes) associated with the verification method identified by the
+options.verificationMethod value.
+
+
+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.
+
+
+
+
+
3.3.7 Proof Verification (eddsa-jcs-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.
+
+
+
+
+Let publicKeyBytes be the result of retrieving the
+public key bytes associated with the
+options.verificationMethod value as described in the
+Retrieve
+Verification Method section of the Controlled Identifiers v1.0 specification.
+
+
+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 following section describes security considerations that developers
+implementing this specification should be aware of in order to create secure
+software.
+
+
+
4.1 Security Properties of Ed25519 Implementations
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.
+
+
4.1.1 Signature Security Properties
+
+
+Digital signatures might 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
+ of the signer and received an arbitrary number of signatures on
+messages of its choice (in an adaptive manner):
+,
+cannot output a valid signature
+
+for a new message
+
+(except with negligible probability). If the attacker outputs a valid
+signature on a new message:
+,
+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
+
+of the signer and
+received an arbitrary number of signatures on messages of its choice:
+,
+it cannot output a new valid signature pair
+,
+such that
+
+(except with negligible probability). Strong unforgeability implies that an
+adversary not only cannot 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
+,
+where both
+
+and
+
+are valid message signature pairs under the public key
+
+and
+
+(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 cannot output a tuple
+,
+where
+
+is a valid signature for the public key
+
+and
+
+is a valid signature for the public key
+
+and either
+
+or
+,
+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.
+
+
+
4.1.2 Achieving Ed25519 Security Properties
+
+
+As pointed out in [Taming_EdDSAs], flaws in Ed25519 libraries
+primarily occur on the signature verification side, where edge cases
+are sometimes 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].
+
+The following section describes privacy considerations that developers
+implementing this specification should be aware of in order to avoid violating
+privacy assumptions.
+
+Ed25519Signature2020 is an earlier version of a cryptographic suite
+for use of the EdDSA algorithm and Curve25519. While it has
+been used in production systems, new implementations should instead use
+eddsa-rdfc-2022. Ed25519Signature2020 has
+been kept in this specification to provide a stable reference.
+
+
+
A.1 Data Model
+
+
A.1.1 Verification Methods
+
+
A.1.1.1 Ed25519VerificationKey2020
+
+
+
+The key format described in this section is provided to document a legacy
+mechanism that has been deployed to production. The key format described in
+section 2.1.1 Multikey supercedes the one described in this section. New
+applications are strongly urged to use the newer key format.
+
+The controller of the verification method MUST be a URL.
+
+
+
+The publicKeyMultibase value of the verification method MUST start 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 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
+
+The proof format described in this section is provided to document a legacy
+mechanism that has been deployed to production. The DataIntegrityProof formats
+described in section 2.2.1 DataIntegrityProof supercede the one described in
+this section. New applications are strongly urged to use the newer proof format.
+
+
+
+The verificationMethod property of the proof MUST be a URL.
+Dereferencing the verificationMethodMUST 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.
+
+
+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 [CID].
+
+
+
+
+ Example 6: An Ed25519 digital signature expressed as a
+ Ed25519Signature2020
+
+The Ed25519Signature2020 cryptographic suite takes an input document,
+canonicalizes the document using the 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.
+
+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 A.2.1.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.
+
+
+
+
+If options.type is not set to the string
+Ed25519Signature2020,
+an error MUST be raised that SHOULD convey an error type of
+PROOF_TRANSFORMATION_ERROR.
+
+The required inputs to this algorithm are a
+transformed data document (transformedDocument) and
+proof configuration (proofConfig). The
+proof configurationMUST 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).
+
+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 optionsMUST 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 a clone of the options object.
+
+
+If proofConfig.type is not set to Ed25519Signature2020,
+an error MUST be raised and SHOULD convey an error type of
+PROOF_GENERATION_ERROR.
+
+
+If proofConfig.created is present and set to a value that is not a
+valid [XMLSCHEMA11-2] datetime, an error MUST be
+raised and SHOULD convey an error type of
+PROOF_GENERATION_ERROR.
+
+
+Set proofConfig.@context to
+unsecuredDocument.@context
+
+
+Let canonicalProofConfig be the result of applying the
+RDF Dataset Canonicalization algorithm [RDF-CANON] to the proofConfig.
+
+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 optionsMUST 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 (or a signing interface enabling the use of the private key
+bytes) associated with the verification method identified by the
+options.verificationMethod value.
+
+
+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.
+
+
+
+
+
+
A.2.1.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.
+
+
+
+
+Let publicKeyBytes be the result of retrieving the
+public key bytes associated with the
+options.verificationMethod value as described in the
+Retrieve
+Verification Method section of the Controlled Identifiers v1.0 specification.
+
+
+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.
+
+
+
+
+
+
+
+
+
+
B. Test Vectors
This section is non-normative.
+
+
B.1 Representation: eddsa-rdfc-2022
+
+
+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
+
+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.
+
+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)
+
B.2 Enhanced Example for Representation: eddsa-rdfc-2022
+
+
+Here we again go through the steps of creating a credential signed with
+eddsa-rdfc-2022, but with a more complicated input document. The
+representation of the public key and the representation of the private key
+are shown below.
+
+
+
+ Example 18: Private and Public keys for Signature
+
+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: Employment Authorization Credential without Proof
+
+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 25: Combine hashes of Proof Options and Credential (hex)
+
+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
+
+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.
+
{
+ "@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
+
{"@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 32: Hash of Canonical Credential without Proof (hex)
+
+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 36: Combine hashes of Proof Options and Credential (hex)
+
+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 40: Private and Public keys for Signature
+
+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.
+
+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 47: Combine hashes of Proof Options and Credential (hex)
+
+Proof sets and chains are defined in the [VC-DATA-INTEGRITY]. We
+provide test vectors showing the creation of proof sets and chains with the
+eddsa-rdfc-2022 cryptosuite. Multiple signers can be involved in the generation
+of proof sets and chains so multiple public/private key pairs are needed. These
+are shown below.
+
{
+ "@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"
+ }
+}
+
+
B.5.1 Proof Set
+
+
+To demonstrate creating a proof set, we start with a document containing a
+single proof and add another proof to it. The starting document is shown below and
+contains a proof signed with keyPair1.
+
+The options input to
+Section 4.4: Add Proof Set/Chain in [VC-DATA-INTEGRITY]
+is shown below. Note that it does not include a previousProof attribute since
+we are constructing a proof set and not a chain. In addition, we will be using
+keyPair2 for signing.
+
+Per the algorithm of
+Section 4.4: Add Proof Set/Chain in [VC-DATA-INTEGRITY],
+we create an array variable, allProofs, and add the proof from the
+starting document to it. Since there is no previousProof attribute, no
+modification of unsignedDocument is needed prior to computing the signed proof
+in step 6 of
+Section 4.4: Add Proof Set/Chain in
+[VC-DATA-INTEGRITY]. The signed proof configuration is shown below.
+
+The signed proof options above gets appended to the allProofs
+variable, which then gets set as the proof attribute of the unsigned document
+to produce the final signed document as shown below.
+
+This collection of test vectors demonstrates the construction a proof chain. We
+start with a document containing a proof set, i.e., our previous example, and
+then add a new proof to the credential that has a dependency on the existing
+proofs. This example also demonstrates the case where the previousProofs
+attribute is an array. This example uses keyPair3 and the starting document is
+given below.
+
+Per the algorithm of
+Section 4.4: Add Proof Set/Chain in [VC-DATA-INTEGRITY],
+we create an array variable, allProofs, and add the proofs from the
+starting document to it. Since the options contains the previousProof
+attribute, we compute the matchingProofs variable per step 4
+of Section 4.4: Add Proof
+Set/Chain, and we set the
+unsecuredDocument.proof equal to the matchingProofs. This
+produces the document shown below.
+
+
+
+ Example 59: Temporary Unsecured Document for Binding Previous Proofs
+
+In step 6, we use the previous document (unsecured document with previous proofs
+added to it) to compute the proofValue attribute. This gives the signed
+configuration options (proof) shown below:
+
+
+
+ Example 60: Signed Configuration Options (proof)
+
+The signed proof options above gets appended to the allProofs
+variable, which then gets set as the proof attribute of the unsigned document
+to produce the final signed document as shown below.
+
+This collection of test vectors demonstrates construction of an extended proof
+chain. We start with the output of the previous section and add an additional
+proof that is dependent on one of the existing proofs. This example uses
+keyPair4, and the starting document is given below.
+
+
+
+ Example 62: Starting Document for Extended Proof Chain
+
+The options input to
+Section 4.4: Add Proof Set/Chain in [VC-DATA-INTEGRITY]
+is shown below. Note that it includes a previousProof attribute since we are
+constructing a proof chain, however this time it is a single value.
+
+Per the algorithm of
+Section 4.4: Add Proof Set/Chain in [VC-DATA-INTEGRITY],
+we create an array variable, allProofs, and add the proofs from the
+starting document to it. Since the options contains the previousProof
+attribute, we compute the matchingProofs variable per step 4
+of Section 4.4: Add Proof
+Set/Chain, and we set the
+unsecuredDocument.proof equal to the matchingProofs. This
+produces the document shown below.
+
+
+
+ Example 64: Temporary Unsecured Document for Binding Previous Proofs (Extended Chain)
+
+In step 6, we use the previous document (unsecured document with previous proofs
+added to it) to compute the proofValue attribute. This gives the signed
+configuration options (proof) shown below:
+
+
+
+ Example 65: Signed Configuration Options (Extended)
+
+The signed proof options above gets appended to the allProofs
+variable, which then gets set as the proof attribute of the unsigned document
+to produce the final signed document as shown below.
+
+Added support for JSON Canonicalization Scheme in addition to RDF Dataset
+Canonicalization.
+
+
+Added test vectors for rdfc and jcs cryptosuites.
+
+
+Deprecated and moved Ed25519Signature2020 to appendix.
+
+
+Add Security Considerations for proper implementation of EdDSA.
+
+
+Move normative definition of Multikey to the Data Integrity specification.
+
+
+Add RDF-CANON mitigation for Dataset poisoning.
+
+
+Revise cryptographic suite names and align with other cryptosuites.
+
+
+Add secretKeyMultibase definition.
+
+
+
+
+
+
D. Acknowledgements
This section is non-normative.
+
+
+
+Work on this specification has been supported by the Rebooting the Web of Trust
+community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles,
+Brian Weller, Betty Dhamers, Kaliya Young, Manu Sporny, Drummond Reed, Joe
+Andrieu, Heather Vescent, Kim Hamilton Duffy, Samantha Chase, Andrew Hughes,
+Erica Connell, Shigeya Suzuki, Zaïda Rivai, Will Abramson, and Eric Schuh. The
+participants in the Internet Identity Workshop, facilitated by Phil Windley,
+Kaliya Young, Doc Searls, and Heidi Nobantu Saul, also supported the refinement
+of this work through numerous working sessions designed to educate about, debate
+on, and improve this specification.
+
+
+
+The Working Group also thanks our Working Group Chair Brent Zundel, and ex-chair
+Kristina Yasuda, as well as our W3C Staff Contact, Ivan Herman, for their expert
+management and steady guidance of the group through the W3C standardization
+cycle. We also thank the Chairs of the W3C Credentials Community Group,
+Christopher Allen, Joe Andrieu, Kim Hamilton Duffy, Heather Vescent, Wayne
+Chang, Mike Prorock, Harrison Tang, Kimberly Wilson Linson, and Will Abramson,
+who oversaw the incubation of this work.
+
+
+
+Portions of the work on this specification have been funded by the United States
+Department of Homeland Security's Science and Technology Directorate under
+contracts 70RSAT20T00000029, 70RSAT21T00000016, 70RSAT23T00000005,
+70RSAT20T00000010/P00001, 70RSAT20T00000029, 70RSAT21T00000016/P00001,
+70RSAT23T00000005, 70RSAT23C00000030, 70RSAT23R00000006, 70RSAT24T00000011, and
+the National Science Foundation through NSF 22-572. The content of this
+specification does not necessarily reflect the position or the policy of the
+U.S. Government and no official endorsement should be inferred.
+
+
+
+The Working Group would like to thank the following individuals for reviewing
+and providing feedback on and implementations of the specification
+(in alphabetical order by last name):
+