initial impl guide and starting to pull informative info into their a… (

#138)

* initial impl guide and starting to pull informative info into their and reference it

Signed-off-by: 2byrds <2byrds@gmail.com>

* one full pass to populate the impolementors guide

Signed-off-by: 2byrds <2byrds@gmail.com>

* Update spec/core.md

Co-authored-by: Charles Lanahan <charles.lanahan@gmail.com>
Signed-off-by: Lance <lance.byrd@rootsid.com>

---------

Signed-off-by: 2byrds <2byrds@gmail.com>

spec/core.md

@@ -43,9 +43,7 @@ This section is normative.
 1. The [[ref: host]] MUST abide by the formal rules describing valid syntax found in [[ref: RFC1035]], [[ref: RFC1123]], and [[ref: RFC2181]].
 1. A port MAY be included and the colon MUST be percent encoded, like `%3a`, to prevent a conflict with paths.
 1. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes.
-1. The KERI AID is a unique identifier and MUST be derived from the inception event of a KERI identifier.
-
-> The inception event is the first item in the identifier's [[ref: KEL]]. The algorithm used to generate the AID depends on the type of AID. If the AID is transferable (supports key rotation) then the AID is generated by taking a cryptographic digest of the inception event of the KEL of the AID. If the AID is non-transferable (does not support key rotation) the AID is generated by taking a cryptographic digest of the first (and only) public key of the identifier. See the [[ref: KERI Fundamentals]] section for more details.
+1. The KERI AID is a unique identifier and MUST be derived from the [[ref: inception event]] of a KERI identifier.
 
 > To be compatible with `did:web`, the AID is "just a path", the final (and perhaps only) path element. The presence of the required AID as a path element means that a `did:webs` always has a path,and so the "no path" version of a `did:web` that implicitly uses the `.well-known` folder is not supported by `did:webs`. Any `did:webs` can be expressed as a `did:web` but the inverse is not true--a `did:webs` must include an AID.
 
@@ -65,7 +63,8 @@ This section is normative.
     1. The [[ref: KERI event stream]] MUST be [[ref: CESR]]-formatted (media type of application/cesr) and the KERI events must be verifiable using the KERI rules.
 1. The `did:web` version of the DIDs MUST be the same (minus the `s`) and point to the same `did.json` file, but have no knowledge of the `keri.cesr` file.
 
-> The set of KERI features needed for most `did:webs` use cases is modest, with limited dependencies. These basics are summarized in the [KERI Fundamentals](#keri-fundamentals) section of this specification. This specification assumes a working knowledge of the concepts there. The inclusion of KERI in `did:webs` enables a number of capabilities for securing a `did:webs` identifier, including multi-signature support and the creation of [[ref: pre-rotated]] keys to prevent loss of control of the identifier if the current private key were to be compromised.
+For more information, see the following sections in the implementors guide:
+* [[ref: the set of KERI features needed]] to support `did:webs`
 
 > A target system cannot forge or tamper with data protected by KERI, and if it deliberately serves an outdated copy, the duplicity is often detectable. Thus, any given target system in isolation can be viewed by this method as a dumb, untrusted server of content. It is the combination of target systems and some KERI mechanisms, _together_, that constitutes this method's verifiable data registry. In short, verifying the DID document by processing the [[ref: KERI event stream]] using KERI puts the "s" of "security" in `did:webs`.
 
@@ -93,10 +92,6 @@ URLs, based on the examples from the [[ref: did:web Specification]], but with th
 
 > Since an AID is a unique cryptographic identifier that is inseparably bound to the [[ref: KERI event stream]] it is associated with any AIDs and any `did:webs` DIDs that have the same AID component. It can be verifiably proven that they have the same controller(s).
 
-> The web supports a number of ways to redirect users. See the section on [Handling Web Redirections](#handling-web-redirection) later in this specification.
-
-> KERI anticipates the possibility of a duplicitous actor with an AID that forks a [[ref: KERI event stream]] and shares different versions of the [[ref: KERI event stream]] containing different events, such as publishing different versions of the [[ref: KERI event stream]] on different web servers.
-
 ### Handling Web Redirection
 
 1. A `did:webs` MAY be a "stable" (long-lasting) identifier that can be put into documents such as verifiable credentials, to be useful for a very long time -- generations.
@@ -113,17 +108,7 @@ URLs, based on the examples from the [[ref: did:web Specification]], but with th
         1. If possible, the controller of the DID MAY use web redirects to allow resolution of the old location of the DID to the new location.
     1. If the previously published location of a `did:webs` is not redirected, an entity trying to resolve the DID MAY be able to find the data for the DID somewhere else using just the AID.
 
-> The web is not a very stable place, and documents are moved around and copied frequently. When two or more companies merge, often the web presence of some of the merged entities "disappears". It may not be possible to retain a permanent `did:webs` web location.
-
-> The purpose of the history of [[ref: designated aliases]] for the AID is so that if the `did:webs` DID has been put in long-lasting documents, and its URL instantiation is redirected or disappears, the controller can explicitly indicate that the new DID is an `equivalentId` to the old one.
-
-> Since the AID is globally unique and references the same identifier, regardless of the rest of the string that is the full `did:webs`, web searching could yield either the current location of the DID document, or a copy of the DID that may be useful. For example, even the [Internet Archive: Wayback Machine](https://archive.org/web) could be used to find a copy of the DID document and the [[ref: KERI event stream]] at some point in the past that may be sufficient for the purposes of the entity trying to resolve the DID. This specification does not rely on the Wayback Machine, but it might be a useful `did:webs` discovery tool.
-
-> The DID document, [[ref: KERI event stream]] and other files related to a DID may be copied to other web locations. For example, someone might want to keep a cache of DIDs they use, or an entity might want to run a registry of "useful" DIDs for a cooperating group. While the combination of DID document and [[ref: KERI event stream]] make the DID and DID document verifiable, just as when published in their "intended" location, the absence of the `did:webs` in the [[ref: designated aliases]] for those locations in the DID document `equivalentId` means that the controller of the DID is not self-asserting any sort of tie between the DID and the location to which the DID-related documents have been copied. In contrast, if the controller confirms the link between the source and the copy with an `equivalentId`, the related copies will have to be kept in sync.
-
-> Were the AID of a `did:webs` identifier to change, it would be an altogether new DID, unconnected to the first DID.
-
-> A `did:webs` could be moved to use another DID method that uses the AID for uniqueness and the [[ref: KERI event stream]] for validity, but that is beyond the scope of this specification.
+* The implementors guide contains more information about `did:webs` [[ref: stable identifiers on an unstable web]]. 
 
 ### DID Method Operations
 

spec/diddocuments.md

@@ -6,8 +6,7 @@ This section is normative.
 1. `did:webs` DID documents MUST be pure JSON. They MAY be processed as JSON-LD by prepending an `@context` if consumers of the documents wish.
 1. All hashes, cryptographic keys, and signatures MUST be represented as [[ref: CESR]] strings. This is an approach similar to multibase, making them self-describing and terse.
 
-> The [[ref: KERI event stream]] represents a cryptographic chain 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 [[ref: hosts]], 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.  Understanding the optimal way to update and maintain the [[ref: KERI event stream]] (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) 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.
-> The [[ref: KERI event stream]] represents a cryptographic chain 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 [[ref: hosts]], 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.  Understanding the optimal way to update and maintain the [[ref: KERI event stream]] (publish static keri.cesr files, dyanamically generate the keri.cesr resource, etc) 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.
+* See the implementors guide for more information about the [[def: KERI event stream chain of custody]]
 
 In KERI the calculated values that result from processing the [[ref: KERI event stream]] are referred to as the "current key state" and expressed
 in the Key State Notice (KSN) record.  An example of a KERI KSN record can be seen here:
@@ -361,24 +360,7 @@ would result in a DID document with the following verification methods array:
 
 > Private keys of a KERI AID can be used to sign a variety of data.  This includes but is not limited to logging into a website, challenge-response exchanges, credential issuances, etc.
 
-#### Key Agreement
-This section is informative:
-
-There are multiple ways to establish key agreement in KERI. We detail common considerations and techniques:
-* If the 'k' field references a Ed25519 key, then key agreement may be established using the corresponding x25519 key for Diffie-Helman key exchange.
-* If the key is an ECDSA or other NIST algorithms key then it will be the same key for signatures and encryption and can be used for key agreement.
-
-* *BADA-RUN for key agreement:* Normally in KERI we would use [[ref: BADA-RUN]], similar to how we specify endpoints, [[ref: host]] migration info, etc. This would allow the controller to specify any Key Agreement key, without unnecessarily adding KERI events to their [[ref: KEL]].
-* *Key agreement from `k` field keys:* It is important to note that KERI is cryptographically agile and can support a variety of keys and signatures.
-* *Key agreement anchored in KEL:* It is always possible to anchor arbitrary data, like a key agreement key, to the KEL.
-  * Likely the best mechanism is to anchor an [[ref: ACDC]] to a [[ref: TEL]] which is anchored to the KEL.
-
-#### Other Key Commitments
-This section is informative.
-
-Data structures similar to Location Scheme and Endpoint Authorizations and managed in KERI using [[ref: BADA-RUN]] may be created and used for declaring other types of keys, for example encryption keys, etc
-
-To support new data structures, propose them in KERI and detail the transformation in the spec.
+For more information, see the [[ref: key agreement]] and [[ref: other key commitments]] section in the Implementors Guide.
 
 ### Service Endpoints
 1. `did:webs` DIDs MUST support service endpoints, including types declared in the DID Specification Registries, such as [DIDCommMessaging](https://www.w3.org/TR/did-spec-registries/#didcommmessaging).