Data Integrity ECDSA Cryptosuites v1.0

Achieving Data Integrity using ECDSA with NIST-compliant curves

W3C Candidate Recommendation Draft

More details about this document
This version:
https://www.w3.org/TR/2024/CRD-vc-di-ecdsa-20241117/
Latest published version:
https://www.w3.org/TR/vc-di-ecdsa/
Latest editor's draft:
https://w3c.github.io/vc-di-ecdsa/
History:
https://www.w3.org/standards/history/vc-di-ecdsa/
Commit history
Implementation report:
https://w3c.github.io/vc-di-ecdsa-test-suite/
Editors:
Manu Sporny (Digital Bazaar)
Marty Reed (RANDA Solutions)
Greg Bernstein (Invited Expert)
Sebastian Crane (Invited Expert)
Authors:
Dave Longley (Digital Bazaar)
Manu Sporny (Digital Bazaar)
Feedback:
GitHub w3c/vc-di-ecdsa (pull requests, new issue, open issues)
Related Specifications
The Verifiable Credentials Data Model v2.0
Verifiable Credential Data Integrity v1.0
Controller Documents v1.0
Data Integrity EdDSA Cryptosuites v1.0
Data Integrity BBS Cryptosuites v1.0

Abstract

This specification describes Data Integrity cryptosuites for use when generating a digital signature using the Elliptic Curve Digital Signature Algorithm (ECDSA).

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 ECDSA Cryptosuite Implementation Report is an "at risk" feature and might be removed before the transition to W3C Proposed Recommendation.

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

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 document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

This specification defines a cryptographic suite for the purpose of creating, and verifying proofs for ECDSA signatures in conformance with the Data Integrity [VC-DATA-INTEGRITY] specification. ECDSA signatures are specified in [FIPS-186-5] with elliptic curves P-256 and P-384 specified in [NIST-SP-800-186]. [FIPS-186-5] includes the deterministic ECDSA algorithm which is also specified in [RFC6979].

Note

The elliptic curves P-256 and P-384 of [NIST-SP-800-186] are respectively referred to as secp256r1 and secp384r1 in [SECG2]. This notation is sometimes also used by ECDSA software libraries.

Developers are cautioned to not confuse secp256r1 terms with secp256k1 terms; the latter are from a third, different, elliptic curve, that is not used by this specification. ECDSA software libraries might not implement all of these curves, so developers need to take care when choosing an ECDSA software library for their implementation.

This specification uses either the RDF Dataset Canonicalization Algorithm [RDF-CANON] or the JSON Canonicalization Scheme [RFC8785] to transform the input document into its canonical form. It uses one of two mechanisms to digest and sign: SHA-256 [RFC6234] as the message digest algorithm and ECDSA with Curve P-256 as the signature algorithm, or SHA-384 [RFC6234] as the message digest algorithm and ECDSA with Curve P-384 as the signature algorithm.

1.1 Terminology

Terminology used throughout this document is defined in the Terminology section of the Verifiable Credential Data Integrity 1.0 specification.

1.2 Conformance

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

The key words MAY, MUST, 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. Such parts need to be removed if implementers want 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

These verification methods are used to verify Data Integrity Proofs [VC-DATA-INTEGRITY] produced using Elliptic Curve cryptographic key material that is compliant with [FIPS-186-5]. The encoding formats for these key types are provided in this section. Lossless cryptographic key transformation processes that result in equivalent cryptographic key material MAY be used during the processing of digital signatures.

2.1.1 Multikey

The Multikey format, defined in Controller Documents 1.0, is used to express public keys for the cryptographic suites defined in this specification.

The publicKeyMultibase property represents a Multibase-encoded Multikey expression of a P-256 or P-384 public key.

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 ECDSA 256-bit public key value or an ECDSA 384-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 in the event of a Multicodec value other than 0x1200 or 0x1201 being used in a publicKeyMultibase value.

Example 1: An P-256 public key encoded as a Multikey
{
  "id": "https://example.com/issuer/123#key-0",
  "type": "Multikey",
  "controller": "https://example.com/issuer/123",
  "publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv"
}
Example 2: An P-384 public key encoded as a Multikey
{
  "id": "https://example.com/issuer/123#key-0",
  "type": "Multikey",
  "controller": "https://example.com/issuer/123",
  "publicKeyMultibase": "z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJ
    Uz2sG9FE42shbn2xkZJh54"
}
Example 3: Two public keys (P-256 and P-384) encoded as Multikeys in a controller document
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "https://example.com/issuer/123#key-1",
    "type": "Multikey",
    "controller": "https://example.com/issuer/123",
    "publicKeyMultibase": "zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv"
  }, {
    "id": "https://example.com/issuer/123#key-2",
    "type": "Multikey",
    "controller": "https://example.com/issuer/123",
    "publicKeyMultibase": "z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJ
      Uz2sG9FE42shbn2xkZJh54"
  }],
  "authentication": [
    "did:example:123#key-1"
  ],
  "assertionMethod": [
    "did:example:123#key-2"
  ],
  "capabilityDelegation": [
    "did:example:123#key-2"
  ],
  "capabilityInvocation": [
    "did:example:123#key-2"
  ]
}

The secretKeyMultibase property represents a Multibase-encoded Multikey expression of a P-256 or P-384 secret key (also sometimes referred to as a private key).

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 ECDSA 256-bit secret key value or an ECDSA 384-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 as 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 MUST be ecdsa-rdfc-2019, ecdsa-jcs-2019, or ecdsa-sd-2023.

The value of the proofValue property is produced according to the cryptosuite type and is specified in either Section 3.2.1 Create Proof (ecdsa-rdfc-2019), or Section 3.3.1 Create Proof (ecdsa-jcs-2019), or Section 3.6.1 Create Base Proof (ecdsa-sd-2023), or Section 3.6.6 Add Derived Proof (ecdsa-sd-2023).

Example 4: An ECDSA P-256 digital signature expressed as a DataIntegrityProof
{
  "@context": [
    {"myWebsite": "https://vocabulary.example/myWebsite"},
    "https://www.w3.org/ns/credentials/v2"
  ],
  "myWebsite": "https://hello.world.example/",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-rdfc-2019",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "https://vc.example/issuers/5678#zDnaepBuvsQ8cpsWrVKw8
      fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "z2iAR3F2Sk3mWfYyrinKzSQpSbvfxnz9kkv7roxxumB5RZDP9JUw5QAXuchUd
      huiwE18hyyZTjiEreKmhH3oj9Q8"
  }
}

3. Algorithms

The following section describes multiple Data Integrity cryptographic suites that utilize the Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5]. When generating ECDSA signatures, the signature value MUST be expressed according to section 7 of [RFC4754] (sometimes referred to as the IEEE P1363 format) and encoded according to the specific cryptosuite proof generation algorithm. All ECDSA signatures SHOULD use the deterministic variant of the algorithm defined in [FIPS-186-5].

Implementations SHOULD fetch and cache verification method information as early as possible when adding or verifying proofs. Parameters passed to functions in this section use information from the verification method — such as the public key size — to determine function parameters — such as the cryptographic hashing algorithm.

When the RDF Dataset Canonicalization Algorithm (RDFC-1.0) [RDF-CANON] is used with ECDSA algorithms, the cryptographic hashing function used by RDFC-1.0 is chosen based on the size of the associated public key. For P-256 keys, the default hashing function, SHA-2 with 256 bits of output, MUST be used. For P-384 keys, SHA-2 with 384-bits of output MUST be used, specified via the RDFC-1.0 implementation-specific parameter.

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

3.1 Instantiate Cryptosuite

This algorithm is used to configure a cryptographic suite to be used by the Add Proof and Verify Proof functions in Verifiable Credential Data Integrity 1.0. The algorithm takes an options object (map options) as input and returns a cryptosuite instance (struct cryptosuite).

  1. Initialize cryptosuite to an empty struct.
  2. If options.type does not equal DataIntegrityProof, return cryptosuite.
  3. If options.cryptosuite is ecdsa-rdfc-2019 then:
    1. Set cryptosuite.createProof to the algorithm in Section 3.2.1 Create Proof (ecdsa-rdfc-2019).
    2. Set cryptosuite.verifyProof to the algorithm in Section 3.2.7 Proof Verification (ecdsa-rdfc-2019).
  4. If options.cryptosuite is ecdsa-jcs-2019 then:
    1. Set cryptosuite.createProof to the algorithm in Section 3.3.1 Create Proof (ecdsa-jcs-2019).
    2. Set cryptosuite.verifyProof to the algorithm in Section 3.3.7 Proof Verification (ecdsa-jcs-2019).
  5. If options.cryptosuite is ecdsa-sd-2023 then:
    1. Set cryptosuite.createProof to the algorithm in Section 3.6.1 Create Base Proof (ecdsa-sd-2023).
    2. Set cryptosuite.verifyProof to the algorithm in Section 3.6.7 Verify Derived Proof (ecdsa-sd-2023).
  6. Return cryptosuite.

3.2 ecdsa-rdfc-2019

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

3.2.1 Create Proof (ecdsa-rdfc-2019)

The following algorithm specifies how to create a data integrity proof given an unsecured data document. Required inputs are an unsecured data document (map unsecuredDocument), and a set of proof options (map options). A data integrity proof (map), or an error, is produced as output.

  1. Let proof be a clone of the proof options, options.
  2. Let proofConfig be the result of running the algorithm in Section 3.2.5 Proof Configuration (ecdsa-rdfc-2019) with options passed as a parameter.
  3. Let transformedData be the result of running the algorithm in Section 3.2.3 Transformation (ecdsa-rdfc-2019) with unsecuredDocument, proofConfig, and options passed as parameters.
  4. Let hashData be the result of running the algorithm in Section 3.2.4 Hashing (ecdsa-rdfc-2019) with transformedData and proofConfig passed as a parameters.
  5. Let proofBytes be the result of running the algorithm in Section 3.2.6 Proof Serialization (ecdsa-rdfc-2019) with hashData and options passed as parameters.
  6. Let proof.proofValue be a base58-btc-encoded Multibase value of the proofBytes.
  7. Return proof as the data integrity proof.

3.2.2 Verify Proof (ecdsa-rdfc-2019)

The following algorithm specifies how to verify a data integrity proof given an secured data document. Required inputs are an secured data document (map securedDocument). This algorithm returns a verification result, which is a struct whose items are:

verified
true or false
verifiedDocument
Null, if verified is false; otherwise, an unsecured data document
  1. Let unsecuredDocument be a copy of securedDocument with the proof value removed.
  2. Let proofConfig be a copy of securedDocument.proof with proofValue removed.
  3. Let proofBytes be the Multibase decoded base58-btc value in securedDocument.proof.proofValue.
  4. Let transformedData be the result of running the algorithm in Section 3.2.3 Transformation (ecdsa-rdfc-2019) with unsecuredDocument and proofConfig passed as parameters.
  5. Let hashData be the result of running the algorithm in Section 3.2.4 Hashing (ecdsa-rdfc-2019) with transformedData and proofConfig passed as a parameters.
  6. Let verified be the result of running the algorithm in Section 3.2.7 Proof Verification (ecdsa-rdfc-2019) algorithm on hashData, proofBytes, and proofConfig.
  7. Return a verification result with items:
    verified
    verified
    verifiedDocument
    unsecuredDocument if verified is true, otherwise Null

3.2.3 Transformation (ecdsa-rdfc-2019)

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 (ecdsa-rdfc-2019).

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

  1. If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string ecdsa-rdfc-2019, an error MUST be raised and SHOULD convey an error type of PROOF_TRANSFORMATION_ERROR.
  2. Let canonicalDocument be the result of converting unsecuredDocument to JSON-LD expanded form and then to RDF statements, applying the RDF Dataset Canonicalization Algorithm [RDF-CANON] to the result, and then serializing the result to a serialized canonical form [RDF-CANON]. For canonicalization, one is expected to use a hash algorithm that has an appropriate security level for the curve used; see further details.
  3. Return canonicalDocument as the transformed data document.

3.2.4 Hashing (ecdsa-rdfc-2019)

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.2.6 Proof Serialization (ecdsa-rdfc-2019) or Section 3.2.7 Proof Verification (ecdsa-rdfc-2019). One must use the hash algorithm appropriate in security level to the curve used, i.e., for curve P-256 one uses SHA-256 and for curve P-384 one uses SHA-384.

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.

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

3.2.5 Proof Configuration (ecdsa-rdfc-2019)

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

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

  1. Let proofConfig be a clone of the options object.
  2. If proofConfig.type is not set to DataIntegrityProof and/or proofConfig.cryptosuite is not set to ecdsa-rdfc-2019, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR.
  3. If proofConfig.created is set and if the value is not a valid [XMLSCHEMA11-2] datetime, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR.
  4. Set proofConfig.@context to unsecuredDocument.@context.
  5. Let canonicalProofConfig be the result of applying the RDF Dataset Canonicalization [RDF-CANON] to the proofConfig.
  6. Return canonicalProofConfig.

3.2.6 Proof Serialization (ecdsa-rdfc-2019)

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

  1. Let privateKeyBytes be the result of retrieving the private key bytes (or a signing interface enabling the use of the private key bytes) associated with the verification method identified by the options.verificationMethod value.
  2. Let proofBytes be the result of applying the Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with hashData as the data to be signed using the private key specified by privateKeyBytes. proofBytes will be exactly 64 bytes in size for a P-256 key, and 96 bytes in size for a P-384 key.
  3. Return proofBytes as the digital proof.

3.2.7 Proof Verification (ecdsa-rdfc-2019)

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

  1. Let publicKeyBytes be the result of retrieving the public key bytes associated with the options.verificationMethod value as described in the Controller Documents 1.0 specification, Section: Retrieve Verification Method.
  2. Let verificationResult be the result of applying the verification algorithm Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with hashData as the data to be verified against the proofBytes using the public key specified by publicKeyBytes.
  3. Return verificationResult as the verification result.

3.3 ecdsa-jcs-2019

The ecdsa-jcs-2019 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 in this section also include the verification of such a data integrity proof.

3.3.1 Create Proof (ecdsa-jcs-2019)

The following algorithm specifies how to create a data integrity proof given an unsecured data document. Required inputs are an unsecured data document (map unsecuredDocument), and a set of proof options (map options). A data integrity proof (map), or an error, is produced as output.

  1. Let proof be a clone of the proof options, options.
  2. If unsecuredDocument.@context is present, set proof.@context to unsecuredDocument.@context.
  3. Let proofConfig be the result of running the algorithm in Section 3.3.5 Proof Configuration (ecdsa-jcs-2019) with proof passed as the proof options parameter.
  4. Let transformedData be the result of running the algorithm in Section 3.3.3 Transformation (ecdsa-jcs-2019) with unsecuredDocument and options passed as parameters.
  5. Let hashData be the result of running the algorithm in Section 3.3.4 Hashing (ecdsa-jcs-2019) with transformedData and proofConfig passed as a parameters.
  6. Let proofBytes be the result of running the algorithm in Section 3.3.6 Proof Serialization (ecdsa-jcs-2019) with hashData and options passed as parameters.
  7. Let proof.proofValue be a base58-btc-encoded Multibase value of the proofBytes.
  8. Return proof as the data integrity proof.

3.3.2 Verify Proof (ecdsa-jcs-2019)

The following algorithm specifies how to verify a data integrity proof given an secured data document. Required inputs are an secured data document (map securedDocument). This algorithm returns a verification result, which is a struct whose items are:

verified
true or false
verifiedDocument
if verified is true, an unsecured data document; otherwise Null
  1. Let unsecuredDocument be a copy of securedDocument with the proof value removed.
  2. Let proofOptions be the result of a copy of securedDocument.proof with proofValue removed.
  3. Let proofBytes be the Multibase decoded base58-btc value in securedDocument.proof.proofValue.
  4. If proofOptions.@context exists:
    1. 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.
    2. Set unsecuredDocument.@context equal to proofOptions.@context.
  5. Let transformedData be the result of running the algorithm in Section 3.3.3 Transformation (ecdsa-jcs-2019) with unsecuredDocument and proofOptions passed as parameters.
  6. Let proofConfig be the result of running the algorithm in Section 3.3.5 Proof Configuration (ecdsa-jcs-2019) with proofOptions passed as the parameter.
  7. Let hashData be the result of running the algorithm in Section 3.3.4 Hashing (ecdsa-jcs-2019) with transformedData and proofConfig passed as a parameters.
  8. Let verified be the result of running the algorithm in Section 3.3.7 Proof Verification (ecdsa-jcs-2019) on hashData, proofBytes, and proofConfig.
  9. Return a verification result with items:
    verified
    verified
    verifiedDocument
    if verified is true, unsecuredDocument; otherwise, Null

3.3.3 Transformation (ecdsa-jcs-2019)

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 (ecdsa-jcs-2019).

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

  1. If options.type is not set to the string DataIntegrityProof or options.cryptosuite is not set to the string ecdsa-jcs-2019, an error MUST be raised and SHOULD convey an error type of PROOF_TRANSFORMATION_ERROR.
  2. Let canonicalDocument be the result of applying the JSON Canonicalization Scheme [RFC8785] to a JSON serialization of the unsecuredDocument.
  3. Return canonicalDocument as the transformed data document.

3.3.4 Hashing (ecdsa-jcs-2019)

The following algorithm specifies how to cryptographically hash a transformed data document and proof configuration into cryptographic hash data that is ready to be provided as input to the algorithms in Section 3.3.6 Proof Serialization (ecdsa-jcs-2019) or Section 3.3.7 Proof Verification (ecdsa-jcs-2019). One must use the hash algorithm appropriate in security level to the curve used, i.e., for curve P-256 one uses SHA-256, and for curve P-384 one uses SHA-384.

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

  1. Let transformedDocumentHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) or SHA-384 (SHA-2 with 384-bit output) cryptographic hashing algorithm [RFC6234] to the respective curve P-256 or curve P-384 transformedDocument. Respective transformedDocumentHash will be exactly 32 or 48 bytes in size.
  2. Let proofConfigHash be the result of applying the SHA-256 (SHA-2 with 256-bit output) or SHA-384 (SHA-2 with 384-bit output) cryptographic hashing algorithm [RFC6234] to the respective curve P-256 or curve P-384 canonicalProofConfig. Respective proofConfigHash will be exactly 32 or 48 bytes in size.
  3. Let hashData be the result of concatenating proofConfigHash (the first hash) followed by transformedDocumentHash (the second hash).
  4. Return hashData as the hash data.

3.3.5 Proof Configuration (ecdsa-jcs-2019)

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 proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MUST contain a cryptosuite identifier (cryptosuite). A proof configuration object is produced as output.

  1. Let proofConfig be a clone of the options object.
  2. If proofConfig.type is not set to DataIntegrityProof and/or proofConfig.cryptosuite is not set to ecdsa-jcs-2019, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR.
  3. If proofConfig.created is set and if the value is not a valid [XMLSCHEMA11-2] datetime, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR.
  4. Let canonicalProofConfig be the result of applying the JSON Canonicalization Scheme [RFC8785] to the proofConfig.
  5. Return canonicalProofConfig.

3.3.6 Proof Serialization (ecdsa-jcs-2019)

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

  1. Let privateKeyBytes be the result of retrieving the private key bytes associated with the options.verificationMethod value.
  2. Let proofBytes be the result of applying the Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with hashData as the data to be signed using the private key specified by privateKeyBytes. proofBytes will be exactly 64 bytes in size for a P-256 key, and 96 bytes in size for a P-384 key.
  3. Return proofBytes as the digital proof.

3.3.7 Proof Verification (ecdsa-jcs-2019)

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

  1. Let publicKeyBytes be the result of retrieving the public key bytes associated with the options.verificationMethod value as described in the Controller Documents 1.0 specification, Section: Retrieve Verification Method.
  2. Let verificationResult be the result of applying the verification algorithm, Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with hashData as the data to be verified against the proofBytes using the public key specified by publicKeyBytes.
  3. Return verificationResult as the verification result.

3.4 Selective Disclosure Functions

Issue 2: (AT RISK) Pending implementation feedback and security reviews.

The Working Group is seeking implementer feedback on these generalized selective disclosure functions as well as horizonal security review on the features from parties at W3C and IETF. Those reviews might result in significant changes to these functions, migration of these functions to the core Data Integrity specification (for use by other cryptographic suites), or the removal of the algorithm from the specification during the Candidate Recommendation phase.

The following section contains a set of functions that are used throughout cryptographic suites that perform selective disclosure.

3.4.1 labelReplacementCanonicalizeNQuads

The following algorithm canonicalizes an array of N-Quad [N-QUADS] strings and replaces any blank node identifiers in the canonicalized result using a label map factory function, labelMapFactoryFunction. The required inputs are an array of N-Quad strings (nquads), and a label map factory function (labelMapFactoryFunction). Any custom options can also be passed. An N-Quads representation of the canonicalNQuads as an array of N-Quad strings, with the replaced blank node labels, and a map from the old blank node IDs to the new blank node IDs, labelMap, is produced as output.

  1. Run the RDF Dataset Canonicalization Algorithm [RDF-CANON] on the joined nquads, passing any custom options, and as output, get the canonicalized dataset, which includes a canonical bnode identifier map, canonicalIdMap.
  2. Pass canonicalIdMap to labelMapFactoryFunction to produce a new bnode identifier map, labelMap.
  3. Use the canonicalized dataset and labelMap to produce the canonical N-Quads representation as an array of N-Quad strings, canonicalNQuads.
  4. Return an object containing labelMap and canonicalNQuads.

3.4.2 labelReplacementCanonicalizeJsonLd

The following algorithm canonicalizes a JSON-LD document and replaces any blank node identifiers in the canonicalized result using a label map factory function, labelMapFactoryFunction. The required inputs are a JSON-LD document (document) and a label map factory function (labelMapFactoryFunction). Additional custom options (such as a document loader) can also be passed. An N-Quads representation of the canonicalNQuads as an array of N-Quad strings, with the replaced blank node labels, and a map from the old blank node IDs to the new blank node IDs, labelMap, is produced as output.

  1. Deserialize the JSON-LD document to RDF, rdf, using the Deserialize JSON-LD to RDF algorithm, passing any custom options (such as a document loader).
  2. Serialize rdf to an array of N-Quad strings, nquads.
  3. Return the result of calling the algorithm in Section 3.4.1 labelReplacementCanonicalizeNQuads, passing nquads, labelMapFactoryFunction, and any custom options.

3.4.3 createLabelMapFunction

The following algorithm creates a label map factory function that uses an input label map to replace canonical blank node identifiers with another value. The required input is a label map, labelMap. A function, labelMapFactoryFunction, is produced as output.

  1. Create a function, labelMapFactoryFunction, with one required input (a canonical node identifier map, canonicalIdMap), that will return a blank node identifier map, bnodeIdMap, as output. Set the function's implementation to:
    1. Generate a new empty bnode identifier map, bnodeIdMap.
    2. For each map entry, entry, in canonicalIdMap:
      1. Use the canonical identifier from the value in entry as a key in labelMap to get the new label, newLabel.
      2. Add a new entry, newEntry, to bnodeIdMap using the key from entry and newLabel as the value.
    3. Return bnodeIdMap.
  2. Return labelMapFactoryFunction.

3.4.4 createHmacIdLabelMapFunction

The following algorithm creates a label map factory function that uses an HMAC to replace canonical blank node identifiers with their encoded HMAC digests. The required input is an HMAC (previously initialized with a secret key), HMAC. A function, labelMapFactoryFunction, is produced as output.

  1. Create a function, labelMapFactoryFunction, with one required input (a canonical node identifier map, canonicalIdMap), that will return a blank node identifier map, bnodeIdMap, as output. Set the function's implementation to:
    1. Generate a new empty bnode identifier map, bnodeIdMap.
    2. For each map entry, entry, in canonicalIdMap:
      1. HMAC the canonical identifier from the value in entry to get an HMAC digest, digest.
      2. Generate a new string value, b64urlDigest, and initialize it to "u" followed by appending a base64url-no-pad encoded version of the digest value.
      3. Add a new entry, newEntry, to bnodeIdMap using the key from entry and b64urlDigest as the value.
    3. Return bnodeIdMap.
  2. Return labelMapFactoryFunction.
Note: Other algorithms are possible

A different primitive could be created that returned a label map factory function that would instead sort the resulting HMAC digests and assign labels in the produced label map using a prefix and integers based on their sorted order. This primitive might be useful for selective disclosure schemes, such as BBS, that favor unlinkability over minimizing unrevealed data leakage.

3.4.5 skolemizeNQuads

The following algorithm replaces all blank node identifiers in an array of N-Quad strings with custom scheme URNs. The required inputs are an array of N-Quad strings (inputNQuads) and a URN scheme (urnScheme). An array of N-Quad strings, skolemizedNQuads, is produced as output. This operation is intended to be reversible through the use of the algorithm in Section 3.4.6 deskolemizeNQuads.

  1. Create a new array of N-Quad strings, skolemizedNQuads.
  2. For each N-Quad string, s1, in inputNQuads:
    1. Create a new string, s2, that is a copy of s1 replacing any occurrence of a blank node identifier with a URN ("urn:"), plus the input custom scheme (urnScheme), plus a colon (":"), and the value of the blank node identifier. For example, a regular expression of a similar form to the following would achieve the desired result: s1.replace(/(_:([^\s]+))/g, '<urn:custom-scheme:$2>').
    2. Append s2 to skolemizedNQuads.
  3. Return skolemizedNQuads.

3.4.6 deskolemizeNQuads

The following algorithm replaces all custom scheme URNs in an array of N-Quad statements with a blank node identifier. The required inputs are an array of N-Quad strings (inputNQuads) and a URN scheme (urnScheme). An array of N-Quad strings, deskolemizedNquads, is produced as output. This operation is intended to reverse use of the algorithm in Section 3.4.6 deskolemizeNQuads.

  1. Create a new array of N-Quad strings, deskolemizedNQuads.
  2. For each N-Quad string, s1, in inputNQuads:
    1. Create a new string, s2, that is a copy of s1 replacing any occurrence of a URN ("urn:"), plus the input custom scheme (urnScheme), plus a colon (":"), and the value of the blank node identifier with a blank node prefix ("_:"), plus the value of the blank node identifier. For example, a regular expression of a similar form to the following would achieve the desired result: s1.replace(/(<urn:custom-scheme:([^>]+)>)/g, '_:$2')..
    2. Append s2 to deskolemizedNQuads.
  3. Return deskolemizedNQuads.

3.4.7 skolemizeExpandedJsonLd

The following algorithm replaces all blank node identifiers in an expanded JSON-LD document with custom-scheme URNs, including assigning such URNs to blank nodes that are unlabeled. The required inputs are an expanded JSON-LD document (expanded), a custom URN scheme (urnScheme), a UUID string or other comparably random string (randomString), and reference to a shared integer (count). Any additional custom options (such as a document loader) can also be passed. It produces the expanded form of the skolemized JSON-LD document (skolemizedExpandedDocument as output. The skolemization used in this operation is intended to be reversible through the use of the algorithm in Section 3.4.9 toDeskolemizedNQuads.

  1. Initialize skolemizedExpandedDocument to an empty array.
  2. For each element in expanded:
    1. If either element is not an object or it contains the key @value, append a copy of element to skolemizedExpandedDocument and continue to the next element.
    2. Otherwise, initialize skolemizedNode to an object, and for each property and value in element:
      1. If value is an array, set the value of property in skolemizedNode to the result of calling this algorithm recursively passing value for expanded and keeping the other parameters the same.
      2. Otherwise, set the value of property in skolemizedNode to the first element in the array result of calling this algorithm recursively passing an array with value as its only element for expanded and keeping the other parameters the same.
    3. If skolemizedNode has no @id property, set the value of the @id property in skolemizedNode to the concatenation of "urn:", urnScheme, "_", randomString, "_" and the value of count, incrementing the value of count afterwards.
    4. Otherwise, if the value of the @id property in skolemizedNode starts with "_:", preserve the existing blank node identifier when skolemizing by setting the value of the @id property in skolemizedNode to the concatenation of "urn:", urnScheme, and the blank node identifier (i.e., the existing value of the @id property minus the "_:" prefix; e.g., if the existing value of the @id property is _:b0, the blank node identifier is b0).
    5. Append skolemizedNode to skolemizedExpandedDocument.
  3. Return skolemizedExpandedDocument.

3.4.8 skolemizeCompactJsonLd

The following algorithm replaces all blank node identifiers in a compact JSON-LD document with custom-scheme URNs. The required inputs are a compact JSON-LD document (document) and a custom URN scheme (urnScheme) which defaults to "custom-scheme:". The document is assumed to use only one @context property at the top level of the document. Any additional custom options (such as a document loader) can also be passed. It produces both an expanded form of the skolemized JSON-LD document (skolemizedExpandedDocument and a compact form of the skolemized JSON-LD document (skolemizedCompactDocument) as output. The skolemization used in this operation is intended to be reversible through the use of the algorithm in Section 3.4.9 toDeskolemizedNQuads which uses the same custom URN scheme (urnScheme).

  1. Initialize expanded to the result of the JSON-LD Expansion Algorithm, passing document and any custom options.
  2. Initialize skolemizedExpandedDocument to the result of the algorithm in Section 3.4.7 skolemizeExpandedJsonLd.
  3. Initialize skolemizedCompactDocument to the result of the JSON-LD Compaction Algorithm, passing skolemizedExpandedDocument and any custom options.
  4. Return an object with both skolemizedExpandedDocument and skolemizedCompactDocument.

3.4.9 toDeskolemizedNQuads

The following algorithm converts a skolemized JSON-LD document, such as one created using the algorithm in Section 3.4.8 skolemizeCompactJsonLd, to an array of deskolemized N-Quads. The required input is a JSON-LD document, skolemizedDocument. Additional custom options (such as a document loader) can be passed. An array of deskolemized N-Quad strings (deskolemizedNQuads) is produced as output.

  1. Initialize skolemizedDataset to the result of the Deserialize JSON-LD to RDF algorithm, passing any custom options (such as a document loader), to convert skolemizedDocument from JSON-LD to RDF in N-Quads format.
  2. Split skolemizedDataset into an array of individual N-Quads, skolemizedNQuads.
  3. Set deskolemizedNQuads to the result of the algorithm in Section 3.4.6 deskolemizeNQuads with skolemizedNQuads and "custom-scheme:" as parameters. Implementations MAY choose a different urnScheme that is different than "custom-scheme:" so long as the same scheme name was used to generate skolemizedDocument.
  4. Return deskolemizedNQuads.

3.4.10 jsonPointerToPaths

The following algorithm converts a JSON Pointer [RFC6901] to an array of paths into a JSON tree. The required input is a JSON Pointer string (pointer). An array of paths (paths) is produced as output.

  1. Initialize paths to an empty array.
  2. Initialize splitPath to an array by splitting pointer on the "/" character and skipping the first, empty, split element. In Javascript notation, this step is equivalent to the following code: pointer.split('/').slice(1)
  3. For each path in splitPath:
    1. If path does not include ~, then add path to paths, converting it to an integer if it parses as one, leaving it as a string if it does not.
    2. Otherwise, unescape any JSON pointer escape sequences in path and add the result to paths.
  4. Return paths.

3.4.11 createInitialSelection

The following algorithm creates an initial selection (a fragment of a JSON-LD document) based on a JSON-LD object. This is a helper function used within the algorithm in Section 3.4.13 selectJsonLd. The required input is a JSON-LD object (source). A JSON-LD document fragment object (selection) is produced as output.

  1. Initialize selection to an empty object.
  2. If source has an id that is not a blank node identifier, set selection.id to its value. Note: All non-blank node identifiers in the path of any JSON Pointer MUST be included in the selection, this includes any root document identifier.
  3. If source.type is set, set selection.type to its value. Note: The selection MUST include all types in the path of any JSON Pointer, including any root document type.
  4. Return selection.

3.4.12 selectPaths

The following algorithm selects a portion of a compact JSON-LD document using paths parsed from a parsed JSON Pointer. This is a helper function used within the algorithm in Section 3.4.13 selectJsonLd. The required inputs are an array of paths (paths) parsed from a JSON Pointer, a compact JSON-LD document (document), a selection document (selectionDocument) to be populated, and an array of arrays (arrays) for tracking selected arrays. This algorithm produces no output; instead it populates the given selectionDocument with any values selected via paths.

  1. Initialize parentValue to document.
  2. Initialize value to parentValue.
  3. Initialize selectedParent to selectionDocument.
  4. Initialize selectedValue to selectedParent.
  5. For each path in paths:
    1. Set selectedParent to selectedValue.
    2. Set parentValue to value.
    3. Set value to parentValue.path. If value is now undefined, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR, indicating that the JSON pointer does not match the given document.
    4. Set selectedValue to selectedParent.path.
    5. If selectedValue is now undefined:
      1. If value is an array, set selectedValue to an empty array and append selectedValue to arrays.
      2. Otherwise, set selectedValue to an initial selection passing value as source to the algorithm in Section 3.4.11 createInitialSelection.
      3. Set selectedParent.path to selectedValue.
  6. Note: With path traversal complete at the target value, the selected value will now be computed.
  7. If value is a literal, set selectedValue to value.
  8. If value is an array, Set selectedValue to a copy of value.
  9. In all other cases, set selectedValue to an object that merges a shallow copy of selectedValue with a deep copy of value, e.g., {...selectedValue, …deepCopy(value)}.
  10. Get the last path, lastPath, from paths.
  11. Set selectedParent.lastPath to selectedValue.

3.4.13 selectJsonLd

The following algorithm selects a portion of a compact JSON-LD document using an array of JSON Pointers. The required inputs are an array of JSON Pointers (pointers) and a compact JSON-LD document (document). The document is assumed to use a JSON-LD context that aliases @id and @type to id and type, respectively, and to use only one @context property at the top level of the document. A new JSON-LD document that represents a selection (selectionDocument) of the original JSON-LD document is produced as output.

  1. If pointers is empty, return null. This indicates nothing has been selected from the original document.
  2. Initialize arrays to an empty array. This variable will be used to track selected sparse arrays to make them dense after all pointers have been processed.
  3. Initialize selectionDocument to an initial selection passing document as source to the algorithm in Section 3.4.11 createInitialSelection.
  4. Set the value of the @context property in selectionDocument to a copy of the value of the @context property in document.
  5. For each pointer in pointers, walk the document from root to the pointer target value, building the selectionDocument:
    1. Parse the pointer into an array of paths, paths, using the algorithm in Section 3.4.10 jsonPointerToPaths.
    2. Use the algorithm in Section 3.4.12 selectPaths, passing document, paths, selectionDocument, and arrays.
  6. For each array in arrays:
    1. Make array dense by removing any undefined elements between elements that are defined.
  7. Return selectionDocument.

3.4.14 relabelBlankNodes

The following algorithm relabels the blank node identifiers in an array of N-Quad strings using a blank node label map. The required inputs are an array of N-Quad strings (nquads) and a blank node label map (labelMap). An array of N-Quad strings with relabeled blank node identifiers (relabeledNQuads) is produced as output.

  1. Create a new array of N-Quad strings, relabeledNQuads.
  2. For each N-Quad string, s1, in nquads:
    1. Create a new string, s2, such it that is a copy of s1 except each blank node identifier therein has been replaced with the value associated with it as a key in labelMap.
    2. Append s2 to relabeledNQuads.
  3. Return relabeledNQuads.

3.4.15 selectCanonicalNQuads

The following algorithm selects a portion of a skolemized compact JSON-LD document using an array of JSON Pointers, and outputs the resulting canonical N-Quads with any blank node labels replaced using the given label map. The required inputs are an array of JSON Pointers (pointers), a skolemized compact JSON-LD document (skolemizedCompactDocument), and a blank node label map (labelMap). Additional custom options (such as a document loader) can be passed. The document is assumed to use a JSON-LD context that aliases @id and @type to id and type, respectively, and to use only one @context property at the top level of the document. An object containing the new JSON-LD document that represents a selection of the original JSON-LD document (selectionDocument), an array of deskolemized N-Quad strings (deskolemizedNQuads), and an array of canonical N-Quads with replacement blank node labels (nquads) is produced as output.

  1. Initialize selectionDocument to the result of the algorithm in Section 3.4.13 selectJsonLd, passing pointers, and skolemizedCompactDocument as document.
  2. Initialize deskolemizedNQuads to the result of the algorithm in Section 3.4.9 toDeskolemizedNQuads, passing selectionDocument as skolemizedCompactDocument, and any custom options.
  3. Initialize nquads to the result of the algorithm in Section 3.4.14 relabelBlankNodes, passing labelMap, and deskolemizedNQuads as nquads.
  4. Return an object containing selectionDocument, deskolemizedNQuads, and nquads.

3.4.16 canonicalizeAndGroup

The following algorithm is used to output canonical N-Quad strings that match custom selections of a compact JSON-LD document. It does this by canonicalizing a compact JSON-LD document (replacing any blank node identifiers using a label map) and grouping the resulting canonical N-Quad strings according to the selection associated with each group. Each group will be defined using an assigned name and array of JSON pointers. The JSON pointers will be used to select portions of the skolemized document, such that the output can be converted to canonical N-Quads to perform group matching.

The required inputs are a compact JSON-LD document (document), a label map factory function (labelMapFactoryFunction), and a map of named group definitions (groupDefinitions). Additional custom options (such as a document loader) can be passed. The document is assumed to use a JSON-LD context that aliases @id and @type to id and type, respectively, and to use only one @context property at the top level of the document. An object containing the created groups (groups), the skolemized compact JSON-LD document (skolemizedCompactDocument), the skolemized expanded JSON-LD document (skolemizedExpandedDocument), the deskolemized N-Quad strings (deskolemizedNQuads), the blank node label map (labelMap), and the canonical N-Quad strings nquads, is produced as output.

  1. Initialize skolemizedExpandedDocument and skolemizedCompactDocument to their associated values in the result of the algorithm in Section 3.4.8 skolemizeCompactJsonLd, passing document and any custom options.
  2. Initialize deskolemizedNQuads to the result of the algorithm in Section 3.4.9 toDeskolemizedNQuads, passing skolemizedExpandedDocument and any custom options.
  3. Initialize nquads and labelMap to their associated values in the result of the algorithm in Section 3.4.1 labelReplacementCanonicalizeNQuads, passing labelMapFactoryFunction, deskolemizedNQuads as nquads, and any custom options.
  4. Initialize selections to a new map.
  5. For each key (name) and value (pointers) entry in groupDefinitions:
    1. Add an entry with a key of name and a value that is the result of the algorithm in Section 3.4.15 selectCanonicalNQuads, passing pointers, labelMap, skolemizedCompactDocument as document, and any custom options.
  6. Initialize groups to an empty object.
  7. For each key (name) and value (selectionResult) entry in selections:
    1. Initialize matching to an empty map.
    2. Initialize nonMatching to an empty map.
    3. Initialize selectedNQuads to nquads from selectionResult.
    4. Initialize selectedDeskolemizedNQuads from deskolemizedNQuads from selectionResult.
    5. For each element (nq) and index (index) in nquads:
      1. Create a map entry, entry, with a key of index and a value of nq.
      2. If selectedNQuads includes nq then add entry to matching; otherwise, add entry to nonMatching.
    6. Set name in groups to an object containing matching, nonMatching, and selectedDeskolemizedNQuads as deskolemizedNQuads.
  8. Return an object containing groups, skolemizedExpandedDocument, skolemizedCompactDocument, deskolemizedNQuads, labelMap, and nquads.

3.4.17 hashMandatoryNQuads

The following algorithm cryptographically hashes an array of mandatory to disclose N-Quads using a provided hashing API. The required input is an array of mandatory to disclose N-Quads (mandatory) and a hashing function (hasher). A cryptographic hash (mandatoryHash) is produced as output.

  1. Initialize bytes to the UTF-8 representation of the joined mandatory N-Quads.
  2. Initialize mandatoryHash to the result of using hasher to hash bytes.
  3. Return mandatoryHash.

3.5 ecdsa-sd-2023 Functions

Issue 3: (AT RISK) Pending implementation feedback and security reviews.

The Working Group is seeking implementer feedback on these cryptographic suite functions as well as horizonal security review on the feature from parties at W3C and IETF. Those reviews might result in significant changes to these algorithms, or the removal of the algorithms from the specification during the Candidate Recommendation phase.

This section contains subalgorithms that are useful to the ecdsa-sd-2023 cryptographic suite.

3.5.1 serializeSignData

The following algorithm serializes the data that is to be signed by the private key associated with the base proof verification method. The required inputs are the proof options hash (proofHash), the proof-scoped multikey-encoded public key (publicKey), and the mandatory hash (mandatoryHash). A single sign data value, represented as series of bytes, is produced as output.

  1. Return the concatenation of proofHash, publicKey, and mandatoryHash, in that order, as sign data.

3.5.2 serializeBaseProofValue

The following algorithm serializes the base proof value, including the base signature, public key, HMAC key, signatures, and mandatory pointers. The required inputs are a base signature baseSignature, a public key publicKey, an HMAC key hmacKey, an array of signatures, and an array of mandatoryPointers. A single base proof string value is produced as output.

  1. Initialize a byte array, proofValue, that starts with the ECDSA-SD base proof header bytes 0xd9, 0x5d, and 0x00.
  2. Initialize components to an array with five elements containing the values of: baseSignature, publicKey, hmacKey, signatures, and mandatoryPointers.
  3. CBOR-encode components per [RFC8949] where CBOR tagging MUST NOT be used on any of the components. Append the produced encoded value to proofValue.
  4. Initialize baseProof to a string with the Multibase base64url-no-pad-encoding of proofValue as described in the Multibase section of Controller Documents 1.0. That is, return a string starting with "u" and ending with the base64url-no-pad-encoded value of proofValue.
  5. Return baseProof as base proof.

3.5.3 parseBaseProofValue

The following algorithm parses the components of an ecdsa-sd-2023 selective disclosure base proof value. The required inputs are a proof value (proofValue). A single object parsed base proof, containing five elements, using the names baseSignature, publicKey, hmacKey, signatures, and mandatoryPointers, is produced as output.

  1. If the proofValue string does not start with u, indicating that it is a multibase-base64url-no-pad-encoded value, an error MUST be raised and SHOULD convey an error type of PROOF_VERIFICATION_ERROR.
  2. Initialize decodedProofValue to the result of base64url-no-pad-decoding the substring after the leading u in proofValue.
  3. If the decodedProofValue does not start with the ECDSA-SD base proof header bytes 0xd9, 0x5d, and 0x00, an error MUST be raised and SHOULD convey an error type of PROOF_VERIFICATION_ERROR.
  4. Initialize components to an array that is the result of CBOR-decoding the bytes that follow the three-byte ECDSA-SD base proof header. Confirm that the result is an array of five elements.
  5. Return an object with properties set to the five elements, using the names baseSignature, publicKey, hmacKey, signatures, and mandatoryPointers, respectively.

3.5.4 createDisclosureData

The following algorithm creates data to be used to generate a derived proof. The inputs include a JSON-LD document (document), an ECDSA-SD base proof (proof), an array of JSON pointers to use to selectively disclose statements (selectivePointers), and any custom JSON-LD API options, such as a document loader). A single object, disclosure data, is produced as output, which contains the "baseSignature", "publicKey", "signatures" for "filteredSignatures", "labelMap", "mandatoryIndexes", and "revealDocument" fields.

  1. Initialize baseSignature, publicKey, hmacKey, signatures, and mandatoryPointers to the values of the associated properties in the object returned when calling the algorithm in Section 3.5.3 parseBaseProofValue, passing the proofValue from proof.
  2. Initialize hmac to an HMAC API using hmacKey. The HMAC uses the same hash algorithm used in the signature algorithm, i.e., SHA-256 for a P-256 curve.
  3. Initialize labelMapFactoryFunction to the result of calling the createHmacIdLabelMapFunction algorithm passing hmac.
  4. Initialize combinedPointers to the concatenation of mandatoryPointers and selectivePointers.
  5. Initialize groupDefinitions to a map with the following entries: key of the string "mandatory" and value of mandatoryPointers, key of the string "selective" and value of selectivePointers, and key of the string "combined" and value of combinedPointers.
  6. Initialize groups and labelMap to their associated values in the result of calling the algorithm in Section 3.4.16 canonicalizeAndGroup, passing document, labelMapFactoryFunction, groupDefinitions, and any custom JSON-LD API options as parameters. Note: This step transforms the document into an array of canonical N-Quad strings with pseudorandom blank node identifiers based on hmac, and groups the N-Quad strings according to selections based on JSON pointers.
  7. Initialize relativeIndex to zero.
  8. Initialize mandatoryIndexes to an empty array.
  9. For each absoluteIndex in the keys in groups.combined.matching, convert the absolute index of any mandatory N-Quad to an index relative to the combined output that is to be revealed:
    1. If groups.mandatory.matching has absoluteIndex as a key, then append relativeIndex to mandatoryIndexes.
    2. Increment relativeIndex.
  10. Determine which signatures match a selectively disclosed statement, which requires incrementing an index counter while iterating over all signatures, skipping over any indexes that match the mandatory group.
    1. Initialize index to 0.
    2. Initialize filteredSignatures to an empty array.
    3. For each signature in signatures:
      1. While index is in groups.mandatory.matching, increment index.
      2. If index is in groups.selective.matching, add signature to filteredSignatures.
      3. Increment index.
  11. Initialize revealDocument to the result of the "selectJsonLd" algorithm, passing document, and combinedPointers as pointers.
  12. Run the RDF Dataset Canonicalization Algorithm [RDF-CANON] on the joined |combinedGroup.deskolemizedNQuads|, passing any custom options, and get the canonical bnode identifier map, canonicalIdMap. Note: This map includes the canonical blank node identifiers that a verifier will produce when they canonicalize the reveal document.
  13. Initialize verifierLabelMap to an empty map. This map will map the canonical blank node identifiers the verifier will produce when they canonicalize the revealed document to the blank node identifiers that were originally signed in the base proof.
  14. For each key (inputLabel) and value (verifierLabel) in canonicalIdMap:
    1. Add an entry to verifierLabelMap using verifierLabel as the key and the value associated with inputLabel as a key in labelMap as the value.
  15. Return an object with properties matching baseSignature, publicKey, signatures for filteredSignatures, verifierLabelMap for labelMap, mandatoryIndexes, and revealDocument.

3.5.5 compressLabelMap

The following algorithm compresses a label map. The required inputs are label map (labelMap). The output is a compressed label map.

  1. Initialize map to an empty map.
  2. For each entry (k, v) in labelMap:
    1. Add an entry to map with a key that is a base-10 integer parsed from the characters following the "c14n" prefix in k and a value that is a byte array resulting from base64url-no-pad-decoding the characters after the "u" prefix in v.
  3. Return map as compressed label map.

3.5.6 decompressLabelMap

The following algorithm decompresses a label map. The required input is a compressed label map (compressedLabelMap). The output is a decompressed label map.

  1. Initialize map to an empty map.
  2. For each entry (k, v) in compressedLabelMap:
    1. Add an entry to map with a key that adds the prefix "c14n" to k and a value that adds a prefix of "u" to the base64url-no-pad-encoded value for v.
  3. Return map as decompressed label map.

3.5.7 serializeDerivedProofValue

The following algorithm serializes a derived proof value. The required inputs are a base signature (baseSignature), public key (publicKey), an array of signatures (signatures), a label map (labelMap), and an array of mandatory indexes (mandatoryIndexes). A single derived proof value, serialized as a byte string, is produced as output.

  1. Initialize compressedLabelMap to the result of calling the algorithm in Section 3.5.5 compressLabelMap, passing labelMap as the parameter.
  2. Initialize a byte array, proofValue, that starts with the ECDSA-SD disclosure proof header bytes 0xd9, 0x5d, and 0x01.
  3. Initialize components to an array with five elements containing the values of: baseSignature, publicKey, signatures, compressedLabelMap, and mandatoryIndexes.
  4. CBOR-encode components per [RFC8949] where CBOR tagging MUST NOT be used on any of the components. Append the produced encoded value to proofValue.
  5. Return the derived proof as a string with the base64url-no-pad-encoding of proofValue as described in the Multibase section of Controller Documents 1.0. That is, return a string starting with "u" and ending with the base64url-no-pad-encoded value of proofValue.

3.5.8 parseDerivedProofValue

The following algorithm parses the components of the derived proof value. The required input is a derived proof value (proofValue). A single derived proof value value object is produced as output, which contains a set to five elements, using the names "baseSignature", "publicKey", "signatures", "labelMap", and "mandatoryIndexes".

  1. If the proofValue string does not start with u, indicating that it is a multibase-base64url-no-pad-encoded value, an error MUST be raised and SHOULD convey an error type of PROOF_VERIFICATION_ERROR.
  2. Initialize decodedProofValue to the result of base64url-no-pad-decoding the substring after the leading u in proofValue.
  3. If the decodedProofValue does not start with the ECDSA-SD disclosure proof header bytes 0xd9, 0x5d, and 0x01, an error MUST be raised and SHOULD convey an error type of PROOF_VERIFICATION_ERROR.
  4. Initialize components to an array that is the result of CBOR-decoding the bytes that follow the three-byte ECDSA-SD disclosure proof header. If the result is not an array of the following five elements — a byte array of length 64; a byte array of length 36; an array of byte arrays, each of length 64; a map of integers to byte arrays, each of length 32; and an array of integers — an error MUST be raised and SHOULD convey an error type of PROOF_VERIFICATION_ERROR.
  5. Replace the fourth element in components using the result of calling the algorithm in Section 3.5.6 decompressLabelMap, passing the existing fourth element of components as compressedLabelMap.
  6. Return derived proof value as an object with properties set to the five elements, using the names "baseSignature", "publicKey", "signatures", "labelMap", and "mandatoryIndexes", respectively.

3.5.9 createVerifyData

The following algorithm creates the data needed to perform verification of an ECDSA-SD-protected verifiable credential. The inputs include a JSON-LD document (document), an ECDSA-SD disclosure proof (proof), and any custom JSON-LD API options, such as a document loader. A single verify data object value is produced as output containing the following fields: "baseSignature", "proofHash", "publicKey", "signatures", "nonMandatory", and "mandatoryHash".

  1. Initialize proofHash to the result of perform RDF Dataset Canonicalization [RDF-CANON] on the proof options. The hash used is the same as the one used in the signature algorithm, i.e., SHA-256 for a P-256 curve. Note: This step can be performed in parallel; it only needs to be completed before this algorithm needs to use the proofHash value.
  2. Initialize baseSignature, publicKey, signatures, labelMap, and mandatoryIndexes, to the values associated with their property names in the object returned when calling the algorithm in Section 3.5.8 parseDerivedProofValue, passing proofValue from proof.
  3. Initialize labelMapFactoryFunction to the result of calling the "createLabelMapFunction" algorithm.
  4. Initialize nquads to the result of calling the "labelReplacementCanonicalize" algorithm, passing document, labelMapFactoryFunction, and any custom JSON-LD API options. Note: This step transforms the document into an array of canonical N-Quads with pseudorandom blank node identifiers based on labelMap.
  5. Initialize mandatory to an empty array.
  6. Initialize nonMandatory to an empty array.
  7. For each entry (index, nq) in nquads, separate the N-Quads into mandatory and non-mandatory categories:
    1. If mandatoryIndexes includes index, add nq to mandatory.
    2. Otherwise, add nq to nonMandatory.
  8. Initialize mandatoryHash to the result of calling the "hashMandatory" primitive, passing mandatory.
  9. Return an object with properties matching baseSignature, proofHash, publicKey, signatures, nonMandatory, and mandatoryHash.

3.6 ecdsa-sd-2023

Issue 4: (AT RISK) Pending implementation feedback and security reviews.

The Working Group is seeking implementer feedback on this cryptographic suite as well as horizonal security review on the feature from parties at W3C and IETF. Those reviews might result in significant changes to this algorithm, or the removal of the algorithm from the specification during the Candidate Recommendation phase.

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

3.6.1 Create Base Proof (ecdsa-sd-2023)

The following algorithm specifies how to create a data integrity proof given an unsecured data document. Required inputs are an unsecured data document (map unsecuredDocument), and a set of proof options (map options). A data integrity proof (map), or an error, is produced as output.

  1. Let proof be a clone of the proof options, options.
  2. Let proofConfig be the result of running the algorithm in Section 3.6.4 Base Proof Configuration (ecdsa-sd-2023) with options passed as a parameter.
  3. Let transformedData be the result of running the algorithm in Section 3.6.2 Base Proof Transformation (ecdsa-sd-2023) with unsecuredDocument, proofConfig, and options passed as parameters.
  4. Let hashData be the result of running the algorithm in Section 3.6.3 Base Proof Hashing (ecdsa-sd-2023) with transformedData and proofConfig passed as a parameters.
  5. Let proofBytes be the result of running the algorithm in Section 3.6.5 Base Proof Serialization (ecdsa-sd-2023) with hashData and options passed as parameters.
  6. Let proof.proofValue be a base64-url-encoded Multibase value of the proofBytes.
  7. Return proof as the data integrity proof.

3.6.2 Base Proof Transformation (ecdsa-sd-2023)

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.6.3 Base Proof Hashing (ecdsa-sd-2023).

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), a cryptosuite identifier (cryptosuite), and a verification method (verificationMethod). The transformation options MUST contain an array of mandatory JSON pointers (mandatoryPointers) and MAY contain additional options, such as a JSON-LD document loader. A transformed data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.

  1. Initialize hmac to an HMAC API using a locally generated and exportable HMAC key. The HMAC uses the same hash algorithm used in the signature algorithm, which is detected via the verificationMethod provided to the function, i.e., SHA-256 for a P-256 curve. Per the recommendations of [RFC2104], the HMAC key MUST be the same length as the digest size; for SHA-256, this is 256 bits or 32 bytes.
  2. Initialize labelMapFactoryFunction to the result of calling the createHmacIdLabelMapFunction algorithm passing hmac.
  3. Initialize groupDefinitions to a map with an entry with a key of the string "mandatory" and a value of mandatoryPointers.
  4. Initialize groups to the result of calling the algorithm in Section 3.4.16 canonicalizeAndGroup, passing labelMapFactoryFunction, groupDefinitions, unsecuredDocument as document, and any custom JSON-LD API options. Note: This step transforms the document into an array of canonical N-Quads with pseudorandom blank node identifiers based on hmac, and groups the N-Quad strings according to selections based on JSON pointers.
  5. Initialize mandatory to the values in the groups.mandatory.matching map.
  6. Initialize nonMandatory to the values in the groups.mandatory.nonMatching map.
  7. Initialize hmacKey to the result of exporting the HMAC key from hmac.
  8. Return an object with mandatoryPointers set to mandatoryPointers, mandatory set to mandatory, nonMandatory set to nonMandatory, and hmacKey set to hmacKey.

3.6.3 Base Proof Hashing (ecdsa-sd-2023)

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.6.5 Base Proof Serialization (ecdsa-sd-2023).

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

  1. Initialize proofHash to the result of calling the RDF Dataset Canonicalization algorithm [RDF-CANON] on canonicalProofConfig and then cryptographically hashing the result using the same hash that is used by the signature algorithm, i.e., SHA-256 for a P-256 curve. Note: This step can be performed in parallel; it only needs to be completed before this algorithm terminates as the result is part of the return value.
  2. Initialize mandatoryHash to the result of calling the the algorithm in Section 3.4.17 hashMandatoryNQuads, passing transformedDocument.mandatory.
  3. Initialize hashData as a deep copy of transformedDocument and add proofHash as proofHash and mandatoryHash as mandatoryHash to that object.
  4. Return hashData as hash data.

3.6.4 Base Proof Configuration (ecdsa-sd-2023)

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

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

  1. Let proofConfig be a clone of the options object.
  2. If proofConfig.type is not set to DataIntegrityProof and/or proofConfig.cryptosuite is not set to ecdsa-sd-2023, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR.
  3. If proofConfig.created is set and if the value is not a valid [XMLSCHEMA11-2] datetime, an error MUST be raised and SHOULD convey an error type of PROOF_GENERATION_ERROR.
  4. Set proofConfig.@context to unsecuredDocument.@context.
  5. Let canonicalProofConfig be the result of applying the RDF Dataset Canonicalization [RDF-CANON] to the proofConfig.
  6. Return canonicalProofConfig.

3.6.5 Base Proof Serialization (ecdsa-sd-2023)

The following algorithm specifies how to create a base proof; called by an issuer of an ECDSA-SD-protected Verifiable Credential. The base proof is to be given only to the holder, who is responsible for generating a derived proof from it, exposing only selectively disclosed details in the proof to a verifier. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData) and proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single digital proof value represented as series of bytes is produced as output.

  1. Initialize proofHash, mandatoryPointers, mandatoryHash, nonMandatory, and hmacKey to the values associated with their property names hashData.
  2. Initialize proofScopedKeyPair to a locally generated P-256 ECDSA key pair. Note: This key pair is scoped to the specific proof; it is not used for anything else and the private key will be destroyed when this algorithm terminates.
  3. Initialize signatures to an array where each element holds the result of digitally signing the UTF-8 representation of each N-Quad string in nonMandatory, in order. The digital signature algorithm is ES256, i.e., uses a P-256 curve over a SHA-256 digest, and uses the private key from proofScopedKeyPair. Note: This step generates individual signatures for each statement that can be selectively disclosed using a local, proof-scoped key pair that binds them together; this key pair will be bound to the proof by a signature over its public key using the private key associated with the base proof verification method.
  4. Initialize publicKey to the multikey expression of the public key exported from proofScopedKeyPair. That is, an array of bytes starting with the bytes 0x80 and 0x24 (which is the multikey p256-pub header (0x1200) expressed as a varint) followed by the compressed public key bytes (the compressed header with 2 for an even y coordinate and 3 for an odd one followed by the x coordinate of the public key).
  5. Initialize toSign to the result of calling the algorithm in Section 3.5.1 serializeSignData, passing proofHash, publicKey, and mandatoryHash as parameters to the algorithm.
  6. Initialize baseSignature to the result of digitally signing toSign using the private key associated with the base proof verification method.
  7. Initialize proofValue to the result of calling the algorithm in Section 3.5.2 serializeBaseProofValue, passing baseSignature, publicKey, hmacKey, signatures, and mandatoryPointers as parameters to the algorithm.
  8. Return proofValue as digital proof.

3.6.6 Add Derived Proof (ecdsa-sd-2023)

The following algorithm creates a selective disclosure derived proof; called by a holder of an ecdsa-sd-2023-protected verifiable credential. The derived proof is to be given to the verifier. The inputs include a JSON-LD document (document), an ECDSA-SD base proof (proof), an array of JSON pointers to use to selectively disclose statements (selectivePointers), and any custom JSON-LD API options, such as a document loader. A single selectively revealed document value, represented as an object, is produced as output.

  1. Initialize baseSignature, publicKey, signatures, labelMap, mandatoryIndexes, revealDocument to the values associated with their property names in the object returned when calling the algorithm in Section 3.5.4 createDisclosureData, passing the document, proof, selectivePointers, and any custom JSON-LD API options, such as a document loader.
  2. Initialize newProof to a shallow copy of proof.
  3. Replace proofValue in newProof with the result of calling the algorithm in Section 3.5.7 serializeDerivedProofValue, passing baseSignature, publicKey, signatures, labelMap, and mandatoryIndexes.
  4. Set the value of the "proof" property in revealDocument to newProof.
  5. Return revealDocument as the selectively revealed document.

3.6.7 Verify Derived Proof (ecdsa-sd-2023)

The following algorithm attempts verification of an ecdsa-sd-2023 derived proof. This algorithm is called by a verifier of an ECDSA-SD-protected verifiable credential. The inputs include a JSON-LD document (document), an ECDSA-SD disclosure proof (proof), and any custom JSON-LD API options, such as a document loader. This algorithm returns a verification result:

  1. Let unsecuredDocument be a copy of document with the proof value removed.
  2. Initialize baseSignature, proofHash, publicKey, signatures, nonMandatory, and mandatoryHash to the values associated with their property names in the object returned when calling the algorithm in Section 3.5.9 createVerifyData, passing the document, proof, and any custom JSON-LD API options, such as a document loader.
  3. If the length of signatures does not match the length of nonMandatory, an error MUST be raised and SHOULD convey an error type of PROOF_VERIFICATION_ERROR, indicating that the signature count does not match the non-mandatory message count.
  4. Initialize publicKeyBytes to the public key bytes expressed in publicKey. Instructions on how to decode the public key value can be found in Section 2.1.1 Multikey.
  5. Initialize toVerify to the result of calling the algorithm in Setion 3.5.1 serializeSignData, passing proofHash, publicKey, and mandatoryHash.
  6. Initialize verified to true.
  7. Initialize verificationCheck be the result of applying the verification algorithm of the Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with toVerify as the data to be verified against the baseSignature using the public key specified by publicKeyBytes. If verificationCheck is false, set verified to false.
  8. For every entry (index, signature) in signatures, verify every signature for every selectively disclosed (non-mandatory) statement:
    1. Initialize verificationCheck to the result of applying the verification algorithm Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS-186-5], with the UTF-8 representation of the value at index of nonMandatory as the data to be verified against signature using the public key specified by publicKeyBytes.
    2. If verificationCheck is false, set verified to false.
  9. Return a verification result with items:
    verified
    The value of verified
    verifiedDocument
    unsecuredDocument if verified is true, otherwise Null

4. Security Considerations

This section is non-normative.

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 integrity and authenticity of a secured document that is protected by this cryptographic suite is dependent on a number of factors including the following:

In the following sections, we review these important points and direct the reader to additional information.

4.1 Choice of ECDSA and Parameters

This section is non-normative.

The ECDSA signature scheme has the EUF-CMA (existential unforgeability under chosen message attacks) security property. This property guarantees that any efficient adversary who has the public key pk 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).

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 pk of the signer and received an arbitrary number of signatures on messages of its choice, it cannot output a new valid signature pair for a new message nor a new signature for an old message (except with negligible probability). ECDSA signature scheme does not have the SUF-CMA property, while other schemes such as EdDSA [FIPS-186-5] do.

Per [NIST-SP-800-57-Part-1] in the absence of large scale quantum computers a security strength level of 128 bits requires a key size of approximately 256 bits while a security strength level of 192 bits requires a key size of 384 bits. [NIST-SP-800-186] recommendations includes curves P-256 and P-384 at these respective security strength levels.

4.2 Implementation Considerations for ECDSA Algorithms

This section is non-normative.

The ECDSA algorithm as detailed in [FIPS-186-5] states: "A new secret random number k, 0 < k < n, shall be generated prior to the generation of each digital signature for use during the signature generation process." The failure to properly generate this k value has lead to some highly publicized integrity breaches in widely deployed systems. To counter this problem, a hash-based method of determining the secret number k, called deterministic ECDSA, is given in [FIPS-186-5] and [RFC6979].

Verification of a ECDSA signature is independent of the method of generating k. Hence it is generally recommended to use deterministic ECDSA unless other requirements dictate otherwise. For example, using different k values results in different signature values for the same document which might be a desirable property in some privacy enhancing situations.

4.3 Key Management

This section is non-normative.

The security of the ECDSA algorithm is dependent on the quality and protection of its private signing key. Guidance in the management of cryptographic keys is a large subject and the reader is referred to [NIST-SP-800-57-Part-1] for more extensive recommendations and discussion. As strongly recommended in both [FIPS-186-5] and [NIST-SP-800-57-Part-1], an ECDSA private signing key is not to be used for any other purpose than ECDSA signatures.

ECDSA private signing keys and public verification keys are strongly advised to have limited cryptoperiods [NIST-SP-800-57-Part-1], where a cryptoperiod is "the time span during which a specific key is authorized for use by legitimate entities or the keys for a given system will remain in effect." [NIST-SP-800-57-Part-1] gives extensive guidance on cryptoperiods for different key types under different situations and generally recommends a 1-3 year cryptoperiod for a private signing key.

To deal with potential private key compromises, [NIST-SP-800-57-Part-1] gives recommendations for protective measures, harm reduction, and revocation. Although we have been emphasizing the security of the private signing key, assurance of public key validity is highly recommended on all public keys before using them, per [NIST-SP-800-57-Part-1].

5. Privacy Considerations

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

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

5.1 Unlinkable Disclosure

The cryptographic suites described in this specification do not support unlinkable disclosure. If unlinkable disclosure is of interest, the Data Integrity BBS Cryptosuites v1.0 specification provides an unlinkable digital signature mechanism.

A. Test Vectors

This section is non-normative.

Note

All test vectors are produced using deterministic ECDSA. The implementation was validated against the test vectors in [RFC6979].

A.1 Representation: ecdsa-rdfc-2019, with curve P-256

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 5: Private and Public keys for Signature
{
  "publicKeyMultibase": "zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
  "secretKeyMultibase": "z42twTcNeSYcnqg1FLuSFs2bsGH3ZqbRHFmvS9XMsYhjxvHN"
}

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

Example 6: 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 7: 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 8: 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 9: Proof Options Document
{
  "type": "DataIntegrityProof",
  "cryptosuite": "ecdsa-rdfc-2019",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
  "proofPurpose": "assertionMethod",
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ]
}
Example 10: 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> "ecdsa-rdfc-2019"^^<https://w3id.org/security#cryptosuiteString> .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP> .
Example 11: Hash of Canonical Proof Options Document (hex)
3a8a522f689025727fb9d1f0fa99a618da023e8494ac74f51015d009d35abc2e

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 ECDSA signature, and then base-58-btc encode the signature.

Example 12: Combine hashes of Proof Options and Credential (hex)
3a8a522f689025727fb9d1f0fa99a618da023e8494ac74f51015d009d35abc2e517744132ae165a5349155bef0bb0cf2258fff99dfe1dbd914b938d775a36017
Example 13: Signature of Combined Hashes (hex)
1cb4290918ffb04a55ff7ae1e55e316a9990fda8eec67325eac7fcbf2ddf9dd2b06716a657e72b284c9604df3a172ecbf06a1a475b49ac807b1d9162df855636
Example 14: Signature of Combined Hashes base-58-btc
zaHXrr7AQdydBk3ahpCDpWbxfLokDqmCToYm2dyWvpcFVyWooC2he63w1f7UNQoAMKdhaRtcnaE2KTo5o5vTCcfw

Assemble the signed credential with the following two steps:

  1. Add the proofValue field with the previously computed base-58-btc value to the proof options document.
  2. Set the proof field of the credential to the augmented proof option document.
Example 15: 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": "ecdsa-rdfc-2019",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "zaHXrr7AQdydBk3ahpCDpWbxfLokDqmCToYm2dyWvpcFVyWooC2he63w1f7UNQoAMKdhaRtcnaE2KTo5o5vTCcfw"
  }
}

A.2 Representation: ecdsa-rdfc-2019, with curve P-384

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 16: Private and Public keys for Signature
{
  "publicKeyMultibase": "z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ",
  "secretKeyMultibase": "z2fanyY7zgwNpZGxX5fXXibvScNaUWNprHU9dKx7qpVj7mws9J8LLt4mDB5TyH2GLHWkUc"
}

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 17: 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 18: 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 19: Hash of Canonical Credential without Proof (hex)
8bf6e01df72c5b62f91b685231915ac4b8c58ea95f002c6b8f6bfafa1b251df476b56b8e01518e317dab099d3ecbff96

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 20: Proof Options Document
{
  "type": "DataIntegrityProof",
  "cryptosuite": "ecdsa-rdfc-2019",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "did:key:z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ#z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ",
  "proofPurpose": "assertionMethod",
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ]
}
Example 21: 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> "ecdsa-rdfc-2019"^^<https://w3id.org/security#cryptosuiteString> .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <did:key:z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ#z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ> .
Example 22: Hash of Canonical Proof Options Document (hex)
e32805a26492eac777aa7a138f6d8da3c74e0c7be7b296dcaccf97420c3b92eaad7be6449ca565e165031567f5c7cbc1

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 ECDSA signature, and then base-58-btc encode the signature.

Example 23: Combine hashes of Proof Options and Credential (hex)
e32805a26492eac777aa7a138f6d8da3c74e0c7be7b296dcaccf97420c3b92eaad7be6449ca565e165031567f5c7cbc18bf6e01df72c5b62f91b685231915ac4b8c58ea95f002c6b8f6bfafa1b251df476b56b8e01518e317dab099d3ecbff96
Example 24: Signature of Combined Hashes (hex)
177ac088806c2506d49f0bfec16056a6a80ace62cd029888ad561aba22a59d192d77d9b1fc28df80dea5ee6c8bceb16f1b8bff6bd6ff2d8f8778bdde48bafa7b6cc1f914c0168b5c04499882f632deea9cb7d977e888bb0e1ee9fb20ff03b025
Example 25: Signature of Combined Hashes base-58-btc
z967Mvv5bxtmLNqTzPZ8KmJjFmFXaAKeQNzq7GWnQkMcLtaGSSmuozE5WtJ8PipMe178B1tE28K1vsJur9bGVJhz6jgSJsRHFSQeqgH8hhjcg8gZDFJC1b9FsR5ggNmDBqHv

Assemble the signed credential with the following two steps:

  1. Add the proofValue field with the previously computed base-58-btc value to the proof options document.
  2. Set the proof field of the credential to the augmented proof option document.
Example 26: 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": "ecdsa-rdfc-2019",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "did:key:z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ#z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ",
    "proofPurpose": "assertionMethod",
    "proofValue": "z967Mvv5bxtmLNqTzPZ8KmJjFmFXaAKeQNzq7GWnQkMcLtaGSSmuozE5WtJ8PipMe178B1tE28K1vsJur9bGVJhz6jgSJsRHFSQeqgH8hhjcg8gZDFJC1b9FsR5ggNmDBqHv"
  }
}

A.3 Representation: ecdsa-jcs-2019 with curve P-256

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 27: Private and Public keys for Signature
{
  "publicKeyMultibase": "zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
  "secretKeyMultibase": "z42twTcNeSYcnqg1FLuSFs2bsGH3ZqbRHFmvS9XMsYhjxvHN"
}

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

Example 28: 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 29: 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 30: 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 31: Proof Options Document
{
  "type": "DataIntegrityProof",
  "cryptosuite": "ecdsa-jcs-2019",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
  "proofPurpose": "assertionMethod"
}
Example 32: Canonical Proof Options Document
{"created":"2023-02-24T23:36:38Z","cryptosuite":"ecdsa-jcs-2019","proofPurpose":"assertionMethod","type":"DataIntegrityProof","verificationMethod":"did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP"}
Example 33: Hash of Canonical Proof Options Document (hex)
9c4b552d65fcb106b6b27ec2436d8ae81b319afc7aeaab7964b2938cd120cec3

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 ECDSA signature, and then base-58-btc encode the signature.

Example 34: Combine hashes of Proof Options and Credential (hex)
9c4b552d65fcb106b6b27ec2436d8ae81b319afc7aeaab7964b2938cd120cec359b7cb6251b8991add1ce0bc83107e3db9dbbab5bd2c28f687db1a03abc92f19
Example 35: Signature of Combined Hashes (hex)
29793c6684cb7c3628e09ed5f14d06a37835cc9564b50fe1829c252c6bb9d14f52513c92533508ea4b4938ed523597b40b9584f395537b87592dc60d0f5ea9b7
Example 36: Signature of Combined Hashes base-58-btc
zq6PrUMCtqY5obCSsrQxuFJdGffCDxvFuopdZiBPUBRTFEs1VVsBZi8YiEwVWgHYrXxoV93gBHqGDBtQLPFxpZxz

Assemble the signed credential with the following three steps:

  1. Add the proofValue field with the previously computed base-58-btc value to the proof options document.
  2. Set the proof options @context field to the value of the unsecuredDocument.@context.
  3. Set the proof field of the credential to the augmented proof option document.
Example 37: 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": "ecdsa-jcs-2019",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "zq6PrUMCtqY5obCSsrQxuFJdGffCDxvFuopdZiBPUBRTFEs1VVsBZi8YiEwVWgHYrXxoV93gBHqGDBtQLPFxpZxz"
  }
}

A.4 Representation: ecdsa-jcs-2019 with curve P-384

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 38: Private and Public keys for Signature
{
  "publicKeyMultibase": "z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ",
  "secretKeyMultibase": "z2fanyY7zgwNpZGxX5fXXibvScNaUWNprHU9dKx7qpVj7mws9J8LLt4mDB5TyH2GLHWkUc"
}

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

Example 39: 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 40: 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 41: Hash of Canonical Credential without Proof (hex)
3e0be671cc1881035d463158c80921973dab3534d4f8dfacf4ff2725a4115eb718e49d66de0e90e7365cd6062abf2259

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 42: Proof Options Document
{
  "type": "DataIntegrityProof",
  "cryptosuite": "ecdsa-jcs-2019",
  "created": "2023-02-24T23:36:38Z",
  "verificationMethod": "did:key:z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ#z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ",
  "proofPurpose": "assertionMethod"
}
Example 43: Canonical Proof Options Document
{"created":"2023-02-24T23:36:38Z","cryptosuite":"ecdsa-jcs-2019","proofPurpose":"assertionMethod","type":"DataIntegrityProof","verificationMethod":"did:key:z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ#z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ"}
Example 44: Hash of Canonical Proof Options Document (hex)
bb8fd231f3f5441c089210bb991ca21910ecb2c62e82111f9d4de1ac0db3e6f2fc5dbe33cffc3a08ec1165b7b3a8bedd

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 ECDSA signature, and then base-58-btc encode the signature.

Example 45: Combine hashes of Proof Options and Credential (hex)
bb8fd231f3f5441c089210bb991ca21910ecb2c62e82111f9d4de1ac0db3e6f2fc5dbe33cffc3a08ec1165b7b3a8bedd3e0be671cc1881035d463158c80921973dab3534d4f8dfacf4ff2725a4115eb718e49d66de0e90e7365cd6062abf2259
Example 46: Signature of Combined Hashes (hex)
45cf28964c4335b76efc2d3c9893735e3f2330f41928b5c18b507d1d6b6bd5a4c5ef3885b90d93ae6d79be92cf817b844dc444e4b645fa2f1f9f9251e97428edf49a412be93b348269f76cb39d20140fb621ee004e3500a5dbecd677530a146c
Example 47: Signature of Combined Hashes base-58-btc
zR3krc7pt9Dpn1PY2u8HWPePggtzAG2SuH2ZGNrzw8Ku3QrFLWgDTjS5mCWy65ShixJEtpMwfviAFfh5xTgd5FGN1sSbpPJ5djqSZQLqQkY8KLBPNswuqKtq3bS8f9vEHm8w

Assemble the signed credential with the following three steps:

  1. Add the proofValue field with the previously computed base-58-btc value to the proof options document.
  2. Set the proof options @context field to the value of the unsecuredDocument.@context.
  3. Set the proof field of the credential to the augmented proof option document.
Example 48: 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": "ecdsa-jcs-2019",
    "created": "2023-02-24T23:36:38Z",
    "verificationMethod": "did:key:z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ#z82LkuBieyGShVBhvtE2zoiD6Kma4tJGFtkAhxR5pfkp5QPw4LutoYWhvQCnGjdVn14kujQ",
    "proofPurpose": "assertionMethod",
    "proofValue": "zR3krc7pt9Dpn1PY2u8HWPePggtzAG2SuH2ZGNrzw8Ku3QrFLWgDTjS5mCWy65ShixJEtpMwfviAFfh5xTgd5FGN1sSbpPJ5djqSZQLqQkY8KLBPNswuqKtq3bS8f9vEHm8w"
  }
}

A.5 Representation: ecdsa-sd-2023

To demonstrate selective disclosure features including mandatory disclosure, selective disclosure, and overlap between mandatory and selective disclosure requires an input credential document with more content than previous test vectors. To avoid excessively long test vectors the starting document test vector is based on a purely ficticious windsurfing (sailing) competition scenario. In addition we break the test vectors into two groups based on those that would be generated by the issuer (base proof) and those that would be generated by the holder (derived proof).

A.5.1 Base Proof

In order to add a selective disclosure base proof to a document the issuer needs the following cryptographic key material:

  1. The issuers private/public key pair, i.e., the key pair corresponding to the verification method that will be part of the proof.
  2. A per proof private/public key pair created by the issuer just for this proof. This is an ephemeral, single use key pair where the private key is not kept after the proof has been generated.
  3. An HMAC key. This used to randomize the order of the blank node ids to avoid potential information leakage from the blank node id ordering. This is used only once and is shared between issuer and holder. The HMAC in this case is functioning as a pseudorandom function (PRF).

The key material used for generating the add base proof test vectors is shown below. Multibase representation is use for the P-256 key pairs and the HMAC key is given as a hexadecimal string.

Example 49: Private and Public keys for Signature
{
  "baseKeyPair": {
    "publicKeyMultibase": "zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "secretKeyMultibase": "z42twTcNeSYcnqg1FLuSFs2bsGH3ZqbRHFmvS9XMsYhjxvHN"
  },
  "proofKeyPair": {
    "publicKeyMultibase": "zDnaeTHfhmSaQKBc7CmdL3K7oYg3D6SC7yowe2eBeVd2DH32r",
    "secretKeyMultibase": "z42tqvNGyzyXRzotAYn43UhcFtzDUVdxJ7461fwrfhBPLmfY"
  },
  "hmacKeyString": "00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF"
}

In our scenario a sailor is registering with a race organizer for a series of windsurfing races to be held over a number of days on Maui. The organizer will inspect the sailors equipment to certify that what has been declared is accurate. The sailors unsigned equipment inventory is shown below.

Example 50: Credential without Proof
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    {
      "@vocab": "https://windsurf.grotto-networking.com/selective#"
    }
  ],
  "type": [
    "VerifiableCredential"
  ],
  "issuer": "https://vc.example/windsurf/racecommittee",
  "credentialSubject": {
    "sailNumber": "Earth101",
    "sails": [
      {
        "size": 5.5,
        "sailName": "Kihei",
        "year": 2023
      },
      {
        "size": 6.1,
        "sailName": "Lahaina",
        "year": 2023
      },
      {
        "size": 7.0,
        "sailName": "Lahaina",
        "year": 2020
      },
      {
        "size": 7.8,
        "sailName": "Lahaina",
        "year": 2023
      }
    ],
    "boards": [
      {
        "boardName": "CompFoil170",
        "brand": "Wailea",
        "year": 2022
      },
      {
        "boardName": "Kanaha Custom",
        "brand": "Wailea",
        "year": 2019
      }
    ]
  }
}

In addition to let other sailors know what kinds of equipment their competitors maybe sailing on it is mandatory that each sailor disclose the year of their most recent windsurfing board and full details on two of their sails. Note that all sailors are identified by a sail number that is printed on all their equipment. This mandatory information is specified via an array of JSON pointers as shown below.

Example 51: Mandatory Pointers
["/issuer", "/credentialSubject/sailNumber", "/credentialSubject/sails/1", "/credentialSubject/boards/0/year", "/credentialSubject/sails/2"]

The result of applying the above JSON pointers to the sailors equipment document is shown below.

Example 52: JSON Pointers and Values
[
  {
    "pointer": "/credentialSubject/sailNumber",
    "value": "Earth101"
  },
  {
    "pointer": "/credentialSubject/sails/1",
    "value": {
      "size": 6.1,
      "sailName": "Lahaina",
      "year": 2023
    }
  },
  {
    "pointer": "/credentialSubject/boards/0/year",
    "value": 2022
  },
  {
    "pointer": "/credentialSubject/sails/2",
    "value": {
      "size": 7,
      "sailName": "Lahaina",
      "year": 2020
    }
  }
]

Transformation of the unsigned document begins with canonicalizing the document as shown below.

Example 53: Canonical Document
[
  "_:c14n0 <https://windsurf.grotto-networking.com/selective#boardName> \"CompFoil170\" .\n",
  "_:c14n0 <https://windsurf.grotto-networking.com/selective#brand> \"Wailea\" .\n",
  "_:c14n0 <https://windsurf.grotto-networking.com/selective#year> \"2022\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n1 <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n",
  "_:c14n1 <https://windsurf.grotto-networking.com/selective#size> \"7.8E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n",
  "_:c14n1 <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n2 <https://windsurf.grotto-networking.com/selective#boardName> \"Kanaha Custom\" .\n",
  "_:c14n2 <https://windsurf.grotto-networking.com/selective#brand> \"Wailea\" .\n",
  "_:c14n2 <https://windsurf.grotto-networking.com/selective#year> \"2019\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n3 <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n",
  "_:c14n3 <https://windsurf.grotto-networking.com/selective#size> \"7\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n3 <https://windsurf.grotto-networking.com/selective#year> \"2020\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n4 <https://windsurf.grotto-networking.com/selective#sailName> \"Kihei\" .\n",
  "_:c14n4 <https://windsurf.grotto-networking.com/selective#size> \"5.5E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n",
  "_:c14n4 <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#boards> _:c14n0 .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#boards> _:c14n2 .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#sailNumber> \"Earth101\" .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#sails> _:c14n1 .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#sails> _:c14n3 .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#sails> _:c14n4 .\n",
  "_:c14n5 <https://windsurf.grotto-networking.com/selective#sails> _:c14n6 .\n",
  "_:c14n6 <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n",
  "_:c14n6 <https://windsurf.grotto-networking.com/selective#size> \"6.1E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n",
  "_:c14n6 <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:c14n7 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .\n",
  "_:c14n7 <https://www.w3.org/2018/credentials#credentialSubject> _:c14n5 .\n",
  "_:c14n7 <https://www.w3.org/2018/credentials#issuer> <https://vc.example/windsurf/racecommittee> .\n"
]

To prevent possible information leakage from the ordering of the blank node ids these are processed through a PRF, i.e., the HMAC to give the canonized HMAC document shown below. This represents an ordered list of statements that will be subject to mandatory and selective disclosure, i.e., it is from this list that statements are grouped.

Example 54: Canonical HMAC Document
[
  "_:u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .\n",
  "_:u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY <https://www.w3.org/2018/credentials#credentialSubject> _:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 .\n",
  "_:u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY <https://www.w3.org/2018/credentials#issuer> <https://vc.example/windsurf/racecommittee> .\n",
  "_:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n",
  "_:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg <https://windsurf.grotto-networking.com/selective#size> \"7.8E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n",
  "_:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 <https://windsurf.grotto-networking.com/selective#boardName> \"CompFoil170\" .\n",
  "_:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 <https://windsurf.grotto-networking.com/selective#brand> \"Wailea\" .\n",
  "_:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 <https://windsurf.grotto-networking.com/selective#year> \"2022\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#boards> _:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#boards> _:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sailNumber> \"Earth101\" .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk .\n",
  "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc .\n",
  "_:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw <https://windsurf.grotto-networking.com/selective#boardName> \"Kanaha Custom\" .\n",
  "_:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw <https://windsurf.grotto-networking.com/selective#brand> \"Wailea\" .\n",
  "_:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw <https://windsurf.grotto-networking.com/selective#year> \"2019\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ <https://windsurf.grotto-networking.com/selective#sailName> \"Kihei\" .\n",
  "_:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ <https://windsurf.grotto-networking.com/selective#size> \"5.5E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n",
  "_:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n",
  "_:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk <https://windsurf.grotto-networking.com/selective#size> \"6.1E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n",
  "_:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n",
  "_:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc <https://windsurf.grotto-networking.com/selective#size> \"7\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n",
  "_:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc <https://windsurf.grotto-networking.com/selective#year> \"2020\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
]

The above canonical document gets grouped in to mandatory and non-mandatory statements. The final output of the selective disclosure transformation process is shown below. Each statement is now grouped as mandatory and non-mandatory and its index in the previous list of statements is remembered.

Example 55: Add Base Transformation
{
  "mandatoryPointers": [
    "/issuer",
    "/credentialSubject/sailNumber",
    "/credentialSubject/sails/1",
    "/credentialSubject/boards/0/year",
    "/credentialSubject/sails/2"
  ],
  "mandatory": {
    "dataType": "Map",
    "value": [
      [
        0,
        "_:u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://www.w3.org/2018/credentials#VerifiableCredential> .\n"
      ],
      [
        1,
        "_:u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY <https://www.w3.org/2018/credentials#credentialSubject> _:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 .\n"
      ],
      [
        2,
        "_:u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY <https://www.w3.org/2018/credentials#issuer> <https://vc.example/windsurf/racecommittee> .\n"
      ],
      [
        8,
        "_:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 <https://windsurf.grotto-networking.com/selective#year> \"2022\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ],
      [
        9,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#boards> _:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 .\n"
      ],
      [
        11,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sailNumber> \"Earth101\" .\n"
      ],
      [
        14,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk .\n"
      ],
      [
        15,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc .\n"
      ],
      [
        22,
        "_:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n"
      ],
      [
        23,
        "_:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk <https://windsurf.grotto-networking.com/selective#size> \"6.1E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n"
      ],
      [
        24,
        "_:uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ],
      [
        25,
        "_:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n"
      ],
      [
        26,
        "_:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc <https://windsurf.grotto-networking.com/selective#size> \"7\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ],
      [
        27,
        "_:ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc <https://windsurf.grotto-networking.com/selective#year> \"2020\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ]
    ]
  },
  "nonMandatory": {
    "dataType": "Map",
    "value": [
      [
        3,
        "_:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg <https://windsurf.grotto-networking.com/selective#sailName> \"Lahaina\" .\n"
      ],
      [
        4,
        "_:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg <https://windsurf.grotto-networking.com/selective#size> \"7.8E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n"
      ],
      [
        5,
        "_:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ],
      [
        6,
        "_:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 <https://windsurf.grotto-networking.com/selective#boardName> \"CompFoil170\" .\n"
      ],
      [
        7,
        "_:u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38 <https://windsurf.grotto-networking.com/selective#brand> \"Wailea\" .\n"
      ],
      [
        10,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#boards> _:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw .\n"
      ],
      [
        12,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:u3Lv2QpFgo-YAegc1cQQKWJFW2sEjQF6FfuZ0VEoMKHg .\n"
      ],
      [
        13,
        "_:uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0 <https://windsurf.grotto-networking.com/selective#sails> _:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ .\n"
      ],
      [
        16,
        "_:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw <https://windsurf.grotto-networking.com/selective#boardName> \"Kanaha Custom\" .\n"
      ],
      [
        17,
        "_:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw <https://windsurf.grotto-networking.com/selective#brand> \"Wailea\" .\n"
      ],
      [
        18,
        "_:uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw <https://windsurf.grotto-networking.com/selective#year> \"2019\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ],
      [
        19,
        "_:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ <https://windsurf.grotto-networking.com/selective#sailName> \"Kihei\" .\n"
      ],
      [
        20,
        "_:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ <https://windsurf.grotto-networking.com/selective#size> \"5.5E0\"^^<http://www.w3.org/2001/XMLSchema#double> .\n"
      ],
      [
        21,
        "_:ufUWJRHQ9j1jmUKHLL8k6m0CZ8g4v73gOpaM5kL3ZACQ <https://windsurf.grotto-networking.com/selective#year> \"2023\"^^<http://www.w3.org/2001/XMLSchema#integer> .\n"
      ]
    ]
  },
  "hmacKeyString": "00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF"
}

The next step is to create the base proof configuration and canonicalize it. This is shown in the following two examples.

Example 56: Base Proof Configuration
{
  "type": "DataIntegrityProof",
  "cryptosuite": "ecdsa-sd-2023",
  "created": "2023-08-15T23:36:38Z",
  "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
  "proofPurpose": "assertionMethod",
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    {
      "@vocab": "https://windsurf.grotto-networking.com/selective#"
    }
  ]
}
Example 57: Canonical Base Proof Configuration
_:c14n0 <http://purl.org/dc/terms/created> "2023-08-15T23: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> "ecdsa-sd-2023"^^<https://w3id.org/security#cryptosuiteString> .
_:c14n0 <https://w3id.org/security#proofPurpose> <https://w3id.org/security#assertionMethod> .
_:c14n0 <https://w3id.org/security#verificationMethod> <did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP> .

In the hashing step we compute the SHA-256 hash of the canonicalized proof options to produce the proofHash and we compute the SHA-256 hash of the join of all the mandatory nquads to produce the mandatoryHash. These are shown below in hexadecimal format.

Example 58: Add Base Hashes
{
  "proofHash": "9c5c9b189f06cfa9d9f21a838ccb9b04316f07ad1a517bfd4955ee28c6a8229c",
  "mandatoryHash": "1994f6ce32483940032e56987a2a0cb6ea78b50944a77750c57f63801e30eca0"
}

We compute the baseSignature over the concatenation of the proofHash, proofPublicKey, and mandatoryHash using the issuers long term privateKey. We compute the signatures array by signing each non-mandatory nquad using the per proofPrivateKey. These signatures, the proofPublicKey, and mandatoryPointers which are fed to the final serialization step are shown below.

Example 59: Add Base Signing
{
  "baseSignature": "91628c3bcce94667dc50c92c1d432d64cedc26df0f98d2ec9632936214a2f2067bc005a72b806b39992b1f7759bf1296967c461bfd319455e6539b1ae7e8fbd5",
  "publicKey": "zDnaeTHfhmSaQKBc7CmdL3K7oYg3D6SC7yowe2eBeVd2DH32r",
  "signatures": [
    "29560a336e740c370d58e610a549980b567935984947089ef2f5547aff78406b2df375a1a16eff50ce8950bb0a8cd5478f1665650ca8bcde31c3533f9a19fa4c",
    "b2a312833d0479a3ded079a8e5237524d6660a3899f8234907849c9b22b8eacee10e8b4d66e187c4a19a0050b8dced05c5c29e502f7aabfcfd3c6785e42dd5a5",
    "99ea0453c235673c45c91f90331c284a4a911bd13cfc2692ae11fc4c3dadfad577d872800b884990a97ac47bb3e972f61be574726e9dfeb5a8ce386699568c8d",
    "6d030c724a5c300128d79582e82f0ca376c2116146b4e4e4331343f8b24c75f9024a8bc1ed19c247b497ce4e7ed1856282d27917383bd400286f9ca0d5634d93",
    "a501e56111a551592ff965f53a3258275f4ec3b8a9bd5c14be6f744a7dc88cd44bbb2f69af90c79b7c1595530f5692ea8d2f84f3f8c90de255e696346df2bf03",
    "6acdb0c7d6dc123d1287bb7cc3d0a3fb616971e1a975185a2d9c58b356441bcfa86d48dbd021cec87f12eeec03b67ee8496da8096d92a59be55feda35b5eeb9a",
    "7b7e1e43cfa0247c906a1634126661f26668cb4b2f9e94e391d70b9eba0b201b225647c2ccc28b396784b566545672017ae813f08d82ee69e6a47363768d9de2",
    "33ca240945fc178198c7dae59d20efaf9a531cf3a338e278ec9cc5743b57fd0e1b6715b02c6c2a96d6288c379ccade28c501d8cf9e594678535cb1ea6bbe01ed",
    "3bf1e3d2fc6cb89673a551ad82830a2b666518abe12d7dffbd40af74bf8c4e5b3356bda20b75c9a426ce73c07f5bf3a7f9cb1a2cfcd44af9520ed35e73565593",
    "766d87b78b2ffde737b351d1a9eba5fbec841b1e12ae9c3235045d2dae592b224382aaf887e12d54dcdcf89f95965bcaac737cc012ad52a6aba88e0da67af1ed",
    "39130b5d8cf7979f4ecdced20e4d9e8fb725adeafd067e9e6815101bbef702a439e9b73ea065de7a67a4c1908d1e314b38448da0dabba9eb4ef0545b8851dbe0",
    "5bea2d48556550f166835d7d9f74de484eeea798414b7e00a8fd93194400e690c6c8e4deb6b7fcaaaddb5a3d65a42bb567ac84649950ea7acb882a1a3558692f",
    "d705bf1e1b133d47d496a317e9932c2de9bc85b59a15efeb643a4fa7934dd36bcc1c89c38ced469f406b5d4c9500c9d36377c6ac38ecbb2dac1a033347e6e8d7",
    "bce1925c7e75791a025ad57d2e5a590f5d22c7422eb950a76ade5f47153b86a1acd00cccd3d906b26b833118e8c29e75c6188527788c6a320e3a159484fc470a"
  ],
  "mandatoryPointers": [
    "/issuer",
    "/credentialSubject/sailNumber",
    "/credentialSubject/sails/1",
    "/credentialSubject/boards/0/year",
    "/credentialSubject/sails/2"
  ]
}

Finally, the values above are run through the algorithm of Section 3.5.2 serializeBaseProofValue to produce the proofValue which is used in the signed based document shown below.

Example 60: Signed Base Document
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    {
      "@vocab": "https://windsurf.grotto-networking.com/selective#"
    }
  ],
  "type": [
    "VerifiableCredential"
  ],
  "issuer": "https://vc.example/windsurf/racecommittee",
  "credentialSubject": {
    "sailNumber": "Earth101",
    "sails": [
      {
        "size": 5.5,
        "sailName": "Kihei",
        "year": 2023
      },
      {
        "size": 6.1,
        "sailName": "Lahaina",
        "year": 2023
      },
      {
        "size": 7,
        "sailName": "Lahaina",
        "year": 2020
      },
      {
        "size": 7.8,
        "sailName": "Lahaina",
        "year": 2023
      }
    ],
    "boards": [
      {
        "boardName": "CompFoil170",
        "brand": "Wailea",
        "year": 2022
      },
      {
        "boardName": "Kanaha Custom",
        "brand": "Wailea",
        "year": 2019
      }
    ]
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-sd-2023",
    "created": "2023-08-15T23:36:38Z",
    "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "u2V0AhVhAkWKMO8zpRmfcUMksHUMtZM7cJt8PmNLsljKTYhSi8gZ7wAWnK4BrOZkrH3dZvxKWlnxGG_0xlFXmU5sa5-j71VgjgCQCKnLOGbY_FuM-ASpSkkOxsIR2E8n7Ml2q1UQ6tEwzi5NYIAARIjNEVWZ3iJmqu8zd7v8AESIzRFVmd4iZqrvM3e7_jlhAKVYKM250DDcNWOYQpUmYC1Z5NZhJRwie8vVUev94QGst83WhoW7_UM6JULsKjNVHjxZlZQyovN4xw1M_mhn6TFhAsqMSgz0EeaPe0Hmo5SN1JNZmCjiZ-CNJB4ScmyK46s7hDotNZuGHxKGaAFC43O0FxcKeUC96q_z9PGeF5C3VpVhAmeoEU8I1ZzxFyR-QMxwoSkqRG9E8_CaSrhH8TD2t-tV32HKAC4hJkKl6xHuz6XL2G-V0cm6d_rWozjhmmVaMjVhAbQMMckpcMAEo15WC6C8Mo3bCEWFGtOTkMxND-LJMdfkCSovB7RnCR7SXzk5-0YVigtJ5Fzg71AAob5yg1WNNk1hApQHlYRGlUVkv-WX1OjJYJ19Ow7ipvVwUvm90Sn3IjNRLuy9pr5DHm3wVlVMPVpLqjS-E8_jJDeJV5pY0bfK_A1hAas2wx9bcEj0Sh7t8w9Cj-2FpceGpdRhaLZxYs1ZEG8-obUjb0CHOyH8S7uwDtn7oSW2oCW2SpZvlX-2jW17rmlhAe34eQ8-gJHyQahY0EmZh8mZoy0svnpTjkdcLnroLIBsiVkfCzMKLOWeEtWZUVnIBeugT8I2C7mnmpHNjdo2d4lhAM8okCUX8F4GYx9rlnSDvr5pTHPOjOOJ47JzFdDtX_Q4bZxWwLGwqltYojDecyt4oxQHYz55ZRnhTXLHqa74B7VhAO_Hj0vxsuJZzpVGtgoMKK2ZlGKvhLX3_vUCvdL-MTlszVr2iC3XJpCbOc8B_W_On-csaLPzUSvlSDtNec1ZVk1hAdm2Ht4sv_ec3s1HRqeul--yEGx4SrpwyNQRdLa5ZKyJDgqr4h-EtVNzc-J-VllvKrHN8wBKtUqarqI4Npnrx7VhAORMLXYz3l59Ozc7SDk2ej7clrer9Bn6eaBUQG773AqQ56bc-oGXeemekwZCNHjFLOESNoNq7qetO8FRbiFHb4FhAW-otSFVlUPFmg119n3TeSE7up5hBS34AqP2TGUQA5pDGyOTetrf8qq3bWj1lpCu1Z6yEZJlQ6nrLiCoaNVhpL1hA1wW_HhsTPUfUlqMX6ZMsLem8hbWaFe_rZDpPp5NN02vMHInDjO1Gn0BrXUyVAMnTY3fGrDjsuy2sGgMzR-bo11hAvOGSXH51eRoCWtV9LlpZD10ix0IuuVCnat5fRxU7hqGs0AzM09kGsmuDMRjowp51xhiFJ3iMajIOOhWUhPxHCoVnL2lzc3VlcngdL2NyZWRlbnRpYWxTdWJqZWN0L3NhaWxOdW1iZXJ4Gi9jcmVkZW50aWFsU3ViamVjdC9zYWlscy8xeCAvY3JlZGVudGlhbFN1YmplY3QvYm9hcmRzLzAveWVhcngaL2NyZWRlbnRpYWxTdWJqZWN0L3NhaWxzLzI"
  }
}

A.5.2 Derived Proof

In order to create a derived proof a holder starts with a signed document containing a base proof. The base document we will use for these test vectors is the final example from Section A.5.1 Base Proof above. The first step is to run the algorithm of Section 3.5.3 parseBaseProofValue to recover baseSignature, publicKey, hmacKey, signatures, and mandatoryPointers as shown below.

Example 61: Recovered Base Signature Data
{
  "baseSignature": "91628c3bcce94667dc50c92c1d432d64cedc26df0f98d2ec9632936214a2f2067bc005a72b806b39992b1f7759bf1296967c461bfd319455e6539b1ae7e8fbd5",
  "proofPublicKey": "zDnaeTHfhmSaQKBc7CmdL3K7oYg3D6SC7yowe2eBeVd2DH32r",
  "hmacKey": "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
  "signatures": [
    "29560a336e740c370d58e610a549980b567935984947089ef2f5547aff78406b2df375a1a16eff50ce8950bb0a8cd5478f1665650ca8bcde31c3533f9a19fa4c",
    "b2a312833d0479a3ded079a8e5237524d6660a3899f8234907849c9b22b8eacee10e8b4d66e187c4a19a0050b8dced05c5c29e502f7aabfcfd3c6785e42dd5a5",
    "99ea0453c235673c45c91f90331c284a4a911bd13cfc2692ae11fc4c3dadfad577d872800b884990a97ac47bb3e972f61be574726e9dfeb5a8ce386699568c8d",
    "6d030c724a5c300128d79582e82f0ca376c2116146b4e4e4331343f8b24c75f9024a8bc1ed19c247b497ce4e7ed1856282d27917383bd400286f9ca0d5634d93",
    "a501e56111a551592ff965f53a3258275f4ec3b8a9bd5c14be6f744a7dc88cd44bbb2f69af90c79b7c1595530f5692ea8d2f84f3f8c90de255e696346df2bf03",
    "6acdb0c7d6dc123d1287bb7cc3d0a3fb616971e1a975185a2d9c58b356441bcfa86d48dbd021cec87f12eeec03b67ee8496da8096d92a59be55feda35b5eeb9a",
    "7b7e1e43cfa0247c906a1634126661f26668cb4b2f9e94e391d70b9eba0b201b225647c2ccc28b396784b566545672017ae813f08d82ee69e6a47363768d9de2",
    "33ca240945fc178198c7dae59d20efaf9a531cf3a338e278ec9cc5743b57fd0e1b6715b02c6c2a96d6288c379ccade28c501d8cf9e594678535cb1ea6bbe01ed",
    "3bf1e3d2fc6cb89673a551ad82830a2b666518abe12d7dffbd40af74bf8c4e5b3356bda20b75c9a426ce73c07f5bf3a7f9cb1a2cfcd44af9520ed35e73565593",
    "766d87b78b2ffde737b351d1a9eba5fbec841b1e12ae9c3235045d2dae592b224382aaf887e12d54dcdcf89f95965bcaac737cc012ad52a6aba88e0da67af1ed",
    "39130b5d8cf7979f4ecdced20e4d9e8fb725adeafd067e9e6815101bbef702a439e9b73ea065de7a67a4c1908d1e314b38448da0dabba9eb4ef0545b8851dbe0",
    "5bea2d48556550f166835d7d9f74de484eeea798414b7e00a8fd93194400e690c6c8e4deb6b7fcaaaddb5a3d65a42bb567ac84649950ea7acb882a1a3558692f",
    "d705bf1e1b133d47d496a317e9932c2de9bc85b59a15efeb643a4fa7934dd36bcc1c89c38ced469f406b5d4c9500c9d36377c6ac38ecbb2dac1a033347e6e8d7",
    "bce1925c7e75791a025ad57d2e5a590f5d22c7422eb950a76ade5f47153b86a1acd00cccd3d906b26b833118e8c29e75c6188527788c6a320e3a159484fc470a"
  ],
  "mandatoryPointers": [
    "/issuer",
    "/credentialSubject/sailNumber",
    "/credentialSubject/sails/1",
    "/credentialSubject/boards/0/year",
    "/credentialSubject/sails/2"
  ]
}

Next, the holder needs to indicate what, if anything else, they wish to reveal to the verifiers by specifying JSON pointers for selective disclosure. In our windsurfing competition scenario a sailor (the holder) has just completed their first day of racing and wishes to reveal to the general public (the verifiers) all the details of the windsurfing boards they used in the competition. These are shown below. Note that this slightly overlaps with the mandatory disclosed information which included only the year of their most recent board.

Example 62: Selective Disclosure Pointers
["/credentialSubject/boards/0", "/credentialSubject/boards/1"]

To produce the revealDocument, i.e., the unsigned document that will eventually be signed and sent to the verifier, we append the selective pointers to the mandatory pointers and input these combined pointers along with the document without proof to the algorithm of Section 3.4.13 selectJsonLd to give the result shown below.

Example 63: Unsigned Reveal Document
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    {
      "@vocab": "https://windsurf.grotto-networking.com/selective#"
    }
  ],
  "type": [
    "VerifiableCredential"
  ],
  "issuer": "https://vc.example/windsurf/racecommittee",
  "credentialSubject": {
    "sailNumber": "Earth101",
    "sails": [
      {
        "size": 6.1,
        "sailName": "Lahaina",
        "year": 2023
      },
      {
        "size": 7,
        "sailName": "Lahaina",
        "year": 2020
      }
    ],
    "boards": [
      {
        "year": 2022,
        "boardName": "CompFoil170",
        "brand": "Wailea"
      },
      {
        "boardName": "Kanaha Custom",
        "brand": "Wailea",
        "year": 2019
      }
    ]
  }
}

Now that we know what the revealed document looks like, we need to furnish appropriately updated information to the verifier on which statements are mandatory, the signatures for the selected non-mandatory statements, and the mapping between canonical blank node ids for the reveal document and a subset of the HMAC blank node ids. Running step 6 of the 3.5.4 createDisclosureData yields an abundance of information about various statement groups relative to the original document. Below we show a portion of the indexes for those groups.

Example 64: Derived Group Indexes
{
  "combinedIndexes":[0,1,2,6,7,8,9,10,11,14,15,16,17,18,22,23,24,25,26,27],
  "mandatoryIndexes":[0,1,2,8,9,11,14,15,22,23,24,25,26,27],
  "nonMandatoryIndexes":[3,4,5,6,7,10,12,13,16,17,18,19,20,21],
  "selectiveIndexes":[0,1,6,7,8,9,10,16,17,18]
}

The verifier needs to be able to aggregate and hash the mandatory statements. To enable this we furnish them with a list of indexes of the mandatory statements adjusted to their positions in the reveal document. In the previous example the combinedIndexes show the indexes of all the original nquads (statements) that make up the reveal document, in order. To come up with the adjusted mandatory indexes shown below we obtain the index of each of original mandatory indexes relative to the combinedIndexes as shown below.

Example 65: Adjusted Mandatory Indexes
{"adjMandatoryIndexes":[0,1,2,5,6,8,9,10,14,15,16,17,18,19]}

We have to furnish the verifier with a list of signatures for those selective statements (nquads) that are not mandatory. The original list of signatures corresponds to every non-mandatory statement and the indexes of these in the original document are given above. We now compute a list of adjusted signature indexes by computing the index of each selective index in the non-mandatory index list, ignoring any selective index not present in the list. We then use the adjusted signature indexes to obtain the filtered signature list. These lists are shown below.

Example 66: Filtered Signatures
{
    "adjSignatureIndexes": [3, 4, 5, 8, 9, 10],
    "filteredSignatures": [
        "6d030c724a5c300128d79582e82f0ca376c2116146b4e4e4331343f8b24c75f9024a8bc1ed19c247b497ce4e7ed1856282d27917383bd400286f9ca0d5634d93",
        "a501e56111a551592ff965f53a3258275f4ec3b8a9bd5c14be6f744a7dc88cd44bbb2f69af90c79b7c1595530f5692ea8d2f84f3f8c90de255e696346df2bf03",
        "6acdb0c7d6dc123d1287bb7cc3d0a3fb616971e1a975185a2d9c58b356441bcfa86d48dbd021cec87f12eeec03b67ee8496da8096d92a59be55feda35b5eeb9a",
        "3bf1e3d2fc6cb89673a551ad82830a2b666518abe12d7dffbd40af74bf8c4e5b3356bda20b75c9a426ce73c07f5bf3a7f9cb1a2cfcd44af9520ed35e73565593",
        "766d87b78b2ffde737b351d1a9eba5fbec841b1e12ae9c3235045d2dae592b224382aaf887e12d54dcdcf89f95965bcaac737cc012ad52a6aba88e0da67af1ed",
        "39130b5d8cf7979f4ecdced20e4d9e8fb725adeafd067e9e6815101bbef702a439e9b73ea065de7a67a4c1908d1e314b38448da0dabba9eb4ef0545b8851dbe0"
    ]
}

The last important piece of disclosure data is a mapping of canonical blank node ids to HMAC based ids, the labelMap, computed according to Section 3.5.4 createDisclosureData steps 12-14. This is shown below along with the rest of the disclosure data minus the reveal document.

Example 67: Disclosure Data
{
  "baseSignature": "91628c3bcce94667dc50c92c1d432d64cedc26df0f98d2ec9632936214a2f2067bc005a72b806b39992b1f7759bf1296967c461bfd319455e6539b1ae7e8fbd5",
  "publicKey": "zDnaeTHfhmSaQKBc7CmdL3K7oYg3D6SC7yowe2eBeVd2DH32r",
  "signatures": [
    "6d030c724a5c300128d79582e82f0ca376c2116146b4e4e4331343f8b24c75f9024a8bc1ed19c247b497ce4e7ed1856282d27917383bd400286f9ca0d5634d93",
    "a501e56111a551592ff965f53a3258275f4ec3b8a9bd5c14be6f744a7dc88cd44bbb2f69af90c79b7c1595530f5692ea8d2f84f3f8c90de255e696346df2bf03",
    "6acdb0c7d6dc123d1287bb7cc3d0a3fb616971e1a975185a2d9c58b356441bcfa86d48dbd021cec87f12eeec03b67ee8496da8096d92a59be55feda35b5eeb9a",
    "3bf1e3d2fc6cb89673a551ad82830a2b666518abe12d7dffbd40af74bf8c4e5b3356bda20b75c9a426ce73c07f5bf3a7f9cb1a2cfcd44af9520ed35e73565593",
    "766d87b78b2ffde737b351d1a9eba5fbec841b1e12ae9c3235045d2dae592b224382aaf887e12d54dcdcf89f95965bcaac737cc012ad52a6aba88e0da67af1ed",
    "39130b5d8cf7979f4ecdced20e4d9e8fb725adeafd067e9e6815101bbef702a439e9b73ea065de7a67a4c1908d1e314b38448da0dabba9eb4ef0545b8851dbe0"
  ],
  "labelMap": {
    "dataType": "Map",
    "value": [
      [
        "c14n0",
        "u4YIOZn1MHES1Z4Ij2hWZG3R4dEYBqg5fHTyDEvYhC38"
      ],
      [
        "c14n1",
        "uVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKw"
      ],
      [
        "c14n2",
        "uQ-qOZUDlozRsGk46ux9gp9fjT28Fy3g3nctmMoqi_U0"
      ],
      [
        "c14n3",
        "ukR2991GJuy_Tkjem_x7pLVpS4C4GkZAcuGtiPhBfSSc"
      ],
      [
        "c14n4",
        "uk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDk"
      ],
      [
        "c14n5",
        "u2IE-HtO6PyHQsGnuqhO1mX6V7RkRREhF0d0sWZlxNOY"
      ]
    ]
  },
  "mandatoryIndexes": [
    0,
    1,
    2,
    5,
    6,
    8,
    9,
    10,
    14,
    15,
    16,
    17,
    18,
    19
  ]
}

Finally using the disclosure data above with the algorithm of Section 3.5.7 serializeDerivedProofValue we obtain the signed derived (reveal) document shown below.

Example 68: Signed Derived Document
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    {
      "@vocab": "https://windsurf.grotto-networking.com/selective#"
    }
  ],
  "type": [
    "VerifiableCredential"
  ],
  "issuer": "https://vc.example/windsurf/racecommittee",
  "credentialSubject": {
    "sailNumber": "Earth101",
    "sails": [
      {
        "size": 6.1,
        "sailName": "Lahaina",
        "year": 2023
      },
      {
        "size": 7,
        "sailName": "Lahaina",
        "year": 2020
      }
    ],
    "boards": [
      {
        "year": 2022,
        "boardName": "CompFoil170",
        "brand": "Wailea"
      },
      {
        "boardName": "Kanaha Custom",
        "brand": "Wailea",
        "year": 2019
      }
    ]
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-sd-2023",
    "created": "2023-08-15T23:36:38Z",
    "verificationMethod": "did:key:zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
    "proofPurpose": "assertionMethod",
    "proofValue": "u2V0BhVhAkWKMO8zpRmfcUMksHUMtZM7cJt8PmNLsljKTYhSi8gZ7wAWnK4BrOZkrH3dZvxKWlnxGG_0xlFXmU5sa5-j71VgjgCQCKnLOGbY_FuM-ASpSkkOxsIR2E8n7Ml2q1UQ6tEwzi5OGWEBtAwxySlwwASjXlYLoLwyjdsIRYUa05OQzE0P4skx1-QJKi8HtGcJHtJfOTn7RhWKC0nkXODvUAChvnKDVY02TWEClAeVhEaVRWS_5ZfU6MlgnX07DuKm9XBS-b3RKfciM1Eu7L2mvkMebfBWVUw9WkuqNL4Tz-MkN4lXmljRt8r8DWEBqzbDH1twSPRKHu3zD0KP7YWlx4al1GFotnFizVkQbz6htSNvQIc7IfxLu7AO2fuhJbagJbZKlm-Vf7aNbXuuaWEA78ePS_Gy4lnOlUa2CgworZmUYq-Etff-9QK90v4xOWzNWvaILdcmkJs5zwH9b86f5yxos_NRK-VIO015zVlWTWEB2bYe3iy_95zezUdGp66X77IQbHhKunDI1BF0trlkrIkOCqviH4S1U3Nz4n5WWW8qsc3zAEq1Spquojg2mevHtWEA5EwtdjPeXn07NztIOTZ6PtyWt6v0Gfp5oFRAbvvcCpDnptz6gZd56Z6TBkI0eMUs4RI2g2rup607wVFuIUdvgpgBYIOGCDmZ9TBxEtWeCI9oVmRt0eHRGAaoOXx08gxL2IQt_AVggVkUuBrlOaELGVQWJD4M_qW5bcKEHWGNbOrPA_qAOKKwCWCBD6o5lQOWjNGwaTjq7H2Cn1-NPbwXLeDedy2YyiqL9TQNYIJEdvfdRibsv05I3pv8e6S1aUuAuBpGQHLhrYj4QX0knBFggk0AeXgJ4e6m1XsV5-xFud0L_1mUjZ9Mffhg5aZGTyDkFWCDYgT4e07o_IdCwae6qE7WZfpXtGRFESEXR3SxZmXE05o4AAQIFBggJCg4PEBESEw"
  }
}

B. Revision History

This section is non-normative.

This section contains the substantive changes that have been made to this specification over time.

Changes since the First Candidate Recommendation:

Changes since the First Public Working Draft:

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

D. References

D.1 Normative references

[controller-document]
Controller Documents 1.0. Manu Sporny; Michael Jones. W3C. 28 October 2024. W3C Working Draft. URL: https://www.w3.org/TR/controller-document/
[FIPS-186-5]
FIPS PUB 186-5: Digital Signature Standard (DSS). U.S. Department of Commerce/National Institute of Standards and Technology. 3 February 2023. National Standard. URL: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[JSON-LD11-API]
JSON-LD 1.1 Processing Algorithms and API. Gregg Kellogg; Dave Longley; Pierre-Antoine Champin. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11-api/
[N-QUADS]
RDF 1.1 N-Quads. Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/n-quads/
[NIST-SP-800-186]
Recommendations for Discrete Logarithm-based Cryptography: Elliptic Curve Domain Parameters. Lily Chen; Dustin Moody; Karen Randall; Andrew Regenscheid; Angela Robinson. National Institute of Standards and Technology. February 2023.
[RDF-CANON]
RDF Dataset Canonicalization. Gregg Kellogg; Dave Longley; Dan Yamamoto. W3C. 21 May 2024. W3C Recommendation. URL: https://www.w3.org/TR/rdf-canon/
[RFC2104]
HMAC: Keyed-Hashing for Message Authentication. H. Krawczyk; M. Bellare; R. Canetti. IETF. February 1997. Informational. URL: https://www.rfc-editor.org/rfc/rfc2104
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC4754]
IKE and IKEv2 Authentication Using the Elliptic Curve Digital Signature Algorithm (ECDSA). D. Fu; J. Solinas. IETF. January 2007. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4754
[RFC6234]
US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF). D. Eastlake 3rd; T. Hansen. IETF. May 2011. Informational. URL: https://www.rfc-editor.org/rfc/rfc6234
[RFC6901]
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
[RFC6979]
Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA). T. Pornin. IETF. August 2013. Informational. URL: https://www.rfc-editor.org/rfc/rfc6979
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8785]
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman. IETF. June 2020. Informational. URL: https://www.rfc-editor.org/rfc/rfc8785
[RFC8949]
Concise Binary Object Representation (CBOR). C. Bormann; P. Hoffman. IETF. December 2020. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8949
[VC-DATA-INTEGRITY]
Verifiable Credential Data Integrity 1.0. Manu Sporny; Dave Longley; Greg Bernstein; Dmitri Zagidulin; Sebastian Crane. W3C. 19 October 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vc-data-integrity/
[vc-data-model-2.0]
Verifiable Credentials Data Model v2.0. Manu Sporny; Ted Thibodeau Jr; Ivan Herman; Michael Jones; Gabe Cohen. W3C. 19 October 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vc-data-model-2.0/
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

D.2 Informative references

[NIST-SP-800-57-Part-1]
Recommendation for Key Management: Part 1 – General. Elaine Barker. National Institute of Standards and Technology. May 2020. URL: https://doi.org/10.6028/NIST.SP.800-57pt1r5
[SECG2]
SEC 2: Recommended Elliptic Curve Domain Parameters. Certicom Research. January 27, 2010. URL: https://www.secg.org/sec2-v2.pdf
[VC-DI-BBS]
Data Integrity BBS Cryptosuites v1.0. Greg Bernstein; Manu Sporny. W3C. 15 October 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vc-di-bbs/