Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Split verification instructions by credential. #11

Merged
merged 5 commits into from
Jul 15, 2024
Merged

Split verification instructions by credential. #11

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c38e821
Split verification instructions by credential.
wes-smith Jul 15, 2024
fb73f88
Update base encoding for QR credentials.
wes-smith Jul 15, 2024
0dc1186
Split credential creation example by credential.
wes-smith Jul 15, 2024
944ed18
Fix grammar bug.
wes-smith Jul 15, 2024
e5bc086
Fix markup issues.
wes-smith Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 153 additions & 87 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1128,18 +1128,14 @@ <h2> Test Vectors</h2>
</p>
<section>
<h3>Creating VCBs</h3>
<p>
We start with the data that will be signed by the VCB (i.e an MRZ and
mandatory AAMVA fields from a PDF417):
</p>
<pre class="example nohighlight"
title="A Machine Readable Zone that might appear on a Utopia EAD">
IAUTO0000007010SRC0000000701<<
8804192M2601058NOT<<<<<<<<<<&lt5
SMITH&#60&#60JOHN<<<<<<<<<<<<<<<<<<<
</pre>
<pre class="example nohighlight"
title="Fields from a PDF417 that might appear on a Utopia Driver's License">
<section>
<h4>Utopia Driver's License</h4>
<p>
We start with the data that will be signed by the VCB (i.e. mandatory AAMVA fields
wes-smith marked this conversation as resolved.
Show resolved Hide resolved
from a PDF417):
</p>
<pre class="example nohighlight"
title="Fields from a PDF417 that might appear on a Utopia Driver's License">
DACJOHN
DADNONE
DAG123 MAIN ST
Expand All @@ -1162,54 +1158,41 @@ <h3>Creating VCBs</h3>
DDEN
DDFN
DDGN
</pre>
<section>
<h4>
</pre>
<section>
<h5>
Creating `opticalDataBytes`
</h4>

<p>
</h5>
<p>
Assume for simplicity that the only data in the PDF417 that you want to sign is first
name (DAC), last name (DCS), and license number (DAQ). The bitstring value for use in
`protectedComponentIndex` is then |100000100000000000100000|, and the value of
`protectedComponentIndex` is "uggAg". Applying
<a href="#create-opticaldatabytes">Algorithm 3.5.4.1</a>, we get
</p>
<pre class="example nohighlight"
</p>
<pre class="example nohighlight"
title="Data from the canonicalization of a Utopia Driver's License">
canonicalizedData = 'DACJOHN\nDAQ987654321\nDCSSMITH\n'
opticalDataBytes:
[188, 38, 200, 146, 227, 213, 90, 250,
50, 18, 126, 254, 47, 177, 91, 23,
64, 129, 104, 223, 136, 81, 116, 67,
136, 125, 137, 165, 117, 63, 152, 207]
</pre>
</pre>
</section>
<p>
For the EAD, we apply <a href="#create-opticaldatabytes">Algorithm 3.5.4.2</a>:
</p>
<pre class="example nohighlight"
title="Data from the canonicalization of a Utopia EAD MRZ">
canonicalizedData = 'IAUTO0000007010SRC0000000701<<\n8804192M2601058NOT<<<<<<<<<<
&lt5\nSMITH<&#60JOHN<<<<<<<<<<<<<<<<<<<\n'
opticalDataBytes:
[8, 198, 126, 183, 25, 160, 166, 112,
254, 184, 189, 47, 225, 211, 125, 210,
132, 137, 45, 86, 169, 28, 57, 165,
46, 253, 9, 137, 145, 42, 192, 113]
</pre>
</section>
<p>
We now can use these hash values with
We now can use this hash value with
<a href="#hashing-ecdsa-xi-2023">Algorithm 3.5.3</a> to sign the VC.
Executing <a href="#credential-creation">Algorithm 3.2</a> with a
`BitstringStatusListCredential`, we get the following JSON-LD VCs:
</p>
<section>
<h4>
Example VCs
</h4>
<pre class="example nohighlight"
title="A JSON-LD VC for a Utopia Driver's License VCB">
`BitstringStatusListCredential`, we get the following JSON-LD VC:
</p>
<section>
<h5>
Example VC
</h5>
<pre class="example nohighlight"
title="A JSON-LD VC for a Utopia Driver's License VCB">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
Expand Down Expand Up @@ -1238,9 +1221,129 @@ <h4>
"proofValue": "z4g6G3dAZhhtPxPWgFvkiRv7krtCaeJxjokvL46fchAFCXEY3FeX2vn46MDgBaw779g1E1jswZJxxreZDCrtHg2qH"
}
}
</pre>
</section>
<section>
<h4>CBOR-LD Compression and Encoding</h4>
<p>
We can now apply CBOR-LD compression to this VC. Here we use the newest
version of CBOR-LD, however at the end of the section we provide VCBs
encoded using older versions of CBOR-LD for interoperability testing
with CBOR-LD implementations that are not up to date.
</p>
<p>
For this specficiation, we have reserved the CBOR-LD registry entry
with value 100 (i.e. these payloads will begin with tag 0x0664). The parameters
to encode using CBOR-LD, which can be found in the registry in the CBOR-LD
specification, are then as follows:
</p>
<pre class="example nohighlight"
title="CBOR-LD encoding parameters">
registryEntryId: 100
typeTable:
{
"context":
{
"https://www.w3.org/ns/credentials/v2": 32768,
"https://w3id.org/vc-barcodes/v1": 32769,
"https://w3id.org/utopia/v2": 32770
},

"https://w3id.org/security#cryptosuiteString":
{
"ecdsa-rdfc-2019": 1,
"ecdsa-sd-2023": 2,
"eddsa-rdfc-2022": 3,
"ecdsa-xi-2023": 4
}
}
</pre>
This results in the following encoded credential:
<pre class="example nohighlight"
title="A CBOR-LD compressed Utopia Driver's License VC">
d90664a60183198000198001198002189d82187618a418b8a3189c18a618ce18b218d01ae592208118baa2189c18a018a8447582002018be18aa18c0a5189c186c18d60418e018e618e258417ab7c2e56b49e2cce62184ce26818e15a8b173164401b5d3bb93ffd6d2b5eb8f6ac0971502ae3dd49d17ec66528164034c912685b8111bc04cdc9ec13dbadd91cc18e418ac

diagnostic:
1636(
{
1: [32768, 32769, 32770],
157: [118, 164],
184: {156: 166, 206: 178, 208: 3851559041},
186: {156: 160, 168: h'75820020'},
190: 170,
192: {
156: 108,
214: 4,
224: 230,
226: h'7AB7C2E56B49E2CCE62184CE26818E15A8B173164401B5D3BB93FFD6D2B5EB8F6AC0971502AE3DD49D17EC66528164034C912685B8111BC04CDC9EC13DBADD91CC',
228: 172
}
}
)
</pre>
<p>
Encoding the Driver's License CBORLD as base64url and inserting the result into the
PDF417 bytes in the 'ZZA' field in the 'ZZ' subfile:
</p>
<pre class="example nohighlight"
title="Bytes from a PDF417 including an encoded Utopia Driver's License VCB">
bytes(@\n\x1e\rANSI000000090002DL00410267ZZ03080162DLDAQF987654321\nDCSSMITH\nDDEN\nDACJOHN\nDDFN\nDADNONE\nDDGN\nDCAC\nDCBNONE\nDCDNONE\nDBD01012024\nDBB04191988\nDBA04192030\nDBC1\nDAU069 IN\nDAYBRO\nDAG123 MAIN ST\nDAIANYVILLE\nDAJUTO\nDAKF87P20000 \nDCFUTODOCDISCRIM\nDCGUTO\nDAW158\nDCK1234567890\nDDAN\rZZZZA2QZkpgGDGYAAGYABGYACGJ2CGHYYpBi4oxicGKYYzhiyGNAa5ZIggRi6ohicGKAYqER1ggAgGL4YqhjApRicGGwY1gQY4BjmGOJYQXq3wuVrSeLM5iGEziaBjhWosXMWRAG107uT_9bSteuPasCXFQKuPdSdF-xmUoFkA0yRJoW4ERvATNyewT263ZHMGOQYrA==\r)
</pre>
<p>
The above can now be turned into a barcode:
</p>
<figure id="dl-barcode">
<img style="margin: auto; display: block; border-radius:15px; width: 80%;"
src="diagrams/dl-barcode.png"
alt="A VCB from a Utopia driver's license.">
<figcaption style="text-align: center;">
A VCB from a Utopia driver's license.
</figcaption>
</figure>
</section>
</section>
<section>
<h4>Utopia Employment Authorization Document</h4>

<p>
We start with the data that will be signed by the VCB (i.e an MRZ):
</p>
<pre class="example nohighlight"
title="A JSON-LD VC for a Utopia EAD VCB">
title="A Machine Readable Zone that might appear on a Utopia EAD">
IAUTO0000007010SRC0000000701<<
8804192M2601058NOT<<<<<<<<<<&lt5
SMITH&#60&#60JOHN<<<<<<<<<<<<<<<<<<<
</pre>
<section>
<h5>
Creating `opticalDataBytes`
</h5>
<p>
For the EAD, we apply <a href="#create-opticaldatabytes">Algorithm 3.5.4.2</a>:
</p>
<pre class="example nohighlight"
title="Data from the canonicalization of a Utopia EAD MRZ">
canonicalizedData = 'IAUTO0000007010SRC0000000701<<\n8804192M2601058NOT<<<<<<<<<<
&lt5\nSMITH<&#60JOHN<<<<<<<<<<<<<<<<<<<\n'
opticalDataBytes:
[8, 198, 126, 183, 25, 160, 166, 112,
254, 184, 189, 47, 225, 211, 125, 210,
132, 137, 45, 86, 169, 28, 57, 165,
46, 253, 9, 137, 145, 42, 192, 113]
</pre>
</section>
<p>
We now can use this hash value with
<a href="#hashing-ecdsa-xi-2023">Algorithm 3.5.3</a> to sign the VC.
Executing <a href="#credential-creation">Algorithm 3.2</a> without
adding status, we get the following JSON-LD VC:
</p>
<section>
<h5>
Example VC
</h5>
<pre class="example nohighlight"
title="A JSON-LD VC for a Utopia EAD VCB">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
Expand All @@ -1263,12 +1366,13 @@ <h4>
"proofValue": "z4B8AQgjwgsEdcPEZkrkK2mTVKn7qufoDgDkv9Qitf9tjxQPMoJaGdXwDrThjp7LUdvzsDJ7UwYu6Xpm9fjbo6QnJ"
}
}
</pre>
</pre>
</section>
</section>
<section>
<h4>CBOR-LD Compression and Encoding</h4>
<p>
We can now apply CBOR-LD compression to these VCs. Here we use the newest
We can now apply CBOR-LD compression to this VC. Here we use the newest
version of CBOR-LD, however at the end of the section we provide VCBs
encoded using older versions of CBOR-LD for interoperability testing
with CBOR-LD implementations that are not up to date.
Expand Down Expand Up @@ -1300,29 +1404,7 @@ <h4>CBOR-LD Compression and Encoding</h4>
}
}
</pre>
This results in the following encoded credentials:
<pre class="example nohighlight"
title="A CBOR-LD compressed Utopia Driver's License VC">
d90664a60183198000198001198002189d82187618a418b8a3189c18a618ce18b218d01ae592208118baa2189c18a018a8447582002018be18aa18c0a5189c186c18d60418e018e618e258417ab7c2e56b49e2cce62184ce26818e15a8b173164401b5d3bb93ffd6d2b5eb8f6ac0971502ae3dd49d17ec66528164034c912685b8111bc04cdc9ec13dbadd91cc18e418ac

diagnostic:
1636(
{
1: [32768, 32769, 32770],
157: [118, 164],
184: {156: 166, 206: 178, 208: 3851559041},
186: {156: 160, 168: h'75820020'},
190: 170,
192: {
156: 108,
214: 4,
224: 230,
226: h'7AB7C2E56B49E2CCE62184CE26818E15A8B173164401B5D3BB93FFD6D2B5EB8F6AC0971502AE3DD49D17EC66528164034C912685B8111BC04CDC9EC13DBADD91CC',
228: 172
}
}
)
</pre>
This results in the following encoded credential:
<pre class="example nohighlight"
title="A CBOR-LD compressed Utopia EAD VC">
d90664a50183198000198001198002189d82187618a418baa1189c18a218be18ae18c0a5189c186c18d20418dc18e218de58417a9ec7f688f60caa8c757592250b3f6d6e18419941f186e1ed4245770e687502d51d01cd2c2295e4338178a51a35c2f044a85598e15db9aef00261bc5c95a744e718e018b0
Expand All @@ -1345,31 +1427,15 @@ <h4>CBOR-LD Compression and Encoding</h4>
)
</pre>
<p>
Encoding the Driver's License CBORLD as base64url and inserting the result into the
PDF417 bytes in the 'ZZA' field in the 'ZZ' subfile:
</p>
<pre class="example nohighlight"
title="Bytes from a PDF417 including an encoded Utopia Driver's License VCB">
bytes(@\n\x1e\rANSI000000090002DL00410267ZZ03080162DLDAQF987654321\nDCSSMITH\nDDEN\nDACJOHN\nDDFN\nDADNONE\nDDGN\nDCAC\nDCBNONE\nDCDNONE\nDBD01012024\nDBB04191988\nDBA04192030\nDBC1\nDAU069 IN\nDAYBRO\nDAG123 MAIN ST\nDAIANYVILLE\nDAJUTO\nDAKF87P20000 \nDCFUTODOCDISCRIM\nDCGUTO\nDAW158\nDCK1234567890\nDDAN\rZZZZA2QZkpgGDGYAAGYABGYACGJ2CGHYYpBi4oxicGKYYzhiyGNAa5ZIggRi6ohicGKAYqER1ggAgGL4YqhjApRicGGwY1gQY4BjmGOJYQXq3wuVrSeLM5iGEziaBjhWosXMWRAG107uT_9bSteuPasCXFQKuPdSdF-xmUoFkA0yRJoW4ERvATNyewT263ZHMGOQYrA==\r)
</pre>
<p>
Encoding the EAD CBORLD as base45-multibase and prepending 'VC1-':
</p>
<pre class="example nohighlight"
title="An encoded Utopia EAD VCB">
VC1-RSJRPWCR803A3P0098G3A3-B02-J743853U53KGK0XJ6MKJ1OI0M.FO053.33963DN04$RAQS+4SMC8C3KM7VX4VAPL9%EILI:I1O$D:23%GJ0OUCPS0H8D2FB9D5G00U39.PXG49%SOGGB*K$Z6%GUSCLWEJ8%B95MOD0P NG-I:V8N63K53
</pre>
<p>
The above can now be turned into barcodes:
The above can now be turned into a QR code:
</p>
<figure id="dl-barcode">
<img style="margin: auto; display: block; border-radius:15px; width: 80%;"
src="diagrams/dl-barcode.png"
alt="A VCB from a Utopia driver's license.">
<figcaption style="text-align: center;">
A VCB from a Utopia driver's license.
</figcaption>
</figure>
</section>
<section>
<h5>Employment Authorization Document</h5>
Expand Down
Loading