KERI event stream - events that effect did document key state #46
Conversation
…ing events Signed-off-by: 2byrds <2byrds@gmail.com>
Signed-off-by: 2byrds <2byrds@gmail.com>
Co-authored-by: Markus Sabadello <markus@danubetech.com> Signed-off-by: Daniel Hardman <daniel.hardman@gmail.com>
Co-authored-by: Markus Sabadello <markus@danubetech.com> Signed-off-by: Daniel Hardman <daniel.hardman@gmail.com>
| events (those that change key state), the last event may not be an establishment event and thus can not be relied on to | ||
| provide key information. In addition, the current set of witnesses is calculated from the initial set declared in the | ||
| inception event and "adds" and "cuts" declared in rotation events. | ||
| of custody from the [[ref: AID]] itself down to the current set of keys and the cryptographic commitment to the next rotation key(s). The [[ref: KERI event stream]] also contains events that do not alter the [[ref: AID]] key state, but are useful for the DID document, such as the supported domains, current set of service endpoints, etc. A did:webs resolver produces the DID document by processing the [[ref: KERI event stream]] to determine the current key state. We detail the different events in (KERI event details)[#KERI-event-details] below and show how they change the DID Document. The mapping from [[ref: KERI event stream]] to the properties of the DID Document is the core of the did:webs resolver logic. There are many ways to receive the [[ref: KERI event stream]], but only one way to process a [[ref: KERI event stream]] to produce the verifiable DID document. Understanding the optimal way to retrieve the [[ref: KERI event stream]] is beyond the scope of the spec, but a reference implementation of the resolver that details these techniques is being developed alongside this spec. The important concepts are that the entire [[ref: KERI event stream]] is used to produce and verify the DID document. |
There was a problem hiding this comment.
I didn’t get a chance to review this before it was merged but still have comments.
Why the line "There are many ways to receive the [[ref: KERI event stream]]”? AFAIK, the way in did:webs to retrieve the KERI event stream is to GET the file. KERI may have other ways (and perhaps we can do a side-reference to that effect), but in did:webs, there is only one way.
Is that not right?
There was a problem hiding this comment.
Sorry, I merged because I thought the PR was largely fixing typos, not doing something substantive.
Since the KERI event stream can be fetched by GETting the file from any of the DID locations (not necessarily the one where the DID doc was fetched), the statement about "many ways" could be referring to did:webs synonyms rather than non-did:webs KERI features. But that not have been the intent.
There was a problem hiding this comment.
I created some confusion sorry about that @swcurran @dhh1128, the initial commits were a pass to cleanup prior to adding content, but then I added new content since i hadn't seen any reviews. Soon after, there was some significant activity (Markus/Stephen/Daniel all added input). I will update the PR title to reflect the more significant content.
There was a problem hiding this comment.
Since this has been merged (sorry for that), instead of reverting I will do a follow-on PR based on our discussions here.
There was a problem hiding this comment.
I didn’t get a chance to review this before it was merged but still have comments.
Why the line "There are many ways to receive the [[ref: KERI event stream]]”? AFAIK, the way in did:webs to retrieve the KERI event stream is to GET the file. KERI may have other ways (and perhaps we can do a side-reference to that effect), but in did:webs, there is only one way.
Is that not right?
@swcurran I think the spec is migrating away from explicityly stating 'files' and toward 'KERI event stream' resources that is retrieved via a GET on the .keri for the did:webs DID..... that 'KERI event stream' could come from file(s), database(s), etc. and could be utilizing all kinds of interesting infrastructure. To address this and your related cache issue I give more details here
Happy to discuss, I appreciate the review and think we are getting close to the right level of abstraction for the spec.
| @@ -226,12 +218,12 @@ For example, a KERI AID with only the following inception event in its KEL: | |||
| ``` | |||
|
|
|||
| #### Verification Relationships | |||
| KERI AID public keys can be used to sign a variety of data. This includes but is not limited to logging into a website, challenge-response exchanges and credential issuances. It follows that for each public key in `k` two verification relationships must be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the DID controller can authenticate using each key and the `assertionMethod` verification relationship defines that the DID controller can express claims with each key (should we address multisig and thresholds here?). | |||
| KERI AID public keys can be used to sign a variety of data. This includes but is not limited to logging into a website, challenge-response exchanges and credential issuances. It follows that for each public key in `k` two verification relationships must be generated in the DID document. One verification relationship of type `authentication` and one verification relationship of type `assertionMethod`. The `authentication` verification relationship defines that the DID controller can authenticate using each key and the `assertionMethod` verification relationship defines that the DID controller can express claims with each key (TODO: address multisig and thresholds). | |||
There was a problem hiding this comment.
Is this a statement about KERI keys, or about DIDs? I think this is about DIDs in general. Not sure why it is called out here in this way, as if it was a unique feature of KERI. The rest of this reads (to me, at least) about normal DIDDoc contents.
There was a problem hiding this comment.
I think the point here is that KERI AID keys don't generally distinguish between authenticating the controller of the identifier and signing for that controller. In other words, the text is trying to make the point that the same key shows up in two verification relationships (usually), which is not a generally true assumption in all of DID-land.
There was a problem hiding this comment.
Hmmm…still doesn’t seem like something needed to be called out for did:webs. To create/evolve a the DID, I execute KERI events to accomplish my goal. If that requires I use some keys for authentication to make the changes, I don’t think it need be call out in the DIDDoc section.
Happy to leave it for now (especially since it is merged :-) ), but lets see how it reads in a final review.
|
|
||
| References to verification methods in the DID document MUST use the relative form of the identifier, e.g., `"authentication": ["#<identifier>"]`. | ||
|
|
||
| #### Service Endpoints | ||
| In KERI, service endpoints are defined by 2 sets of signed data that follow the Best Available Data - Read, Update, Nullify (BADA-RUN) (ref?) rules for data processing. Detailing the rules of BADA-RUN is beyond the scope of this document but to summarize, the protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available. | ||
| In KERI, service endpoints are defined by 2 sets of signed data that follow the Best Available Data - Read, Update, Nullify ([[ref: BADA-RUN]]) rules for data processing. The protocol ensures that all data is signed in transport and at rest and versioned to ensure only the latest signed data is available. |
There was a problem hiding this comment.
I think this should this be “In did:webs service endpoints are defined by 2 sets of signed data using KERI’s Best…."
There was a problem hiding this comment.
Is this the same for all services in the DIDDoc, or just the KERI services? If just the KERI services, I think it should be in the next section, with this intro section covering all DIDDoc services.
There was a problem hiding this comment.
@swcurran great questions! I only meant to update the ref to BADA-RUN since we detailed it in security characteristics. I will tackle detailing service endpoints in a future PR. this PR is focused on a few small fixes (like this one) and key-state related content. Would it be okay to punt this to a new issue #48 ?
| [DID Document from KERI Events](#did-document-from-keri-events) introduced the core [[ref: KERI event stream]] and related DID Document concepts. This section provides additional details regarding the basic types of KERI events and how they relate to the DID document. | ||
|
|
||
| #### Key state events | ||
| When processing the [[ref: KERI event stream]] there are two broad types of key state events (KERI parlance is 'establishment events') that can alter the key state of the DID document. Every [[ref: AID]] starts with an [[ref: inception event]]. If that inception event does not commit to a future set of rotation key hashes, then the AID is non-transferrable because the identifier can never change key state. If the inception event does commit to a future set of rotation key hashes, then the AID is transferrable and there could be future rotation events that transfer the key state from the current keys to the rotation keys that were committed to in the previous key state event. |
There was a problem hiding this comment.
I think this should be “that can alter the key state of the AID.” The DIDDoc derives from the key state, but the DIDDoc doesn’t have key state.
There was a problem hiding this comment.
I think the bit about the transferrable, non-transferrable should be in the inception event bullet point, not in the title.
I assume we can’t change this, but the term “transferrable” I find to be quite confusing. It means AFAIK that the the keys in the DID can’t be rotated. I’m sure there is a reason behind the term “transfer”...
There was a problem hiding this comment.
I think this should be “that can alter the key state of the AID.” The DIDDoc derives from the key state, but the DIDDoc doesn’t have key state.
I've fixed this wording and it will be in the next PR.
There was a problem hiding this comment.
I think the bit about the transferrable, non-transferrable should be in the inception event bullet point, not in the title.
I assume we can’t change this, but the term “transferrable” I find to be quite confusing. It means AFAIK that the the keys in the DID can’t be rotated. I’m sure there is a reason behind the term “transfer”...
The term "transferrable" means that control can be transferred from the current keys to the next keys that were committed to (via the rules of pre-rotation). Both inception and rotation events can provide transferability by specifying a set of next key hashes that commit to the transferability. It is also possible to end the ability to transfer control to next keys by not committing to a set of next keys. This could happen in the inception or rotation event. So perhaps I should keep it in this section above but be more explicit that it applies to both inception and rotation?
There was a problem hiding this comment.
I’ve long heard in the broader community and used the term "rotate keys" for the operation we’re talking about. And we enable it in KERI by specifying evidence of “pre-rotation” keys. AFAIK, only the KERI community uses the “Transferrable” — which for me has no connection to key rotation. When I hear it, I jump to transferring control of the DID from one entity to another, or perhaps transfering a DID from one ledger (e.g. DID identifier) to another.
There was a problem hiding this comment.
Agree that the pre-rotation mechanism must be included for the inception event and rotation events to enable additional rotations.
| #### Key state events | ||
| When processing the [[ref: KERI event stream]] there are two broad types of key state events (KERI parlance is 'establishment events') that can alter the key state of the DID document. Every [[ref: AID]] starts with an [[ref: inception event]]. If that inception event does not commit to a future set of rotation key hashes, then the AID is non-transferrable because the identifier can never change key state. If the inception event does commit to a future set of rotation key hashes, then the AID is transferrable and there could be future rotation events that transfer the key state from the current keys to the rotation keys that were committed to in the previous key state event. | ||
| * [[def: Inception event]]: The inception event is the first event in the [[ref: KEL]] that establishes the AID. This defines the initial key set and if the controller(s) desire future key rotation (transfer) then the inception event must commit to a set of future rotation key hashes. When processing the [[ref: KERI event stream]], if there are no rotation events after the inception event, then this is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). You can learn more about the inception event in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example inception event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-inception-event). To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) | ||
| * [[def: Rotation event]]: Rotation events come after inception events and can only change the key state to the previously committed to rotation keys and if the controller(s) desires future key rotation (transfer) then the rotation event must commit to a set of future rotation key hashes. When processing the [[ref: KERI event stream]], if there are rotation events after the inception event, then the last rotation event is the current key state of the AID and will be reflected in the DID Document as specified in [Verification Methods](#verification-methods) and [Verification Relationships](#verification-relationships). You can learn more about rotation events in the [KERI specification](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-basic-terminology) and you can see an [example rotation event](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-rotation-event-message-body). To learn about future rotation key commitment, see the sections about [pre-rotation](#pre-rotation) and the [KERI specification section on pre-rotation](https://trustoverip.github.io/tswg-keri-specification/draft-ssmith-keri.html#name-key-pre-rotation-concept) |
There was a problem hiding this comment.
Will there be more events added to this? I’m assuming there will be — adding keys, adding services, setting the DID URL, changing the DID URL, signing documents at least.
There was a problem hiding this comment.
Yes, I tackled the basic key-state events first. Based on feedback from the group I will repeat the 'format' of this PR for these issues service enpoints, verifying DID urls, etc.
We have some upcoming multisig work by Markus, that should help detail how to add/remove keys.
|
I think I commented on a number of things that tweaked existing language in the spec. A lot of my comments were about existing concepts that @2byrds tweaked. |
2byrds
changed the title
Preparation for detailing key state events