Re: DID Key Management Harmonization Proposal #1

A side note suggestion on extensibility. 

Because the the DID method identifier is meant to uniquely namespace DIDs and the associated methods, it provides a way of extending DID documents without
collision, that is, a field name at the first level of the did document that is the did method name can be used to isolate any non standard data that someone wants to put in the DID document without running the risk of collision. This works for both JSON-LD and naive JSON.  All other field names at the first level of a DID document are then reserved for standarization purposes.



> On 09 Jan 2018, at 02:09 , =Drummond Reed <drummond.reed@evernym.com> wrote:
> 
> Manu, sorry to be slow in responding, this weekend my wife threw me a surprise party and it threw everything off. See inline.
> 
> On Fri, Jan 5, 2018 at 1:50 PM, Manu Sporny <msporny@digitalbazaar.com <mailto:msporny@digitalbazaar.com>> wrote:
> This is an attempt at providing a harmonized DID Key Management
> proposal. It contains aspects that will most likely be distasteful for
> many in the group, but achieves all of the following requirements that
> have surfaced during the DID Spec Hardening discussions:
> 
> R1. All data structures can be treated as plain 'ol JSON.
> R2. All data structures can be extended via JSON-LD.
> R3. All data structures are compatible with both a tree-based model AND
>     a graph-based model (no philosophical nor technical conflicts).
> R4. There is a simple algorithm for locating public keys owned by
>     an entity represented by the DID.
> R5. Authentication and encryption use cases are supported.
> R6. Design allowances are made for authentication via biometrics, smart
>     contract, and oracles.
> R7. Ambient authority is protected against to a certain extent.
> R8. Non-correlation use cases are supported.
> R9. There is a very clear extensibility story both for JSON and JSON-LD.
> R10. It is clear where non-owned public keys go.
> R11. Multiple encoding types for public keys are supported with a clear
>      extensibility story for other types of cryptographic primitives.
> 
> It's a good list of requirements—I was going to type up the same thing after the last DID spec closure call but you beat me too it.
>  
> 
> The suggested high-level DID Document data structure is this:
> 
> {
>   "id": "did:example:123456789abcdefg",
>   "publicKeys": [ ... list of public key objects ... ],
>   "authentication": [ ... list of authentication suites ... ],
>   "services": [ ... list of services ... ]
> }
> 
> In a discussion about this proposal with the DIF Identifiers, Names, and Discovery WG today, it was agreed these were the core properties that the "minimal DID document" contingent is focused on, with the one exception that, given this architecture, "encryption" might also be on the "core properties" list. In other words, if the idea is to separate the list of public key objects from the list of authentication "suite" or encryption "suite" purposes, then encryption seems nearly as important as authentication.
>  
> 
> If we want to (eventually) support encryption, biometrics, smart
> contracts, oracles, etc.... we could extend like so:
> 
> {
>   // "cryptographic" building blocks
>   "publicKeys": [ { ... }, ... ],
>   "biometricTemplates": [ { ... }, ... ],
>   "smartContracts": [ { ... }, ... ],
>   "oracles": [ { ... }, ... ],
> 
>   // applications/purposes
>   "authentication": [ { ... }, ... ],
>   "encryption": [ { ... }, ... ], // unsure about this one
> 
> What is the uncertainty about encryption? Why is it a second-class citizen to authentication? It's the other primary usage of public key cryptography. To quote from the Wikipedia page <https://en.wikipedia.org/wiki/Public-key_cryptography>:
> 
> Public key cryptography, or asymmetrical cryptography, is any cryptographic system that uses pairs of keys <https://en.wikipedia.org/wiki/Cryptographic_key>: public keys which may be disseminated widely, and private keys which are known only to the owner. This accomplishes two functions: authentication <https://en.wikipedia.org/wiki/Authentication_protocol>, where the public key verifies a holder of the paired private key sent the message, and encryption <https://en.wikipedia.org/wiki/Encryption>, where only the paired private key holder can decrypt the message encrypted with the public key.
> 
>  
> 
>   // verifiable credentials
>   "credentials": [ { ... }, ... ],
> 
>   // services
>   "services": [ { ... }, ... ]
> }
> 
> While this is a good example of how the spec may be extended, as discussed on the last Closure Call, we need to avoid going down the slippery slope of defining anything outside of the core properties in the main DID spec. Agreed?
>  
> 
> Now to define what each of these things do.
> 
> publicKeys
> ----------
> 
> This property lists any public key cryptographic material that is owned
> by the entity represented by the DID (or a delegate). Biometric
> material, smart contracts, etc. do not belong in this field and an error
> should be thrown by processors if any non-owned non-public key data is
> found in the publicKeys field.
> 
> While it's an interesting idea, by why tests would such an error be detected?
>  
> 
> This field MUST NOT be directly used for authentication purposes,
> instead the `authentication` field SHOULD be used, which will reference
> a key in this publicKeys array (if the authentication suite is a public
> key based authentication suite).
> 
> An example of the contents of this field are here (but don't pay too
> much attention to it as we can tweak what goes in the field later):
> 
> {
>   ...
>   "publicKeys": [{
>     "id": "#key1",
>     "type": "RsaSigningKey2017",
>     "owner": "did:example:123456789abcdefg",
>     "publicKeyPem": "-----BEGIN KEY...END KEY-----\r\n",
>     "publicKeyJwk": {...}
>   }],
>   ...
> }
> 
> Note that the cryptographic purpose of the key is included in the type
> field, but there is no "purpose" field in the key by design. More on
> this below in the section labelled "Authentication Algorithm".
> 
> authentication
> --------------
> 
> This property lists all of the authentication suites (and references to
> cryptographic material) that the entity represented by the DID deems
> valid for the purposes of authentication. For example:
> 
> {
>   ...
>   "authentication": [{
>     "type": "RsaKeyBasedAuthentication2017",
>     "publicKey": "#key1"
>   }],
>   ...
> }
> 
> Note that this DOES NOT mean that an application, such as a website
> performing login authentication, must accept all authentication
> mechanisms listed in the DID Document. The list of acceptable
> authentication mechanisms will be the union of what the DID Document
> 
> Markus pointed out that he believes you meant "intersection" not "union", yes?
>  
> specifies and what the application checking authentication accepts.
> 
> Authentication Algorithm
> ------------------------
> 
> Given the following DID Document:
> 
> {
>   "id": "did:example:123456789abcdefg",
>   "publicKeys": [{
>     "id": "#key1",
>     "type": "RsaSigningKey2017",
>     "owner": "did:example:123456789abcdefg",
>     "publicKeyPem": "-----BEGIN KEY...END KEY-----\r\n",
>     "publicKeyJwk": {...}
>   }],
>   "authentication": [{
>     "type": "RsaKeyBasedAuthentication2017",
>     "publicKey": "#key1"
>   }],
>   ...
> }
> 
> The authentication algorithm would be the following:
> 
> Assume an authentication server, an authentication client, and a DID
> Document (ddoc).
> 
> 1. The authentication server provides either a signature challenge to
>    the authentication client, or there is a mechanism that is capable
>    of automatically generating the signature challenge.
> 2. The authentication client uses a key listed in ddoc.authentication to
>    digitally sign the challenge and deliver it to the authentication
>    server.
> 3. The authentication server fetches the DID Document and looks in
>    ddoc.authentication for key used in the signed challenge
>    (challenge.signature.creator).
> 4. If the key object is a reference, the authentication server looks in
>    ddoc.publicKeys for the key.
> 5. If the key is found, and it meets the requirements specified for
>    the authentication suite (e.g. key size >= 2KB, secp256k1, etc.),
>    the public key information is used to check the signature on the
>    challenge.
> 
> There are certainly variations to the algorithm that we can discuss, but
> that would be the general structure of it, which would be fairly simple
> to implement in code, operating using a stock JSON processor.
> 
> 
> Given the growing interest in DID Auth—and that what you are proposing is one potential definition of a DID Auth protocol—this could be a good step in that direction. On the DIF call we discussed whether in fact this isn't better described as a service, albiet one that does not require a separate service endpoint (the way this particular protocol flow works—a variant that would send the challenge out-of-band, such as to a mobile phone, would require that endpoint).
> 
> What are your thoughts on why this is not a service?
> 
>  
> 
> Meeting the Requirements
> ------------------------
> 
> Just FYI, I really appreciate this analysis.
>  
> 
> > R1. All data structures can be treated as plain 'ol JSON.
> 
> This requirement is met because we have not used any features of JSON-LD
> or graph-based data models.
> 
> > R2. All data structures can be extended via JSON-LD.
> 
> This requirement is met by adding a JSON-LD Context to the DID Document
> that defines extensions.
> 
> > R3. All data structures are compatible with both a tree-based model
> > AND a graph-based model (no philosophical nor technical conflicts).
> 
> This requirement is met because we force the document to have a
> well-known tree-based model with an algorithm that assumes a tree-based
> layout. JSON-LD processors could force the layout using JSON-LD Framing.
> 
> > R4. There is a simple algorithm for locating public keys owned by an
> > entity represented by the DID.
> 
> This requirement is met by just looking in the `publicKeys` property.
> 
> > R5. Authentication and encryption use cases are supported.
> 
> The authentication requirement is met as demonstrated above. The
> encryption use case is a simple variation on the authentication use case.
> 
> > R6. Design allowances are made for authentication via biometrics,
> > smart contract, and oracles.
> 
> This requirement is met by defining new authentication suites and
> specific containers for other types of cryptographic material as
> outlined above.
> 
> > R7. Ambient authority is protected against to a certain extent.
> 
> This requirement is met by specifically NOT including an
> application/purpose in the key material and instead forcing that
> information to be fetched through other means (e.g. the authentication
> property).
> 
> There is still a danger that one completely mis-implements the
> specification and just searches through publicKeys. A mitigation for
> this would be to remove the publicKeys property, which a few seem like
> they would be unlikely to do.
> 
> Speaking for the minimalist worldview, I would say the publicKeys property is the keystone of this proposal ;-)
>  
> 
> > R8. Non-correlation use cases are supported.
> 
> This requirement is met by ensuring that the DID Method doesn't support
> any mechanism that would lead to correlation (such as certain types of
> public keys or biometrics, etc.).
> 
> > R9. There is a very clear extensibility story both for JSON and
> > JSON-LD.
> 
> This requirement is met by pure JSON implementations either extending
> via JSON-LD and then hard-coding to the JSON-LD properties OR by
> prepending all DID Method specific extensions with the DID Scheme:
> 
> e.g. uportSmartContractFoo or sovAccumulatorBar
> 
> Although, I strongly advise against the latter as the former is just as
> easy to do.
> 
> Agreed.
>  
> 
> > R10. It is clear where non-owned public keys go.
> 
> This requirement is met by allowing non-owned public keys to go anywhere
> in the document they are needed, but specifically NOT in the publicKeys
> array, which are reserved for public keys managed by the entity
> represented by the DID (or a delegate).
> 
> > R11. Multiple encoding types for public keys are supported with a
> > clear extensibility story for other types of cryptographic
> > primitives.
> 
> This requirement is met via the publicKeyPem and publicKeyJwk design
> pattern where the encoding is a part of the property name. Other types
> of cryptographic primitives are supported by creating new, specific bags
> for that information.
> 
> I'll stop there to see if we have buy in for this approach. There are
> some corner cases and security implications that still need to be
> discussed, but those discussions are easier to have once we can settle
> on what the top-level branches of the document could look like.
> 
> Agreed.
>  
> 
> What did I miss? Does the approach above create any new problems? Are
> there remaining concerns that would not allow us to proceed down this path?
> 
> I would very strongly encourage others on the list who care about this topic to weigh in on this Harmonization Proposal #1, because I think it merits serious consideration. I propose we make it the main focus of the DID portion of tomorrow's W3C Credentials Community Group call, and then prepare a Google doc version of it for markup and comment in preparation for Thursday's DID Spec Closure Call.
> 
> Again, thanks to Manu for such a cogent writeup.
> 
> =Drummond 
>  
> 
> -- manu
> 
> --
> Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
> Founder/CEO - Digital Bazaar, Inc.
> blog: The State of W3C Web Payments in 2017
> http://manu.sporny.org/2017/w3c-web-payments/ <http://manu.sporny.org/2017/w3c-web-payments/>

Samuel M. Smith Ph.D.   Founder
smith.sam@prosapien.com 
ProSapien LLC
242 East 600 North, Lindon Utah 84042-1662 USA
Office 1.801.768-2769
Mobile 1.801.592.8230
Skype: samuelmsmith
http://www.prosapien.com/ 

NOTICE: This electronic mail message, together with any attachments contains information
that may be copyrighted, confidential, proprietary, and/or legally privileged of and/or by 
ProSapien LLC. This  electronic mail message is intended solely for the use of
the individual or entity originally named as the intended recipient. If you are not the intended
recipient, and have received this message in error, please return immediately this message