Skip to content

Commit

Permalink
Add descriptive text for Baseline Basic example. Add input files and …
Browse files Browse the repository at this point in the history 
…pointer result file.
  • Loading branch information
@Wind4Greg
Wind4Greg committed Dec 18, 2024
1 parent bfd1707 commit 96710a8
Show file tree
Hide file tree
Showing 6 changed files with 268 additions and 1 deletion.
1 change: 1 addition & 0 deletions TestVectors/prCredMandatory.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
["/issuer"]
1 change: 1 addition & 0 deletions TestVectors/prCredSelective.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
["/validFrom", "/validUntil", "/credentialSubject/birthCountry"]
40 changes: 40 additions & 0 deletions TestVectors/prCredUnsigned.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v4rc1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCardCredential"
],
"issuer": {
"id": "did:key:zDnaeTHxNEBZoKaEo6PdA83fq98ebiFvo3X273Ydu4YmV96rg",
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIW2P4z/DiPwAG0ALnwgz64QAAAABJRU5ErkJggg=="
},
"name": "Permanent Resident Card",
"description": "Government of Utopia Permanent Resident Card.",
"credentialSubject": {
"type": [
"PermanentResident",
"Person"
],
"givenName": "JANE",
"familyName": "SMITH",
"gender": "Female",
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIW2P4v43hPwAHIgK1v4tX6wAAAABJRU5ErkJggg==",
"residentSince": "2015-01-01",
"commuterClassification": "C1",
"birthCountry": "Arcadia",
"birthDate": "1978-07-17",
"permanentResidentCard": {
"type": [
"PermanentResidentCard"
],
"identifier": "83627465",
"lprCategory": "C09",
"lprNumber": "999-999-999"
}
},
"validFrom": "2024-12-16T00:00:00Z",
"validUntil": "2025-12-16T23:59:59Z"
}
9 changes: 9 additions & 0 deletions TestVectors/prc/addPointerValues.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[
{
"pointer": "/issuer",
"value": {
"id": "did:key:zDnaeTHxNEBZoKaEo6PdA83fq98ebiFvo3X273Ydu4YmV96rg",
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIW2P4z/DiPwAG0ALnwgz64QAAAABJRU5ErkJggg=="
}
}
]
7 changes: 6 additions & 1 deletion TestVectors/prc/derivedDisclosureData.json
View file
Original file line number Diff line number Diff line change
@@ -1 +1,6 @@
{"bbsProof":"88df7e0da849da430006b121f741678ddc40eec896965a53be0ca65b1fab6289b448e0bee88474f7cf0e252b4be69453ad42c07ec5ccabcd9198d79153dfc4a2275aa1edc9106fc052bcdbad3bca01a71e282c9b0b685870f880384f9e952ae7b300f35f7d85bba88dd8f3ed36af0ba3afa2d54d00fb951e692fa7b07819cd3f1120618cfce663bfe6e303ddb43d42966e5164b9bab2e2af0459a17a6ae1b069724173d6b397650bda3982fe96caef9b062a339430851b21893e300199ebecb994293e91200fbc800593a001894979953b15b96f41eb83b299321cd5a372f15b4be032860fabd6edee4153d90b0b6a4010299b170e03313b7b83d31f951e2c00a4e64aab8793441a1b6908220294572d7394b93c8454b9886ef5023217197cb08fa53dcd13dc2c479fc5c28fcfdd6e612af7eaaaef40c07e7edbc3de1fdd49227598148ec1b37ef0a6b5d5e8a794345f56efd893decc62a3dc3387f3ee2a44226ec4dddf47f850eb9dc4cde2f0edec0e71b1427168098d968343b2fc40d6fe7d071ba1ee1cd1f997d751313685e8c1990c9e77b4968197792e724133f0c35f4facd2aa66be3b2d665b3df683a9fa170d258076ff5d75348d07be8dd85b09475380986881841c26f3abbafe802522dc910a920df97a32b4f7570d134f0fb9bd46a3e4056e5d258dc7ac574a497918508047a383a04c5445256e81cf987c5486f9cbb2e34232890a1783b2fdd6af685f633fdab17e1576f960fc76e31475d9e512042af92bc7af153cc2346e2bf4a457f263e915f5589813ace84ef2fd83b941e8dd8ee80f8c507e5e2b98b28cbed1dc8f6dfd4f42c51dbd6d042eff18dc9c80691d29c4b571aba0c19e8dcde73ab9a3aa6f703cb666528416ade1551f273a96f58d806e3ef3b060592dba22da3099271a04945161d9c6e9c678bceb20f8bca70b1f107586f02b2bc09cf92f0182d133f028f25fe26404180590af2a3021a853f2849ddbfcb41f4f529b4ea055a03c4d76","labelMap":{"dataType":"Map","value":[["c14n0","b0"],["c14n1","b2"]]},"mandatoryIndexes":[0,4,5,7],"adjSelectiveIndexes":[0,1,7,17,18,19],"presentationHeader":{"0":17,"1":51,"2":119,"3":170}}
{
"bbsProof":"88df7e0da849da430006b121f741678ddc40eec896965a53be0ca65b1fab6289b448e0bee88474f7cf0e252b4be69453ad42c07ec5ccabcd9198d79153dfc4a2275aa1edc9106fc052bcdbad3bca01a71e282c9b0b685870f880384f9e952ae7b300f35f7d85bba88dd8f3ed36af0ba3afa2d54d00fb951e692fa7b07819cd3f1120618cfce663bfe6e303ddb43d42966e5164b9bab2e2af0459a17a6ae1b069724173d6b397650bda3982fe96caef9b062a339430851b21893e300199ebecb994293e91200fbc800593a001894979953b15b96f41eb83b299321cd5a372f15b4be032860fabd6edee4153d90b0b6a4010299b170e03313b7b83d31f951e2c00a4e64aab8793441a1b6908220294572d7394b93c8454b9886ef5023217197cb08fa53dcd13dc2c479fc5c28fcfdd6e612af7eaaaef40c07e7edbc3de1fdd49227598148ec1b37ef0a6b5d5e8a794345f56efd893decc62a3dc3387f3ee2a44226ec4dddf47f850eb9dc4cde2f0edec0e71b1427168098d968343b2fc40d6fe7d071ba1ee1cd1f997d751313685e8c1990c9e77b4968197792e724133f0c35f4facd2aa66be3b2d665b3df683a9fa170d258076ff5d75348d07be8dd85b09475380986881841c26f3abbafe802522dc910a920df97a32b4f7570d134f0fb9bd46a3e4056e5d258dc7ac574a497918508047a383a04c5445256e81cf987c5486f9cbb2e34232890a1783b2fdd6af685f633fdab17e1576f960fc76e31475d9e512042af92bc7af153cc2346e2bf4a457f263e915f5589813ace84ef2fd83b941e8dd8ee80f8c507e5e2b98b28cbed1dc8f6dfd4f42c51dbd6d042eff18dc9c80691d29c4b571aba0c19e8dcde73ab9a3aa6f703cb666528416ade1551f273a96f58d806e3ef3b060592dba22da3099271a04945161d9c6e9c678bceb20f8bca70b1f107586f02b2bc09cf92f0182d133f028f25fe26404180590af2a3021a853f2849ddbfcb41f4f529b4ea055a03c4d76",
"labelMap":{"dataType":"Map","value":[["c14n0","b0"],["c14n1","b2"]]},
"mandatoryIndexes":[0,4,5,7],"adjSelectiveIndexes":[0,1,7,17,18,19],
"presentationHeader":{"0":17,"1":51,"2":119,"3":170}
}
211 changes: 211 additions & 0 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3015,6 +3015,217 @@ <h4>External VC System Based Linkage</h4>

<section class="appendix informative">
<h2>Test Vectors</h2>
<section>
<h4>Baseline Basic Example</h4>
<p>
The starting document test
vector is based on a purely fictitious permanent resident card. 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).
</p>
<section>
<h5>Base Proof</h5>
<p>
To add a selective disclosure base proof to a document, the issuer needs
the following cryptographic key material:
</p>
<ol>
<li>
The issuer's private/public key pair, i.e., the key pair corresponding to the
verification method that will be part of the proof.
</li>
<li>
An HMAC key. This is used to randomize the order of the blank node IDs to avoid
potential information leakage via 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).
</li>
</ol>
<p>
The key material used for generating the test vectors to test <i>add base
proof</i> is shown below. Hexadecimal representation is used for the BBS key
pairs and the HMAC key.
</p>
<pre class="example nohighlight"
title="Private and Public keys for Signature"
data-include="TestVectors/BBSKeyMaterial.json"
data-include-format="text">
</pre>
<p>
In our scenario, a permanent resident credential is being issued. The unsigned
permanent resident document is shown below.
</p>
<pre class="example nohighlight"
title="Credential without Proof"
data-include="TestVectors/prCredUnsigned.json"
data-include-format="text"></pre>
<p>
This mandatory information is specified via an array of JSON pointers
as shown below.
</p>
<pre class="example nohighlight"
title="Mandatory Pointers"
data-include="TestVectors/prCredMandatory.json"
data-include-format="text"></pre>
<p>
The result of applying the above JSON pointers to the document
is shown below.
</p>
<pre class="example nohighlight"
title="JSON Pointers and Values"
data-include="TestVectors/prc/addPointerValues.json"
data-include-format="text"></pre>
<p>
Transformation of the unsigned document begins with canonicalizing the document,
as shown below.
</p>
<pre class="example nohighlight"
title="Canonical Document"
data-include="TestVectors/prc/addBaseDocCanon.json"
data-include-format="text"></pre>
<p>
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 canonicalized 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.
</p>
<pre class="example nohighlight" title="Canonical HMAC Document"
data-include="TestVectors/prc/addBaseDocHMACCanon.json"
data-include-format="text"></pre>
<p>
The above canonical document gets grouped into mandatory and non-mandatory
statements. The final output of the selective disclosure transformation process
is shown below. Each statement is now grouped as mandatory or non-mandatory, and
its index in the previous list of statements is remembered.
</p>
<pre class="example nohighlight" title="Add Base Transformation"
data-include="TestVectors/prc/addBaseTransform.json"
data-include-format="text"></pre>
<p>
The next step is to create the base proof configuration and canonicalize it.
This is shown in the following two examples.
</p>
<pre class="example nohighlight" title="Base Proof Configuration"
data-include="TestVectors/prc/addProofConfig.json"
data-include-format="text"></pre>
<pre class="example nohighlight"
title="Canonical Base Proof Configuration"
data-include="TestVectors/prc/addProofConfigCanon.txt"
data-include-format="text"></pre>
<p>
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 N-Quads to produce the `mandatoryHash`. These are
shown below in hexadecimal format.
</p>
<pre class="example nohighlight" title="Add Base Hashes"
data-include="TestVectors/prc/addHashData.json"
data-include-format="text"></pre>
<p>
Shown below are the computed `bbsSignature` in hexadecimal, and the
`mandatoryPointers`. These are are fed to the final serialization step with the
`hmacKey`.
</p>
<pre class="example nohighlight" title="Add Base Signing"
data-include="TestVectors/prc/addRawBaseSignatureInfo.json"
data-include-format="text"></pre>
<p>
Finally, the values above are run through the algorithm of Section
<a href="#serializebaseproofvalue"></a>, to produce the `proofValue` which is
used in the signed base document shown below.
</p>
<pre class="example nohighlight" title="Signed Base Document"
data-include="TestVectors/prc/addSignedSDBase.json"
data-include-format="text"></pre>
</section>
<section>
<h5>Derived Proof</h5>
<p>
Random numbers are used, and an optional `presentationHeader` can be an input,
for the creation of <q>BBS proofs</q>. To furnish a deterministic set of test
vectors, we used the <q>Mocked Random Scalars</q> procedure from
[[CFRG-BBS-SIGNATURE]]. The `seed` and `presentationHeader` values we used for
generation of the derived proof test vectors are given in hex, below.
</p>
<pre class="example nohighlight"
title="seed and presentation header values"
data-include="TestVectors/BBSDeriveMaterial.json"
data-include-format="text"></pre>
<p>
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 href="#base-proof"></a>, above. The first
step is to run the algorithm of Section <a href="#parsebaseproofvalue"></a> to
recover `bbsSignature`, `hmacKey`, and `mandatoryPointers`, as shown below.
</p>
<pre class="example nohighlight" title="Recovered Base Signature Data"
data-include="TestVectors/prc/derivedRecoveredBaseData.json"
data-include-format="text"></pre>
<p>
Next, the holder needs to indicate what else, if anything, they wish to reveal
to the verifiers, by specifying JSON pointers for selective disclosure. These
are shown below.
</p>
<pre class="example nohighlight" title="Selective Disclosure Pointers"
data-include="TestVectors/prCredSelective.json"
data-include-format="text"></pre>
<p>
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 `selectJsonLd` algorithm of [[DI-ECDSA]],
to get the result shown below.
</p>
<pre class="example nohighlight" title="Unsigned Reveal Document"
data-include="TestVectors/prc/derivedUnsignedReveal.json"
data-include-format="text"></pre>
<p>
Now that we know what the revealed document looks like, we need to furnish
appropriately updated information to the verifier about which statements are
mandatory, and the indexes for the selected non-mandatory statements. Running
step 6 of the
<a href="#createdisclosuredata"></a> 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.
</p>
<pre class="example nohighlight" title="Derived Group Indexes"
data-include="TestVectors/prc/derivedGroupIndexes.json"
data-include-format="text"></pre>
<p>
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 (i.e., relative to the
`combinedIndexes`), while the `selectiveIndexes` need to be adjusted relative to
their positions within the `nonMandatoryIndexes`. These "adjusted" indexes are
shown below.
</p>
<pre class="example nohighlight"
title="Adjusted Mandatory and Selective Indexes"
data-include="TestVectors/prc/derivedAdjIndexes.json"
data-include-format="text"></pre>

<p>
The last important piece of disclosure data is a mapping of canonical blank node
IDs to HMAC-based shuffled IDs, the `labelMap`, computed according to Section
<a href="#createdisclosuredata"></a>. This is shown below along with
the rest of the disclosure data minus the reveal document.
</p>
<pre class="example nohighlight" title="Disclosure Data"
data-include="TestVectors/prc/derivedDisclosureData.json"
data-include-format="text"></pre>
<p>
Finally, using the disclosure data above with the algorithm of Section
<a href="#serializederivedproofvalue"></a>, we obtain the signed derived (reveal)
document shown below.
</p>
<pre class="example nohighlight" title="Signed Derived Document"
data-include="TestVectors/prc/derivedRevealDocument.json"
data-include-format="text"></pre>
</section>
</section>

<section>
<h4>Baseline Enhanced Example</h4>
<p>
Expand Down

0 comments on commit 96710a8

Please sign in to comment.