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

Add discussion of xi c14n. #3

Merged
merged 11 commits into from
May 28, 2024
Merged

Add discussion of xi c14n. #3

Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
73de1ac
Update example credentials.
wes-smith May 27, 2024
1baa8f8
Update CBOR examples.
wes-smith May 27, 2024
ed0574b
Add discussion of signatureBitfield.
wes-smith May 27, 2024
397949d
Add c14n algorithms for PDF417 and MRZ.
wes-smith May 27, 2024
e172230
Update image examples.
wes-smith May 28, 2024
d168137
Update to use Unicode code point order.
wes-smith May 28, 2024
1974b38
Rework TerseBitstring... discussion.
wes-smith May 28, 2024
12e75f5
Add discussion of status list length.
wes-smith May 28, 2024
d6dc7c3
Add new status entry conversion algorithm.
wes-smith May 28, 2024
09fc204
Add barcode encoding discussion.
wes-smith May 28, 2024
4232703
Apply edits from code review (formatting, requirements langauge).
wes-smith May 28, 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
154 changes: 124 additions & 30 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,12 @@
"ISO/IEC JTC 1/SC 31"
],
publisher: "International Standards Organization"
},
"aamva-dl-id-card-design-standard": {
title: "AAMVA DL/ID Card Design Standard (2020)",
date: "2020",
href: "https://www.aamva.org/assets/best-practices,-guides,-standards,-manuals,-whitepapers/aamva-dl-id-card-design-standard-(2020)",
publisher: "American Association of Motor Vehicle Administrators"
}
},
lint: {"no-unused-dfns": false},
Expand Down Expand Up @@ -292,10 +298,12 @@ <h3>Driver's License Example</h3>
"issuer": "did:web:dmv.utopia.example",
"credentialStatus": {
"type": "TerseBitstringStatusListEntry",
"index": 283749
"terseStatusListBaseUrl": "dmv.utopia.gov/statuses/12345/status-lists"
wes-smith marked this conversation as resolved.
Show resolved Hide resolved
"terseStatusListIndex": 123567890
},
"credentialSubject": {
"type": "Pdf417Barcode"
"type": "UsDriversLicenseWithMandatoryFieldsPdf417Barcode",
"signatureBitfield": "uP_BA"
},
"proof": {
"type": "DataIntegrity",
Expand All @@ -314,19 +322,19 @@ <h3>Driver's License Example</h3>
</p>

<pre class="example nohighlight"
title="CBOR-LD compressed Verifiable Credential (137 bytes)">
{
1 => [ 32768, 32769, 32770], <span class="comment">// @context</span>
151 => [ 114, 160 ], <span class="comment">// type</span>
178 => 32782, <span class="comment">// issuer</span>
172 => { 150 => 162, 192 => 283749 }, <span class="comment">// credentialStatus</span>
174 => { 150 => 158 }, <span class="comment">// credentialSubject</span>
180 => { <span class="comment">// proof</span>
150 => 102, <span class="comment">// type</span>
198 => 32771, <span class="comment">// cryptosuite</span>
212 => 32783 <span class="comment">// verificationMethod</span>
208 => 214, <span class="comment">// proofPurpose</span>
210 => Uint8Array(65) [ ... ], <span class="comment">// proofValue</span>
title="CBOR-LD compressed Verifiable Credential (145 bytes)">
1281{
1 => [ 32768, 32769, 32770], <span class="comment">// @context</span>
155 => [ 116, 164 ], <span class="comment">// type</span>
192 => 174, <span class="comment">// issuer</span>
186 => { 154 => 166, 206 => 178, 208 => 1234567890 }, <span class="comment">// credentialStatus</span>
188 => { 154 => 172, 180 => h'753FF040 }, <span class="comment">// credentialSubject</span>
194 => { <span class="comment">// proof</span>
154 => 108, <span class="comment">// type</span>
214 => 4, <span class="comment">// cryptosuite</span>
224 => 230 <span class="comment">// verificationMethod</span>
228 => 176, <span class="comment">// proofPurpose</span>
210 => Uint8Array(65) [ ... ], <span class="comment">// proofValue</span>
}
}
</pre>
Expand Down Expand Up @@ -389,7 +397,7 @@ <h3>Employment Authorization Example</h3>
<span class="comment">// the value below is defined as a URL in the 'utopia/v1' context above</span>
"issuer": "did:web:immigration.utopia.example",
"credentialSubject": {
"type": "MachineReadableZone",
"type": "CompleteMrzBarcode",
},
"proof": {
"type": "DataIntegrity",
Expand All @@ -414,17 +422,17 @@ <h3>Employment Authorization Example</h3>
</p>

<pre class="example nohighlight"
title="CBOR-LD compressed Verifiable Credential (137 bytes)">
title="CBOR-LD compressed Verifiable Credential (120 bytes)">
{
1 => [ 32768, 32769, 32770], <span class="comment">// @context</span>
151 => [ 114, 160 ], <span class="comment">// type</span>
178 => 32782, <span class="comment">// issuer</span>
174 => { 150 => 158 }, <span class="comment">// credentialSubject</span>
180 => { <span class="comment">// proof</span>
150 => 102, <span class="comment">// type</span>
198 => 32771, <span class="comment">// cryptosuite</span>
212 => 32783 <span class="comment">// verificationMethod</span>
208 => 214, <span class="comment">// proofPurpose</span>
155 => [ 116, 176 ], <span class="comment">// type</span>
208 => 194, <span class="comment">// issuer</span>
204 => { 154 => 192 }, <span class="comment">// credentialSubject</span>
210 => { <span class="comment">// proof</span>
154 => 108, <span class="comment">// type</span>
226 => 4, <span class="comment">// cryptosuite</span>
236 => 242 <span class="comment">// verificationMethod</span>
240 => 196, <span class="comment">// proofPurpose</span>
210 => Uint8Array(65) [ ... ], <span class="comment">// proofValue</span>
}
}
Expand Down Expand Up @@ -490,16 +498,32 @@ <h3>OpticalBarcodeCredential</h3>
</p>

<p>
The `credentialSubject` of an `OpticalBarcodeCredential` is either a
`Pdf417Barcode` or a `MachineReadableZone`. A `Pdf417Barcode` signifies that
The `credentialSubject` of an `OpticalBarcodeCredential` is either of type
`UsDriversLicenseWithMandatoryFieldsPdf417Barcode` or a `CompleteMrzBarcode`. A
`UsDriversLicenseWithMandatoryFieldsPdf417Barcode` signifies that
the <a>verifiable credential</a> secures the PDF417 barcode on the physical
document as well as the information expressed in the
<a>verifiable credential</a>. A `MachineReadableZone` signifies that
<a>verifiable credential</a>. A `CompleteMrzBarcode` signifies that
the <a>verifiable credential</a> secures the machine-readable zone on the
physical document as well as the information expressed in the
<a>verifiable credential</a>.
</p>

<p>
If an `OpticalBarcodeCredential` is of type `UsDriversLicenseWithMandatoryFieldsPdf417Barcode`,
there is a REQUIRED additional field `signatureBitfield` that contains information about which fields
in the PDF417 are digitally signed. `signatureBitfield` MUST be a three byte/24 bit value that is
multibase-base64url encoded for a total of 5 characters in the JSON-LD credential. There are 22
mandatory fields in an AAMVA compliant driver's license PDF417 [[aamva-dl-id-card-design-standard]],
and the first 22 bits of the `signatureBitfield` value correspond to these fields. Each AAMVA mandatory
field begins with a three character element ID (e.g. `DBA` for document expiration date). To construct
a mapping between bits in the `signatureBitfield` value and these fields, sort these element IDs lexically.
Then, if a bit in position `i` of `signatureBitfield` is `1`, then the AAMVA mandatory field in
position `i` of the sorted element IDs is digitally signed. The last two bits in `signatureBitfield`
MUST be `0`. For more information, see
<a href="#create-opticaldatahash">Section 3.5.4</a>.
</p>

<p>
In order to achieve as much compression as possible, it is RECOMMENDED that the
`issuer` and `verificationMethod` fields utilize terms from a JSON-LD Context,
Expand Down Expand Up @@ -527,10 +551,12 @@ <h3>OpticalBarcodeCredential</h3>
"issuer": "did:web:dmv.utopia.example",
"credentialStatus": <span class="highlight">{
"type": "TerseBitstringStatusListEntry",
"index": 283749
"terseStatusListBaseUrl": "dmv.utopia.gov/statuses/12345/status-lists"
"terseStatusListIndex": 123567890
}</span>,
"credentialSubject": {
"type": <span class="highlight">"Pdf417Barcode"</span>,
<span class="highlight">"type": "UsDriversLicenseWithMandatoryFieldsPdf417Barcode"</span>,
<span class="highlight">"signatureBitfield": "uP_BA"</span>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In hindsight, this probably should have been protectedFields or something along those lines. The bitfield doesn't have to do with the signature, it's the fields that are protected by the signature.

}
}
</pre>
Expand Down Expand Up @@ -875,6 +901,74 @@ <h4>Hashing (ecdsa-xi-2023)</h4>

</section>

<section>
<h4> Create opticalDataHash</h4>

<section>
<h5>`UsDriversLicenseWithMandatoryFieldsPdf417Barcode` Credentials</h5>
<ol class="algorithm">
<li>
Set |dataToCanonicalize| to an empty array.
</li>
<li>
Set |bitfieldDecoded| to be first 22 bits of the length 24 bitstring resulting from decoding `credentialSubject.signatureBitfield`
from multibase-base64url to binary.
</li>
<li>
Set |fieldsAlphabetized| to be an array containing the 22 AAMVA mandatory PDF417 Element IDs
[[aamva-dl-id-card-design-standard]] sorted in lexical order (i.e. ['DAC', 'DAD' ... 'DDG']).
</li>
<li>
For each bit with value `1` in |bitfieldDecoded|:
<ol class="algorithm">
<li>
Set the string |fieldName| to |fieldsAlphabetized|[|i|], where |i| is the index of the bit in |bitfieldDecoded|.
</li>
<li>
Set the string |fieldData| to the data that will be in the PDF417 associated with that field name.
</li>
<li>
Concatenate |fieldData| to the end of |fieldName|, and append the result to |dataToCanonicalize|.
</li>
</ol>
</li>
<li>
Set |canonicalizedData| to the result of lexically sorting |dataToCanonicalize| and then applying a join operation
wes-smith marked this conversation as resolved.
Show resolved Hide resolved
to create a single string from the array.
</li>
<li>
Hash |canonicalizedData| and return the result.
</li>
</ol>
</section>

<section>
<h5>`CompleteMrzBarcode` Credentials</h5>
<ol class="algorithm">
<li>
Set |dataToCanonicalize| to an empty array.
</li>
<li>
For each line in the Machine Readable Zone on the credential:
<ol class="algorithm">
<li>
Set |mrzLine| to a string containing the data in that line.
</li>
<li>
Append a newline character to the end of |mrzLine| and append |mrzLine| to |dataToCanonicalize|.
</li>
</ol>
</li>
<li>
Set |canonicalizedData| to the result of lexically sorting |dataToCanonicalize| and then applying a join operation
to create a single string from the array.
</li>
<li>
Hash |canonicalizedData| and return the result.
</li>
</ol>
</section>
</section>
<section>
<h4>Proof Configuration (ecdsa-xi-2023)</h4>

Expand Down
Loading