Merge pull request #75 from swcurran/urgent-fixes

Urgent Fixes -- whois title and use of defs in titles

spec/security_characteristics.md

@@ -21,13 +21,13 @@ There are several security characteristics necessary for `did:webs` to sufficien
 The following security concepts are used to secure the data, files, signatures and other information in `did:webs`. We characterize each concept with high, medium and low security to orient readers to the situational relevance.
 We use KEL-backed security for the highest possible security of on-disk storage, but also the most costly because it uses space in KELs. BADA-RUN is medium security and makes sure events are ordered in a consistent way, using a combination of date-time and a key state. Without having to negotiate security in did:webs we use a lower level of security when appropriate.
 
-#### [[def: KEL backed]] data: High Security
+#### KEL backed data: High Security
 
-KEL backed information in `did:webs` can either be found in the KEL or found anchored to the KEL. This means the signatures on the events in the KEL are strongly bound to the key state at the time the events are entered in the KEL. This provides the strongest guarantee of duplicity evidence so that any verifier is protected. The information is end-verifiable and any evidence of duplicity means do not trust. A key compromise of a stale key can not result in an exploit because that would require forging an alternate version of the KEL which would be exposed as duplicity. Key compromise of the current key state is recoverable with a rotation to the pre-rotated key(s) (single-sig or multi-sig). By design pre-rotated keys are post-quantum proof. A compromise of a current key state is guaranteed to be detectable by the AID’s controller because the compromise requires publication of a new KEL event in infrastructure (i.e. witnesses) controlled by the AID controller. This limits the exposure of a successful compromise of the current key state to the time it takes for the AID controller to observe the compromised publication and execute a recovery rotation.
+[[ref: KEL backed]] information in `did:webs` can either be found in the KEL or found anchored to the KEL. This means the signatures on the events in the KEL are strongly bound to the key state at the time the events are entered in the KEL. This provides the strongest guarantee of duplicity evidence so that any verifier is protected. The information is end-verifiable and any evidence of duplicity means do not trust. A key compromise of a stale key can not result in an exploit because that would require forging an alternate version of the KEL which would be exposed as duplicity. Key compromise of the current key state is recoverable with a rotation to the pre-rotated key(s) (single-sig or multi-sig). By design pre-rotated keys are post-quantum proof. A compromise of a current key state is guaranteed to be detectable by the AID’s controller because the compromise requires publication of a new KEL event in infrastructure (i.e. witnesses) controlled by the AID controller. This limits the exposure of a successful compromise of the current key state to the time it takes for the AID controller to observe the compromised publication and execute a recovery rotation.
 
-The ordering of events in the KEL is strictly verifiable because the KEL is a hash chain (block chain). All events are end-verifiable. Any data anchored to these events is also end-verifiable. All of these properties are guaranteed when data is anchored to a KEL, i.e., [[ref: KEL backed]]. Any information that wants to be end-verifiablly authentic over time should be at this highest level of security. [[ref: ACDCs]] when anchored to a KEL directly or indirectly through a [[ref: TEL]] that itself is anchored to a KEL have this level of security.
+The ordering of events in the KEL is strictly verifiable because the KEL is a hash chain (block chain). All events are end-verifiable. Any data anchored to these events is also end-verifiable. All of these properties are guaranteed when data is anchored to a KEL, i.e., [[ref: KEL backed]]. Any information that wants to be end-verifiably authentic over time should be at this highest level of security. [[ref: ACDCs]] when anchored to a KEL directly or indirectly through a [[ref: TEL]] that itself is anchored to a KEL have this level of security.
 
-#### [[def: BADA-RUN]]: Medium Security
+#### BADA-RUN Medium Security
 
 [[ref: BADA-RUN]] stands for Best available data acceptance - Read/Update/Nullify and is described in the ToIP KERI [[ref: OOBI specification]]. It makes sure events are ordered in a consistent way, using a combination of date-time and a key state.
 
@@ -45,17 +45,17 @@ One way to mitigate this exploit (non-detectability of current key state comprom
 
 To elaborate, because BADA only protects that latest data-state it is only appropriate for data where only the latest data-state is important. Unlike token based systems, however, BADA does not invalidate all latest data-states every time the key state is updated (rotated) where such invalidation would thereby force a refresh of all latest data-states. This property of not forcing auto-invalidation upon key rotation makes BADA suitable for asynchronous broadcast or gossip of the latest data-state in support of an authenticatable distributed data base. Whereas the forced auto-invalidation of data-state with token based systems limit their usefulness to access control applications (e.g. not data-bases). With BADA, however, an update of data-state only automatically auto-invalidates prior data-states. But that means that it is not useful for verifiable credentials or similar applications that must have verifiable provenance of old data-states. For example when old data-states must still be valid such as a credential issued under a now stale key state that must still be valid unless explicitly revoked.
 
-Abeit weaker than KEL backing, BADA is a significant performance and security improvment over token based systems. It also has performance advantages over KEL backing. As a result BADA is approapriate for information that does not benefit from verifiable ordering of all data-states but only the latest data-state such as a distributed data-base.
+Albeit weaker than KEL backing, BADA is a significant performance and security improvement over token based systems. It also has performance advantages over KEL backing. As a result BADA is approapriate for information that does not benefit from verifiable ordering of all data-states but only the latest data-state such as a distributed data-base.
 
-In [[ref: BADA-RUN]], the RUN stands for Read, Update, Nullify and is a replacement for CRUD in an API. CRUD does not protect from replay attacks on the data-state because a delete erases any record of last seen which destroys the monotonicity of the (date-time, key state) tuple. Likewise Create makes no sense because the API host cannot create a recored only the remote client can. Moreover, the function of a secure BADA Update must account for both first seen and last seen so a Create verb would be entirely superflous. Nullify deactivates a record without losing the monotonicy of update guarantee. RUN provides the appropriate verbs for any API that applies the security gurantees of a BADA policy to the data-state of its records.
+In [[ref: BADA-RUN]], the RUN stands for Read, Update, Nullify and is a replacement for CRUD in an API. CRUD does not protect from replay attacks on the data-state because a delete erases any record of last seen which destroys the monotonicity of the (date-time, key state) tuple. Likewise Create makes no sense because the API host cannot create a record only the remote client can. Moreover, the function of a secure BADA Update must account for both first seen and last seen so a Create verb would be entirely superflous. Nullify deactivates a record without losing the monotonicy of update guarantee. RUN provides the appropriate verbs for any API that applies the security guarantees of a BADA policy to the data-state of its records.
 
-#### [[def: KRAM]]: Low Security
+#### KRAM: Low Security
 
-KERI Request Authentication Mechanism (KRAM) is the lowest security requirement and can only be used for ephemeral query/reply mechanisms that protect against replay attacks and key-compromise attacks at the moment, not over time. This is done with [[ref: KRAM]] which is a non-interactive replay attack protection algorithm that uses a sliding window of date-time stamps and key state (similar to the the tuple as in [[ref: BADA-RUN]]) but the date-time is the replier’s not the querier’s. **[[ref: KRAM]] is meant to protect a host** when providing access to information to a client from replay attacks by a malicious client. It is not meant to protect the information provided by the host. For that we must use [[ref: BADA-RUN]] or KEL backing. Thus, by itself [[ref: KRAM]] is not suitable to protect on-disk storage (see [[ref: On-Disk Storage]] section below).
+KERI Request Authentication Mechanism ([[ref: KRAM]]) is the lowest security requirement and can only be used for ephemeral query/reply mechanisms that protect against replay attacks and key-compromise attacks at the moment, not over time. This is done with [[ref: KRAM]] which is a non-interactive replay attack protection algorithm that uses a sliding window of date-time stamps and key state (similar to the the tuple as in [[ref: BADA-RUN]]) but the date-time is the replier’s not the querier’s. **[[ref: KRAM]] is meant to protect a host** when providing access to information to a client from replay attacks by a malicious client. It is not meant to protect the information provided by the host. For that we must use [[ref: BADA-RUN]] or KEL backing. Thus, by itself [[ref: KRAM]] is not suitable to protect on-disk storage (see [[ref: On-Disk Storage]] section below).
 
 The `did:webs` resolver should be using KRAM to access the service endpoints providing KERI event streams for verification of the DID document. This is part of what makes the local resolver trusted, it must control who has access and KRAM provides the necessary “non-interactive” basis for non-replay attackable access.
 
-### [[def: On-Disk Storage]]
+### On-Disk Storage
 
 Both KEL-backed and [[ref: BADA-RUN]] are suitable for storing information on disk because both provide a link between the keystate and date-time on some data when a signature by the source of the data was created. [[ref: BADA-RUN]] is too weak for important information because an attacker who has access to the database on disk can overwrite data on disk without being detected by a verifier hosting the on-disk data either through a replay of stale data (data regression attack) or if in addition to disk access the attacker has compromised a given key state, then the attacker can forge new data with a new date-time stamp for a given compromised key and do a regression attack so that the last seen key state is the compromised key state.
 

spec/whois.md

@@ -1,4 +1,4 @@
-## The `whois` Folder
+## The `whois` DID URL
 
 The `did:webs` method defines that a controller MAY publish a W3C Verifiable
 Credentials Data Model Standard [[ref: Verifiable Presentation]] beside the DID