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 publicKeyMultibase definition. #103

Merged
merged 4 commits into from
May 15, 2021
Merged

Add publicKeyMultibase definition. #103

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8c5ef90
Add publicKeyMultibase definition.
msporny May 8, 2021
413c48b
Fix minor syntax issues in publicKeyMultibase description.
msporny May 8, 2021
95fe348
Expand details and advice for publicKeyMultibase.
msporny May 11, 2021
924eea4
Apply suggestions from Kyle, Markus, and Orie to publicKeyMultibase.
msporny May 14, 2021
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
43 changes: 43 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1965,6 +1965,11 @@ <h3>keyAgreement</h3>
<section id="publicKeyBase58" about="https://w3id.org/security#publicKeyBase58"
typeof="rdf:Property">
<h3>publicKeyBase58</h3>
<p class="note" title="The publicKeyBase58 property is deprecated.">
The `publicKeyBase58` property is deprecated. New cryptography suite creators
and developers are advised to use the `publicKeyMultibase` property for
encoding public key parameters.
</p>
<p>
A public key Base58 property is used to specify the base58-encoded version of the
public key.
Expand Down Expand Up @@ -2060,6 +2065,11 @@ <h3>publicKeyPem</h3>
<section id="publicKeyHex" about="https://w3id.org/security#publicKeyHex"
typeof="rdf:Property">
<h3>publicKeyHex</h3>
<p class="note" title="The publicKeyHex property is deprecated.">
The `publicKeyHex` property is deprecated. New cryptography suite creators
and developers are advised to use the `publicKeyMultibase` property for encoding
public key parameters.
</p>
<p>
A <code>publicKeyHex</code> property is used to specify the hex-encoded version of the public key, based on <a href="https://tools.ietf.org/html/rfc4648#section-8">section 8 of rfc4648</a>. Hex encoding is also known as Base16 encoding.
</p>
Expand All @@ -2085,6 +2095,39 @@ <h3>publicKeyHex</h3>
</pre>
</section>

<section id="publicKeyMultibase" about="https://w3id.org/security#publicKeyMultibase"
typeof="rdf:Property">
<h3>publicKeyMultibase</h3>
<p>
The public key multibase property is used to specify the multibase-encoded
version of a public key. Each key type definition is expected to specify
one or more required encoding bases. Specifying only a single encoding
base per key type is preferable as it reduces the burden to reach broad
interoperability.
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm a bit worried that there's quite a bit of tribal knowledge in this. For example, how do I encode a nist p256 key here? How do I specify the encoding. If this is meant to be documentation to be "hey this thing exists" then this is fine, but if we're actually expecting people to build interoperable software against this definition they'll undoubtedly get stuck.

For specific action items I'd like to see, I'd like to see us reference how encoding works by directly referencing multibase and additionally reference how multicodec table is used and finally include how serialization of the bytes should work as well.

I'm all for this additional change, but I think this is a bit too light to actually be something that someone without prior knowledge could implement.

Copy link
Collaborator

Choose a reason for hiding this comment

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

yes, probably also a good idea to always recommend compressed form keys.

Copy link
Collaborator

Choose a reason for hiding this comment

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

see also multiformats/multicodec#210

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I have applied suggestions from @kdenhartog, @peacekeeper, and @OR13 in 924eea4.

If you want further changes, please suggest concrete spec text -- it's hard to read minds and then write spec text. :P

</p>
<dl>
<dt>Status</dt>
<dd property="vs:term_status">unstable</dd>
<dt>Domain</dt>
<dd>Key</dd>
<dt>Range</dt>
<dd>xsd:string</dd>
</dl>
<p>
The following example demonstrates the expression of a public key
in multibase format.
</p>
<pre class="example prettyprint language-jsonld">
{
"id": "did:example:123#zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV",
"type": "Ed25519VerificationKey2020",
"controller": "did:example:123",
"publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
}
</pre>

</section>

<section id="publicKeyService" about="https://w3id.org/security#publicKeyService"
typeof="rdf:Property">
<h3>publicKeyService</h3>
Expand Down