§ Spec-Up Example

Specification Status: Draft

Latest Draft: https://identity.foundation/spec-up

Editors:
Daniel Buchner
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

Let’s face it, other tools and generators for writing technical specifications aimed at standards bodies or industry groups are cumbersome, underwhelming, and lack the features you might want in a technical specification document. Spec-Up’s goal is to deliver you a better spec-writing experience with far less effort and tedium than other tools in the ecosystem. Spec-Up is a simple tool that auto-generates great specs from markdown. The version of markdown Spec-up uses contains all the same features you might expect from common implementations, like GitHub, but adds much more, including notice blocks, complex tables, charts, advanced syntax highlighting, UML diagrams, etc.

§ Getting Started

Using Spec-Up is easy peasy lemon squeezy:

  1. npm install spec-up

  2. Create a specs.json file in the root folder of your repository to specify configuration values used in the generation of your spec documents. The values in your specs.json file include things like where your spec’s markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the specs.json config file:

    • spec_directory (STRING, required) - You must specify the repo-root-relative location of your spec’s markdown file directory. You MUST name your spec’s markdown file spec.md and locate it in your spec_directory for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optionalmarkdown_paths field described below. See the “multi-file” example in the spec-up repo.
    • title (STRING, required) - You must add a title for your spec, which will be rendered in the generated document’s H1 text and page title.
    • markdown_paths (ARRAY, optional) - If you want to name your spec’s markdown file something other than spec.md, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the spec_directory you specified, so DO NOT repeat the full root relative path.
    • katex (BOOLEAN, optional) - To enable TeX support via KaTeX, set this property to true. After rendering, be sure to copy the fonts/ subdirectory, containing the necessary web fonts.
    • output_path (STRING, optional) - If you want the generated spec document to be output to a different location than the spec_directory you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use ./ for root), and the tool will write the document file there instead.

  3. In your main node.js file, drop in this bad boy: require('spec-up')()

Boom! That’s it. Spec-Up will auto-detect modifications to files in your spec_directory and auto-generate your spec’s updated HTML document every time you save a change.

Usage

If your spec.json and package.json and package-lock.json files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes:

command behavior
npm run edit after rendering, this will stay running and the gulp library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.
npm run render this renders the site once and does not keep a gulpy watch on the underlying files.
npm run dev this enables debugging features.

§ Table of Contents

<-- You see that beautiful TOC over there to your left? (tap the header link to slide it out on mobile) Yeah, you don’t need to do a damn thing, that just magically appears based on your use of h2, h3, and h4 headings.

§ Term References

§ Definition Lists

Many specs may want to include a section for terminology references, and Definition Lists are a great way to do that. Here’s how to leverage Spec-Up’s automatic term reference features via Definition List markup:

[[def: Term 1, Term One]]:
~ This is the first term we will define.

[[def: Term 2, Term Two]]:
~ This is the second term, but not the last.

[[def: Term 3, Term Three]]:
~ This is the last term, because you know what they say: third term's the charm!
Term 1:
This is the first term we will define.
Term 2:
This is the second term, but not the last.
Term 3:
This is the last term, because you know what they say: third term’s the charm!

Now let’s refer to some of the terms defined above to show how the auto-linking of terms works: Term 1, Term Two, Term 3. Additionally, as long as you define your terms using Definition Lists (as seen in the markdown above), you will be able to hover any reference to a term to see a tooltip with its definition.

§ Table-defined Terms

You can also reference table-oriented terms and definitions which are decomposed into heading-titled attributes in distinct cells:

Variable           | Default Value | Max Value
------------------- | -------------- | ---------
[[def: Variable 1]] | 123          | 9999
Variable Default Value Max Value
Variable 1 123 9999

Anytime you add a definition of a term in the first column of a table, like Variable 1, it will link to the cell and display a tooltip with the entire set of row values when you hover the term.

§ External Term References

It is possible to include references to terms from external spec-up generated specifications. To include a source you would like to pull references from include an external_specs array in your spec config. The value should be a key/value object where the key is used in the external reference below and the value is the URL of the external spec.

EXAMPLE
{
  "specs": [
    {
      ...
      "external_specs": [
        {"PE": "https://identity.foundation/presentation-exchange"}
      ]
    }
  ]
}

To include an external term reference within your spec use the following format [[x-ref: {title}, {term}]] where {title} is the title given to the spec in the config and {term} is the term being used. For example using the PE spec given in the example above Holder

§ KERI gloss

[[x-ref: KE, Autonomic identifier]]

Autonomic identifier

and what about

[[x-ref: CE, Autonomic identifier]]

Autonomic identifier

and the most important

[[x-ref: KE, Key Event Log]]

Key Event Log

hey, and how did it know?..!

[[x-ref: KE, KEL]]

KEL

§ ACDC gloss

[[x-ref: AC, Edge]]

Edge

§ CESR gloss

[[x-ref: CE, Composability]]

Composability

§ Duplicity?

KERI, ACDC, CESR

Duplicity

Duplicity

Duplicity

§ Typo resistant (to what extent?!)

§ Blockquote

To be, or not to be, that is the question: Whether 'tis nobler in the mind to suffer The slings and arrows of outrageous fortune, Or to take arms against a sea of troubles And by opposing end them. To die—to sleep, No more;

§ Notices

::: note Basic Note
  Check this out.
:::
NOTE

Check this out.

NOTE

Here’s another.

NOTE

And one more!

NOTE

One last note!!!

::: issue Issue Notice
  I take issue with that, kind sir.
:::
ISSUE

I take issue with that, kind sir.

::: warning Warning Notice
  Houston, I think we have a problem
:::
WARNING

Houston, I think we have a problem

::: todo Really Important
  Get this done!
:::
TODO

Get this done!

::: example Code Example
  Put your code block here
:::
EXAMPLE
// Some comment in JSON
{
  "foo": "bar",
  "baz": 2
}

§ Content Insertion

Use the following format to pull in content from other files in your project:

This text has been inserted here from another file: [[insert: ./single-file-test/assets/test.text]]

This text has been inserted here from another file: Beam me in, Scotty!

You can even insert content within more complex blocks, like the JSON object below which is being pulled in and rendered in a syntax-highlighted example block:

::: example Code Example
```json
[[insert: ./single-file-test/assets/test.json]]
```
:::
EXAMPLE
{
  "foo": {
    "bar": 1
  }
}

§ Tables

Stage | Direct Products | ATP Yields
----: | --------------: | ---------:
Glycolysis | 2 ATP ||
^^ | 2 NADH | 3--5 ATP |
Pyruvaye oxidation | 2 NADH | 5 ATP |
Citric acid cycle | 2 ATP ||
^^ | 6 NADH | 15 ATP |
^^ | 2 FADH2 | 3 ATP |
**30--32** ATP |||
[Net ATP yields per hexose]
Net ATP yields per hexose
Stage Direct Products ATP Yields
Glycolysis 2 ATP
2 NADH 3–5 ATP
Pyruvaye oxidation 2 NADH 5 ATP
Citric acid cycle 2 ATP
6 NADH 15 ATP
2 FADH2 3 ATP
30–32 ATP 
|--|--|--|--|--|--|--|--|
|♜|  |♝|♛|♚|♝|♞|♜|
|  |♟|♟|♟|  |♟|♟|♟|
|♟|  |♞|  |  |  |  | |
|  |♗|  |  |♟|  |  | |
|  |  |  |  |♙|  |  | |
|  |  |  |  |  |♘|  | |
|♙|♙|♙|♙|  |♙|♙|♙|
|♖|♘|♗|♕|♔|  |  |♖|
♜ ♝ ♛ ♚ ♝ ♞ ♜
♟ ♟ ♟ ♟ ♟ ♟
♟ ♞
♗ ♟
♙
♘
♙ ♙ ♙ ♙ ♙ ♙ ♙
♖ ♘ ♗ ♕ ♔ ♖

§ Sequence Diagrams

```mermaid
sequenceDiagram
  Alice ->> Bob: Hello Bob, how are you?
  Bob-->>John: How about you John?
  Bob--x Alice: I am good thanks!
  Bob-x John: I am good thanks!
  Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row.

  Bob-->Alice: Checking with John...
  Alice->John: Yes... John, how are you?
```
sequenceDiagram Alice ->> Bob: Hello Bob, how are you? Bob-->>John: How about you John? Bob--x Alice: I am good thanks! Bob-x John: I am good thanks! Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes... John, how are you?

§ Flows

```mermaid
graph TD
  A[Start] --> B{Is it?}
  B -->|Yes| C[OK]
  C --> D[Rethink]
  D --> B
  B -->|No| E[End]
```
graph TD A[Start] --> B{Is it?} B -->|Yes| C[OK] C --> D[Rethink] D --> B B -->|No| E[End]

§ Charts

```chart
{
  "type": "pie",
  "data": {
    "labels": [
      "Red",
      "Blue",
      "Yellow"
    ],
    "datasets": [
      {
        "data": [
          300,
          50,
          100
        ],
        "backgroundColor": [
          "#FF6384",
          "#36A2EB",
          "#FFCE56"
        ],
        "hoverBackgroundColor": [
          "#FF6384",
          "#36A2EB",
          "#FFCE56"
        ]
      }
    ]
  }
}
```
{"type":"pie","data":{"labels":["Red","Blue","Yellow"],"datasets":[{"data":[300,50,100],"backgroundColor":["#FF6384","#36A2EB","#FFCE56"],"hoverBackgroundColor":["#FF6384","#36A2EB","#FFCE56"]}]}}

§ Syntax Highlighting

```json
{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [{
    "id":"did:example:123456789abcdefghi#vcs",
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}
```

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{ 
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [{
    "id":"did:example:123456789abcdefghi#vcs",
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}

§ TeX Math Equations

When the katex option is enabled, the KaTeX math engine is used for TeX rendering. You can find a list of supported features and examples here: https://katex.org/docs/supported.html.

(x2y2)=(ABCD)⋅(x1y1)\begin{pmatrix}x_2 \\ y_2 \end{pmatrix} = \begin{pmatrix} A & B \\ C & D \end{pmatrix}\cdot \begin{pmatrix} x_1 \\ y_1 \end{pmatrix}

abcdefghi\def\arraystretch{1.5} \begin{array}{c:c:c} a & b & c \\ \hline d & e & f \\ \hdashline g & h & i \end{array}

a+b+c⏟Note: such math, much wow.\underbrace{a+b+c}_{\text{Note: such math, much wow.}}

§ Tab Panels

{
  "foo": "foo",
  "baz": 1
}

{
  "foo": "bar",
  "baz": 2
}

Spec-Up automatically upgrades the links of certain sites, like GitHub. GitHub is the only supported site with Fancy Links right now, but we’ll be adding more as we go.

§ GitHub

§ External Spec References

You can reference external specifications from IETF, W3C, and WHATWG as follows:

  1. Anywhere in your document you want to referece an external specification, use the spec-prefixed custom token format: [[spec:RFC4122]]
  2. Wherever in your document you want to print out all your external specification references, use the spec custom token format without any spec name: [[spec]]

Here are a set of example references that are distributed among the reference groups spec, spec-norm, spec-inform:

§ Default References

This is what is printed out when you include the [[spec]] custom token in your Markdown:

RFC3548
The Base16, Base32, and Base64 Data Encodings. S. Josefsson, Ed.; 2003-07. Status: Informational.
RFC7518
JSON Web Algorithms (JWA). M. Jones; 2015-05. Status: Proposed Standard.

§ Normative References

This is what is printed out when you include the [[spec-norm]] custom token in your Markdown:

DID-CORE
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
DID-SPEC-REGISTRIES
DID Specification Registries. Orie Steele; Manu Sporny; 2023-09-11. Status: NOTE.

§ Informative References

This is what is printed out when you include the [[spec-inform]] custom token in your Markdown:

RFC6901
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.; 2013-04. Status: Proposed Standard.
RFC7230
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.; 2014-06. Status: Proposed Standard.

✕
Table of Contents ✕
Claim
An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
Claim
An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
Conformant Consumer
An entity that follows the specified processing rules to consume a Presentation Definition or Presentation Submission that conforms to this specification.
Conformant Consumer
An entity that follows the specified processing rules to consume a Presentation Definition or Presentation Submission that conforms to this specification.
Conformant Producer
An entity that produces a Presentation Definition or Presentation Submission that conforms to this specification.
Embed Locations
Embed Locations are the specific paths and indexes per Embed Target where the Verifier can expect to find the Presentation. See Embed Locations.
Embed Target
Embed Targets are data formats used in messaging protocols that may be used to transport a Presentation Submission. See Embed Targets.
Embed Target
Embed Targets are data formats used in messaging protocols that may be used to transport a Presentation Submission. See Embed Targets.
Feature
Features enable Verifiers to express, and Holders to support, extended functionality (relative to the base objects) by defining one or more properties on one or more objects.
Feature
Features enable Verifiers to express, and Holders to support, extended functionality (relative to the base objects) by defining one or more properties on one or more objects.
Holder
Holders are entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. A Holder is a Conformant Consumer of a Presentation Definition and a Conformant Producer of a Presentation Submission.
Holder
Holders are entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. A Holder is a Conformant Consumer of a Presentation Definition and a Conformant Producer of a Presentation Submission.
Holder Binding
Holder Bindings are requirements of a certain type of relationship between the Holder and the Claims within the Presentation. See Holder Binding.
Decentralized Web Node
Some examples refer to an unfamiliar query protocol, dwn://, as a way of storing and querying schemata and other resources. While orthogonal to this specification and not yet on a standards track, the concept of “decentralized web nodes” proposes an architecture that may be of interest or utility to implementers of this specification. For more information, see the draft specification hosted at the decentralized identity foundation here
Decentralized Web Node
Some examples refer to an unfamiliar query protocol, dwn://, as a way of storing and querying schemata and other resources. While orthogonal to this specification and not yet on a standards track, the concept of “decentralized web nodes” proposes an architecture that may be of interest or utility to implementers of this specification. For more information, see the draft specification hosted at the decentralized identity foundation here
Input Descriptor
Input Descriptors are used by a Verifier to describe the information required of a Holder before an interaction can proceed. See Input Descriptor.
Input Descriptor
Input Descriptors are used by a Verifier to describe the information required of a Holder before an interaction can proceed. See Input Descriptor.
Input Descriptor Object
Input Descriptors Objects are populated with properties describing what type of input data/Claim, or sub-fields thereof, are required for submission to the Verifier. See Input Descriptor Object.
Input Descriptor Object
Input Descriptors Objects are populated with properties describing what type of input data/Claim, or sub-fields thereof, are required for submission to the Verifier. See Input Descriptor Object.
Link Secrets
Link Secrets are values held by the Holder but hidden from other parties. They are typically incorporated into cryptographic signatures used in claims to demonstrate correlation while preventing replay attacks. An Issuer may ascertain that a Holder possesses a link secret without its disclosure. See Link Secrets.
Presentation Definition
Presentation Definitions are objects that articulate what proofs a Verifier requires. These help the Verifier to decide how or whether to interact with a Holder. Presentation Definitions are composed of inputs, which describe the forms and details of the proofs they require, and optional sets of selection rules, to allow Holders flexibility in cases where many different types of proofs may satisfy an input requirement. See Presentation Definition.
Presentation Request
Presentation Requests are transport mechanisms for Presentation. Presentation Requests can take multiple shapes, using a variety of protocols and signature schemes not refined in this specification. They are sent by a Verifier to a Holder. Defining Presentation Requests is outside the scope of this specification. See Presentation Request.
Presentation Submission
Presentation Submissions are objects embedded within target claim negotiation formats that unify the presentation of proofs to a Verifier in accordance with the requirements a Verifier specified in a Presentation Definition. See Presentation Submission.
Subject
Subjects are the entities about which Claims are made. The Subject may not be the same entity as the Holder
Subject
Subjects are the entities about which Claims are made. The Subject may not be the same entity as the Holder
Submission Requirement
Submission Requirements are objects that define what combinations of inputs must be submitted to comply with the requirements a Verifier has for proceeding in a flow (e.g. credential issuance, allowing entry, accepting an application). See Submission Requirements.
Submission Requirement
Submission Requirements are objects that define what combinations of inputs must be submitted to comply with the requirements a Verifier has for proceeding in a flow (e.g. credential issuance, allowing entry, accepting an application). See Submission Requirements.
Submission Requirement Object
Submission Requirement Objects describe valid combinations of inputs in a Presentation Submission. See Submission Requirement Objects.
Submission Requirement Object
Submission Requirement Objects describe valid combinations of inputs in a Presentation Submission. See Submission Requirement Objects.
Submission Requirement Rule
Submission Requirement Rules describe combinatorial rules within a Submission Requirement Object when processing inputs. They may be nested. See Submission Requirement Rules.
Submission Requirement Rule
Submission Requirement Rules describe combinatorial rules within a Submission Requirement Object when processing inputs. They may be nested. See Submission Requirement Rules.
Verifier
Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. A Verifier is a Conformant Producer of a Presentation Definition and a Conformant Consumer of a Presentation Submission.
Verifier
Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. A Verifier is a Conformant Producer of a Presentation Definition and a Conformant Consumer of a Presentation Submission.
OIDC
Open ID Connect. Jones, M., Bradley, J., and N. Sakimura. Status: Approved Specification
Linked Data Proof
Data Integrity 1.0. Dave Longley, Manu Sporny. 2022-03. Status: Draft Community Group Report.
Linked Data Proof
Data Integrity 1.0. Dave Longley, Manu Sporny. 2022-03. Status: Draft Community Group Report.
CHAPI
W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
CHAPI
W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
DIDComm
DIF DIDComm Messaging. Daniel Hardman, Sam Curren. Status: Working Group Draft.
,
Authentic Chained Data Container
a directed acyclic graph with properties to provide a verifiable chain of proof-of-authorship. See the full specification
Authentic Chained Data Container
a directed acyclic graph with properties to provide a verifiable chain of proof-of-authorship. See the full specification
Autonomic identifier
a self-managing cryptonymous identifier that must be self-certifying (self-authenticating) and must be encoded in CESR as a qualified Cryptographic primitive.
Autonomic identifier
a self-managing cryptonymous identifier that must be self-certifying (self-authenticating) and must be encoded in CESR as a qualified Cryptographic primitive.
Autonomic identity system
an identity system that includes a primary root-of-trust in self-certifying identifiers that are strongly bound at issuance to a cryptographic signing (public, private) key pair. An AIS enables any entity to establish control over an AN in an independent, interoperable, and portable way.
Autonomic identity system
an identity system that includes a primary root-of-trust in self-certifying identifiers that are strongly bound at issuance to a cryptographic signing (public, private) key pair. An AIS enables any entity to establish control over an AN in an independent, interoperable, and portable way.
Autonomic namespace
a namespace that is self-certifying and hence self-administrating. An AN has a self-certifying prefix that provides cryptographic verification of root control authority over its namespace. All derived AIDs in the same AN share the same root-of-trust, source-of-truth, and locus-of-control (RSL). The governance of the namespace is therefore unified into one entity, that is, the controller who is/holds the root authority over the namespace.
Autonomic namespace
a namespace that is self-certifying and hence self-administrating. An AN has a self-certifying prefix that provides cryptographic verification of root control authority over its namespace. All derived AIDs in the same AN share the same root-of-trust, source-of-truth, and locus-of-control (RSL). The governance of the namespace is therefore unified into one entity, that is, the controller who is/holds the root authority over the namespace.
Backer
an alternative to a traditional KERI based Witness commonly using Distributed Ledger Technology (DLT) to store the KEL for an identifier.
Concise Binary Object Representation
something
Concise Binary Object Representation
something
Configuration traits
a list of specially defined strings representing a configuration of a KEL. See (Configuration traits field)[#configuration-traits-field].
Configuration traits
a list of specially defined strings representing a configuration of a KEL. See (Configuration traits field)[#configuration-traits-field].
Controller
an entity that can cryptographically prove the control authority over an AID and make changes on the associated KEL. A controller of a multi-sig AID may consist of multiple controlling entities.
Cryptographic Primitive
the serialization of a value associated with a cryptographic operation including but not limited to a digest (hash), a salt, a seed, a private key, a public key, or a signature.
Cryptonym
a cryptographic pseudonymous identifier represented by a string of characters derived from a random or pseudo-random secret seed or salt via a one-way cryptographic function with a sufficiently high degree of cryptographic strength (e.g., 128 bits, see appendix on cryptographic strength) [13] [14] [12] [11]. A Cryptonym is a type of Primitive. Due to the entropy in its derivation, a Cyptonym is a universally unique identifier and only the Controller of the secret salt or seed from which the Cryptonym is derived may prove control over the Cryptonym. Therefore the derivation function must be associated with the Cryptonym and may be encoded as part of the Cryptonym itself.
Current threshold
represents the number or fractional weights of signatures from the given set of current keys required to be attached to a Message for the Message to be considered fully signed.
Dead-Attack
an attack on an establishment event that occurs after the Key-state for that event has become stale because a later establishment event has rotated the sets of signing and pre-rotated keys to new sets. See (Security Properties of Prerotation)[#dead-attacks].
Decentralized key management infrastructure
a key management infrastructure that does not rely on a single entity for the integrity and security of the system as a whole. Trust in a DKMI is decentralized through the use of technologies that make it possible for geographically and politically disparate entities to reach an agreement on the key state of an identifier DPKI.
Decentralized key management infrastructure
a key management infrastructure that does not rely on a single entity for the integrity and security of the system as a whole. Trust in a DKMI is decentralized through the use of technologies that make it possible for geographically and politically disparate entities to reach an agreement on the key state of an identifier DPKI.
Duplicity
the existence of more than one Version of a Verifiable KEL for a given AID.
End-verifiability
a data item or statement may be cryptographically securely attributable to its source (party at the source end) by any recipient verifier (party at the destination end) without reliance on any infrastructure not under the verifier’s ultimate control.
Establishment event
a Key event that establishes or changes the Key state which includes the current set of authoritative keypairs (Key state) for an AID.
First-Seen
refers to the first instance of a Message recieved by any Witness or Watcher. The first-seen event is always seen, and can never be unseen. It forms the basis for Duplicity detection in KERI based systems.
Inception
the operation of creating an AID by binding it to the initial set of authoritative keypairs and any other associated information. This operation is made verifiable and Duplicity evident upon acceptance as the Inception event that begins the AID’s KEL.
Inception event
an Establishment event that provides the incepting information needed to derive an AID and establish its initial Key state.
Interaction event
a Non-establishment event that anchors external data to the Key state as established by the most recent prior Establishment event.
KERI’s Algorithm for Witness Agreement
a type of Byzantine Fault Tolerant (BFT) algorithm
KERI’s Algorithm for Witness Agreement
a type of Byzantine Fault Tolerant (BFT) algorithm
Key event
concretely, the serialized data structure of an entry in the Key event log (KEL) for an AID. Abstractly, the data structure itself. Key events come in different types and are used primarily to establish or change the authoritative set of keypairs and/or anchor other data to the authoritative set of keypairs at the point in the KEL actualized by a particular entry.
Key event log
a Verifiable data structure that is a backward and forward chained, signed, append-only log of key events for an AID. The first entry in a KEL must be the one and only Inception event of that AID.
Key event log
a Verifiable data structure that is a backward and forward chained, signed, append-only log of key events for an AID. The first entry in a KEL must be the one and only Inception event of that AID.
Key event message
message whose body is a Key event and whose attachments may include signatures on its body.
Key event receipt
message whose body references a Key event and whose attachments must include one or more signatures on that Key event.
Key event receipt log
a key event receipt log is a KEL that also includes all the consistent key event receipt Messages created by the associated set of witnesses. See annex Key event receipt log
Key event receipt log
a key event receipt log is a KEL that also includes all the consistent key event receipt Messages created by the associated set of witnesses. See annex Key event receipt log
Key-State
a set of currently authoritative keypairs for an AID and any other information necessary to secure or establish control authority over an AID. This includes current keys, prior next key digests, current thresholds, prior next thresholds, witnesses, witness thresholds, and configurations. A key-state of an AID is first established through an inception event and may be altered by subsequent rotation events.
Live-Attack
an attack that compromises either the current signing keys used to sign non-establishment events or he current pre-rotated keys needed to sign a subsequent establishment event. See (Security Properties of Prerotation)[#live-attacks].
Message
a serialized data structure that comprises its body and a set of serialized data structures that are its attachments. Attachments may include but are not limited to signatures on the body.
Next threshold
represents the number or fractional weights of signatures from the given set of next keys required to be attached to a Message for the Message to be considered fully signed.
Non-establishment event
a Key event that does not change the current Key state for an AID. Typically, the purpose of a Non-establishment event is to anchor external data to a given Key state as established by the most recent prior Establishment event for an AID.
Primitive:
a serialization of a unitary value. All Primitives in KERI must be expressed in CESR [1].
Rotation
the operation of revoking and replacing the set of authoritative keypairs for an AID. This operation is made verifiable and Duplicity evident upon acceptance as a Rotation event that is appended to the AID’s KEL.
Rotation event
an Establishment Event that provides the information needed to change the Key state which includes a change to the set of authoritative keypairs for an AID.
Salt
random data fed as an additional input to a one-way function that hashes data.
Seal
a seal is a cryptographic commitment in the form of a cryptographic digest or hash tree root (Merkle root) that anchors arbitrary data or a tree of hashes of arbitrary data to a particular event in the key event sequence. See annex (Seal)[#seal].
Self-addressed data
a representation of data content from which a SAID is derived. The SAID is both cryptographically bound to (content-addressable) and encapsulated by (self-referential) its SAD SAID.
Self-addressed data
a representation of data content from which a SAID is derived. The SAID is both cryptographically bound to (content-addressable) and encapsulated by (self-referential) its SAD SAID.
Self-addressing identifiers
an identifier that is content-addressable and self-referential. A SAID is uniquely and cryptographically bound to a serialization of data that includes the SAID as a component in that serialization SAID.
Self-addressing identifiers
an identifier that is content-addressable and self-referential. A SAID is uniquely and cryptographically bound to a serialization of data that includes the SAID as a component in that serialization SAID.
Self-certifying identifier
a type of Cryptonym that is uniquely cryptographically derived from the public key of an asymmetric non-repudiable signing keypair, (public, private).
Self-certifying identifier
a type of Cryptonym that is uniquely cryptographically derived from the public key of an asymmetric non-repudiable signing keypair, (public, private).
Validator
any entity or agent that evaluates whether or not a given signed statement as attributed to an identifier is valid at the time of its issuance.
Verifiable
a condition for a KEL for being internally consistent with integrity of its backward and forward chaining digest as well as authenticity of its non-repudiable signatures
Verifier
any entity or agent that cryptographically verifies the signature(s) and/or digests on an event Message.
Version
an instance of a KEL for an AID in which at least one event is unique between two instances of the KEL
Watcher
a watcher is an entity or component that keeps a copy of a KERL for an identifier but is not designated by the controller of the identifier as one of its witnesses. See annex watcher
Witness
a witness is an entity or component designated (trusted) by the controller of an identifier. The primary role of a witness is to verify, sign, and keep events associated with an identifier. A witness is the controller of its own self-referential identifier which may or may not be the same as the identifier to which it is a witness. See Annex Witness.
,
Attribute
a top-level field map within an ACDC that provides a property of an entity that is inherent or assigned to the entity.
Autonomic Identifier
a self-managing cryptonymous identifier that must be self-certifying (self-authenticating) and must be encoded in CESR as a qualified Cryptographic Primitive.
Autonomic Identifier
a self-managing cryptonymous identifier that must be self-certifying (self-authenticating) and must be encoded in CESR as a qualified Cryptographic Primitive.
Chain-link Confidential Disclosure
contractual restrictions and liability imposed on a recipient of a disclosed ACDC that contractually link the obligations to protect the disclosure of the information contained within the ACDC to all subsequent recipients as the information moves downstream. The Chain-link Confidential Disclosure provides a mechanism for protecting against unpermissioned exploitation of the data disclosed via an ACDC.
Compact Disclosure
a disclosure of an ACDC that discloses only the SAID(s) of some or all of its field maps. Both Partial and Selective Disclosure rely on Compact Disclosure.
Contractually Protected Disclosure
a discloser of an ACDC that leverages a Graduated Disclosure so that contractual protections can be put into place to minimize the leakage of information that can be correlated. A Contractually Protected Disclosure partially or selectively reveals the information contained within the ACDC in the initial interaction with the recipient and disclose further information only after the recipient agrees to the terms established by the discloser. More information may be progressively revealed as the recipient agrees to additional terms.
Controller
an entity that can cryptographically prove the control authority over an AID and make changes on the associated KEL. A controller of a multi-sig AID may consist of multiple controlling entities. See controller.
Disclosee
a role of an entity that is a recipient to which an ACDC is disclosed. A Disclosee may or may not be the Issuee of the disclosed ACDC.
Discloser
a role of an entity that discloses an ACDC. A Discloser may or may not be the Issuer of the disclosed ACDC.
Duplicity
the existence of more than one Version of a Verifiable KEL for a given AID. See duplicity.
Edge
a top-level field map within an ACDC that provides edges that connect to other ACDCs, forming a labeled property graph (LPG).
Framing Code
a code that delineate a number of characters or bytes, as appropriate, that can be extracted atomically from a Stream.
Full Disclosure
a disclosure of an ACDC that discloses the full details of some or all of its field maps. In the context of Selective Disclosure, Full Disclosure means detailed disclosure of the selectively disclosed attributes, not the detailed disclosure of all selectively disclosable attributes. In the context of Partial Disclosure, Full Disclosure means detailed disclosure of the field map that was so far only partially disclosed.
Graduated Disclosure
a disclosure of an ACDC that does not to reveal its entire content in the initial interaction with the recipient and, instead, partially or selectively reveal only the information contained within the ACDC that is necessary to further a transaction with the recipient. A Graduated disclosure may invole multiple steps where more information is prgressively revealed as the recipient satisfy the conditions set by the discloser. Compact disclosure, Partial disclosure, Selective disclosure and Full disclosure are all Graduated disclosure mechanisms.
Inception event
an Establishment event that provides the incepting information needed to derive an AID and establish its initial Key state. See inception event.
Information theoretic security
the highest level of cryptographic security with respect to a cryptographic secret (seed, salt, or private key).
Information theoretic security
the highest level of cryptographic security with respect to a cryptographic secret (seed, salt, or private key).
Interaction event
a Non-establishment event that anchors external data to the Key state as established by the most recent prior Establishment event. See interaction event.
Issuee
a role of an entity to which the claims of an ACDC are asserted.
Issuer
a role of an entity that asserts claims and creates an ACDC from these claims.
Key-state
a set of currently authoritative keypairs for an AID and any other information necessary to secure or establish control authority over an AID. This includes current keys, prior next key digests, current thresholds, prior next thresholds, witnesses, witness thresholds, and configurations. A key-state of an AID is first established through an inception event and may be altered by subsequent rotation events. See validator.
Operator
an optional field map in the Edge section that enables expression of the edge logic on edge subgraph as either a unary operator on the edge itself or an m-ary operator on the edge-group.
Partial Disclosure
a disclosure of an ACDC that partially discloses its field maps using Compact Disclosure. The Compact Disclosure provides a cryptographically equivalent commitment to the yet-to-be-disclosed content, and later exchange of the uncompacted content is verifiable to an earlier Partial Disclosure. Unlike Selective dDsclosure, a partially disclosable field becomes correlatable to its encompassing block after its Full Disclosure.
Percolated discovery
a discovery mechanism for information associated with an AID or a SAID, which is based on Invasion Percolation Theory. Once an entity has discovered such information, it may in turn share what it discovers with other entities. Since the information so discovered is end-verifiable, the percolation mechanism and percolating intermediaries do not need to be trusted.
Perfect security
a special case of Information theoretic security ITPS
Primitive
a serialization of a unitary value. All Primitives in KERI must be expressed in CESR.
Primitive
a serialization of a unitary value. All Primitives in KERI must be expressed in CESR.
Rotation event
an Establishment Event that provides the information needed to change the Key state which includes a change to the set of authoritative keypairs for an AID. See rotation event.
Rules
a top-level field map within an ACDC that provides a legal language as a Ricardian Contract [43, which is both human and machine-readable and referenceable by a cryptographic digest.
SEMVER
Semantic Versioning Specification 2.0. See also (https://semver.org)[https://semver.org]
Schema
the SAID of a JSON schema that is used to issue and verify an ACDC.
Selective Disclosure
a disclosure of an ACDC that selectively discloses its attributes using Compact Disclosure. The set of selectively disclosable attributes is provided as an array of blinded blocks where each attribute in the set has its own dedicated blinded block. Unlike Partial Disclosure, the selectively disclosed fields are not correlatable to the so far undisclosed but selectively disclosable fields in the same encompassing block.
Self-Addressing Identifier
any identifier which is deterministically generated out of the content, digest of the content
Stream
a CESR Stream is any set of concatenated Primitives, concatenated groups of Primitives or hierarchically composed groups of Primitives.
Targeted ACDC
an ACDC with the presence of the Issuee field in the attribute or attribute aggregate sections.
Unpermissioned correlation
a correlation established between two or more disclosed ACDCs whereby the discloser of the ACDCs does not permit the disclosee to establish such a correlation.
Untargeted ACDC
an ACDC without the presence of the Issuee field in the attribute or attribute aggregate sections.
Validator
any entity or agent that evaluates whether or not a given signed statement as attributed to an identifier is valid at the time of its issuance. See validator.
Verifiable data registry
A role a system might perform by mediating issuance and verification of ACDCs. See verifiable data registry.
Verifier
any entity or agent that cryptographically verifies the signature(s) and/or digests on an event Message. See verifier.
Weight
an optional field map in the Edge section that provides edge weight property that enables directed weighted edges and operators that use weights.
,
Autonomic Identifier (AID)
a self-managing cryptonymous identifier that must be self-certifying (self-authenticating) and must be encoded in CESR as a qualified Cryptographic Primitive.
Composability
short for text-binary concatenation composability. An encoding has Composability when any set of self-framing concatenated Primitives expressed in either the Text domain or Binary domain may be converted as a group to the other Domain and back again without loss.
Cryptographic Primitive
the serialization of a value associated with a cryptographic operation including but not limited to a digest (hash), a salt, a seed, a private key, a public key, or a signature.
Domain
a representation of a Primitive either Text (T), Binary (B) or Raw binary (R).
Framing Codes
codes that delineate a number of characters or bytes, as appropriate, that can be extracted atomically from a Stream.
Group/Count Codes
special Framing Codes that can be specified to support groups of Primitives which make them pipelinable. Self-framing grouping using Count Codes is one of the primary advantages of composable encoding.
Key Event Receipt Infrastructure (KERI)
or the KERI protocol, is an identity system-based secure overlay for the Internet.
Message
consists of a serialized data structure that comprises its body and a set of serialized data structures that are its attachments. Attachments may include but are not limited to signatures on the body.
Primitive
a serialization of a unitary value. All Primitives in KERI must be expressed in CESR.
Quadlet
a group of 4 characters in the T domain and equivalently in triplets of 3 bytes each in the B domain used to define variable size.
Stable
todo
Stream
any set of concatenated Primitives, concatenated groups of Primitives or hierarchically composed groups of Primitives.
Tritet
3 bits. See Performant resynchronization with unique start bits
Variable Length
a type of count code allowing for vaiable size signatures or attachments which can be parsed to get the full size
Version
the CESR Version is provided by a special Count Code that specifies the Version of all the the CESR code tables in a given Stream or Stream section.
Version String
the first field in any top-level KERI field map in which it appears.