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 technical reports index at
https://www.w3.org/TR/.
The Working Group is actively seeking implementation feedback for this
specification. In order to exit the Candidate Recommendation phase, the
Working Group has set the requirement of at least two independent
implementations for each mandatory feature in the specification. For details
on the conformance testing process, see the test suites listed in the
implementation report.
(Feature at Risk) Issue 1: Features with less than two independent implementations
Any feature with less than two independent implementations in the
EdDSA Cryptosuite Implementation Report is an "at risk" feature and might be
removed before the transition to W3C Proposed Recommendation.
Publication as a Candidate Recommendation does not
imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates
changes from the previous Candidate Recommendation that the Working Group
intends to include in a subsequent Candidate Recommendation Snapshot.
This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than work in progress.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
This 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.
The publicKeyMultibase value of the verification method MUST start with the
base-58-btc prefix (z), as defined in the
Multibase section of
Controller Documents 1.0. A Multibase-encoded Ed25519 256-bit public key value
follows, as defined in the
Multikey section of
Controller Documents 1.0. 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
The secretKeyMultibase value of the verification method MUST start with the
base-58-btc prefix (z), as defined in the
Multibase section of
Controller Documents 1.0. A Multibase-encoded Ed25519 256-bit secret key value
follows, as defined in the
Multikey section of
Controller Documents 1.0. Any other encoding MUST NOT be allowed.
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.
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
Controller Documents 1.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 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 associated with the
options.verificationMethod value as described in the
Data Integrity [VC-DATA-INTEGRITY] specification,
Section 4.1: Processing Model.
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 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.
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 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 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 [VC-DATA-INTEGRITY].
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 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 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.
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)
{
"@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": "did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
"proofPurpose": "assertionMethod",
"proofValue": "z2YwC8z3ap7yx1nZYCg4L3j3ApHsF8kgPdSb5xoS1VR7vPG3F561B52hYnQF9iseabecm3ijx4K1FBTQsCZahKZme"
}
}
B.2 Representation: eddsa-jcs-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.
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"],"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)
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)
{
"@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": "did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
"proofPurpose": "assertionMethod",
"proofValue": "zboydVv31kj6jP37GMBZwYyjbvrqr9MWeY9NCEfYUwLcKwkdqAcB44dqEcqaMi8mfdvT2Vbnvdrv6XRaYzgpuPWn"
}
}
B.3 Representation: Ed25519Signature2020
The signer needs to generate a private/public key pair with the private key used
for signing and the public key made available for verification. The
representation of the public key, and the representation of the private key,
are shown below.
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 36: Combine hashes of Proof Options and Credential (hex)
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"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": "did:key:z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2#z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2",
"proofPurpose": "assertionMethod",
"proofValue": "z57Mm1vboMtZiCyJ4aReZsv8co4Re64Y8GEjL1ZARzMbXZgkARFLqFs1P345NpPGG2hgCrS4nNdvJhpwnrNyG3kEF"
}
}
B.4 Proof Sets and Chains
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.4.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.
{
"@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",
"id": "urn:uuid:26329423-bec9-4b2e-88cb-a7c7d9dc4544",
"cryptosuite": "eddsa-rdfc-2022",
"created": "2023-02-24T23:36:38Z",
"verificationMethod": "did:key:z6MktgKTsu1QhX6QPbyqG6geXdw6FQCZBPq7uQpieWbiQiG7#z6MktgKTsu1QhX6QPbyqG6geXdw6FQCZBPq7uQpieWbiQiG7",
"proofPurpose": "assertionMethod",
"proofValue": "z66vWyqwAghu52WbpRkCwFRTu6Msn92ArtjpJ3gGMSVoU5RADwBfszoDt1QWY8owqLPz4nTj7hAwV7xFti1p93zdr"
}
}
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 48: 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:
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 51: 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 53: Temporary Unsecured Document for Binding Previous Proofs (Extended Chain)
{
"@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",
"id": "urn:uuid:d94f792a-c546-4d06-b38a-da070ab56c23",
"cryptosuite": "eddsa-rdfc-2022",
"created": "2023-02-26T22:06:38Z",
"verificationMethod": "did:key:z6MkmEq87wkHCYnWnNZkigeDMGTN7oUw1upkhzd77KuXERS1#z6MkmEq87wkHCYnWnNZkigeDMGTN7oUw1upkhzd77KuXERS1",
"proofPurpose": "assertionMethod",
"previousProof": [
"urn:uuid:26329423-bec9-4b2e-88cb-a7c7d9dc4544",
"urn:uuid:8cc9022b-6b14-4cf3-8571-74972c5feb54"
],
"proofValue": "zWaPeEvBAkhQpNQj8pknuvg5STcKnt3cvM9t4kAYeJETFjvVMSXEEjadC4uxC9fKCn6JHbjt6fj2fhoaVNynBm6J"
}
]
}
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 54: 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, and Zaïda Rivai. 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 Chair, Brent Zundel, our 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
process.
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, 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 the specification (in alphabetical order):
Will Abramson,
Mahmoud Alkhraishi,
Christopher Allen,
Joe Andrieu,
Bohdan Andriyiv,
Anthony,
George Aristy,
Hadley Beeman,
Greg Bernstein,
Bob420,
Sarven Capadisli,
Melvin Carvalho,
David Chadwick,
Matt Collier,
Gabe Cohen,
Sebastian Crane,
Kyle Den Hartog,
Veikko Eeva,
Eric Elliott,
Raphael Flechtner,
Julien Fraichot,
Benjamin Goering,
Kim Hamilton Duffy,
Joseph Heenan,
Helge,
Ivan Herman,
Michael Herman,
Anil John,
Andrew Jones,
Michael B. Jones,
Rieks Joosten,
Gregory K,
Gregg Kellogg,
Filip Kolarik,
David I. Lehn,
Charles E. Lehner,
Christine Lemmer-Webber,
Eric Lim,
Dave Longley,
Tobias Looker,
Jer Miller,
nightpool,
Luis Osta,
Nate Otto,
George J. Padayatti,
Addison Phillips,
Mike Prorock,
Brian Richter,
Anders Rundgren,
Eugeniu Rusu,
Markus Sabadello,
silverpill,
Wesley Smith,
Manu Sporny,
Patrick St-Louis,
Orie Steele,
Henry Story,
Oliver Terbu,
Ted Thibodeau Jr,
John Toohey,
Bert Van Nuffelen,
Mike Varley,
Snorre Lothar von Gohren Edwin,
Jeffrey Yasskin,
Kristina Yasuda,
Benjamin Young,
Dmitri Zagidulin,
and
Brent Zundel.