KERI jargon in a nutshell. Part 3: OOBI and IPEX.

• Part 1: KERI and AID.
• Part 2: SAID and ACDC.
• Part 3: OOBI and IPEX.
• Part 4: CESR and CESR-Proof Signatures.
• Part 5: TEL and PTEL.

TL;DR 1: The OOBI protocol allows the discovery of AIDs and SAIDs using the existing IP and DNS infrastructure. However, the OOBI by itself is insecure, and the information discovered by the OOBI must be verified.

TL;DR 2: The IPEX protocol is a protocol for the issuance and presentation of ACDCs that enable contractually protected disclosure. A discloser of an ACDC may initially disclose the content of the ACDC partially or selectively and may reveal more content after the disclosee agrees to contractual terms.

This blog continues from the KERI jargon in a nutshell Part 1 and Part 2. The third part here explores the OOBI (Out-Of-Band-Introduction) and IPEX (Issuance and Presentation Exchange Protocol) protocols that are utilized for message discovery and exchanges within the KERI ecosystem.

These topics are currently under the standardization process by Internet Engineering Task Force (IETF). I recommend avid readers and developers to check out their IETF drafts, which can be found here:

• KERI Community: https://github.com/WebOfTrust/keri
• OOBI IETF Draft: https://datatracker.ietf.org/doc/draft-ssmith-oobi/
• IPEX IETF Draft: https://github.com/WebOfTrust/ietf-ipex

Table of Contents

· OOBI (Out-Of-Band-Introduction)
∘ Basic OOBI
∘ OOBI as a URL
∘ Security Implication
· IPEX (Issuance and Presentation Exchange Protocol)
∘ Step 1: Apply [Disclosee]
∘ Step 2A: Spurn [Discloser]
∘ Step 2B: Offer [Discloser]
∘ Step 3A: Spurn [Disclosee]
∘ Step 3B: Agree [Disclosee]
∘ Step 4A: Spurn [Discloser]
∘ Step 4B: Grant [Discloser]
∘ Step 5: Admit [Disclosee]

Photo by Brett Jordan on Unsplash

OOBI (Out-Of-Band-Introduction)

An Out-Of-Band Introduction (OOBI) is a protocol for discovering verifiable information on an AID (Autonomic Identifier) or a SAID (Self-Addressing Identifier) within the KERI ecosystem. The OOBI protocol acts as a service endpoint that associates a URI or URL with either an AID or a SAID.

The OOBI protocol allows KERI to leverage the existing IP and DNS infrastructure for discovery. Hence, KERI does not need its own dedicated discovery network.

The OOBI protocol is “out-of-band” as it enables any internet and web search infrastructure to act as an “out-of-band” infrastructure to discover information that is verified using the “in-band” KERI protocol.

Common usages of the OOBI protocol include:

• Discovery of a Key Event Log (KEL) of an AID,
• Discovery of a Key Event Receipt Log (KERL) of an AID from one of its witnesses, and
• Discovery of a Self-Addressing Data (SAD) of a SAID.

Basic OOBI

The basic form of an OOBI is a tuple that contains both a KERI AID (or a SAID) and a URL (or URI).

(url, aid)

The URL typically includes the word “oobi” in its path to indicate that that URL is to be used as an OOBI. For example, an OOBI may associate a URL http://93:184:216:34:8080/oobi or http://example.comwith an AID EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM as follows:

("http://93.184.216.34:8080/oobi", "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM")

("http://example.com/oobi", "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM")

In this example, the OOBI’s URL may be used to discover the AID’s key event log.

OOBI as a URL

A URL and an AID can be combined into one namespaced URL where the AID’s prefix is in the path component of the URL. This makes the URL self-describing. For example, the above example may be represented as one URL, as follows:

# http://{ipaddress}:{port}/oobi/{controller_aid}
http://8.8.5.6:8080/oobi/EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM

A role of the AID may also be added at the end of the URL such as controller, witness, andwatcher.

http://8.8.5.6:8080/oobi/EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM/controller

Another example of a URL OOBI is to include both a controller’s AID and its witness’s AID, as follows:

# http://{ipaddress}:{port}/oobi/{controller_aid}/witness/{witness_aid}
http://8.8.5.6:8080/oobi/EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM/witness/BrHLayDN-mXKv62DAjFLX1_Y5yEUe0vA9YPe_ihiKYHE

where EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM is the AID of the controller whereas BrHLayDN-mXKv62DAjFLX1_Y5yEUe0vA9YPe_ihiKYHE is the AID of the controller’s witness.

Note: In the KERI community, the word “OOBI” is often used as a countable noun. “An OOBI” often refers to a URL that points to a resource related to an AID or a SAID whereas “OOBIs” refer to a collection of such URLs.

Security Implication

“An OOBI by itself is considered insecure with respect to KERI.”

IP infrastructure is not trusted by KERI, and a KERI OOBI by itself is considered insecure with respect to KERI. Hence, any information discovered by the OOBI must be verified by other means. For example,

• A KEL or a KERL discovered from an OOBI of an AID must be verified with the KERI protocol. That is to verify that all key events are consistent, all signatures from the controller are valid, and no duplicity is detected.
• A SAD discovered from an OOBI of a SAID must be verified with the SAID protocol. That is to verify that the SAID is really defined from the obtained SAD.

The policy for verifying and accepting the information discovered by the OOBI protocol is called BADA (Best-Available-Data-Acceptance), which is discussed in the following section.

Note 1: Everything in KERI or that depends on KERI is end-verifiable, therefore it has no security dependency nor does it rely on security provided by web or internet infrastructure.

Note 2: KERI AIDs are derived in a completely decentralized manner, and the root-of-trust of a KERI AID is completely independent of internet and DNS addressing infrastructure. Thus an IP address or URL could be considered a type of Out-Of-Band Infrastructure (OOBI) for KERI. We call this a KERI OOBI (Out-Of-Band-Introduction) and is a special case of Out-Of-Band-Infrastructure (OOBI) with a shared acronym.

IPEX (Issuance and Presentation Exchange Protocol)

The Issuance and Presentation Exchange (IPEX) Protocol is a secure mechanism for the issuance and presentation of Authentic Chained Data Containers (ACDCs).

Unlike W3C Verifiable Credentials (VCs), where two different protocols are required for issuance and presentation, IPEX works for both. While W3C VCs are exchanged between three parties—namely an issuer, a holder, and a verifier—IPEX simplifies the exchange protocol by modeling it as disclosure of information by a Discloser to a Disclosee. This approach has two advantages:

• Enhanced security: A simpler protocol can be designed and analyzed to minimize and mitigate attacks.
• Convenience: A simpler protocol is easier to implement, support, update, understand, and adopt.

The IPEX protocol leverages properties of KERI and ACDCs, including ancillary protocols such as CESR, SAIDs, and CESR-Proofs. Through its support for Ricardian contracts and graduated disclosure, IPEX allows the disclosure of an ACDC to achieve contractually protected disclosure—including chain-link confidentiality.

Graduated disclosure reveals the content of an ACDC compactly, partially, or selectively. More content of the ACDC may be gradually revealed in a series of interactions, i.e., in a graduated manner.

Contractually protected disclosure leverages graduated disclosure to contractually protect the discloser. The disclosure minimally reveals the content of the ACDC to the disclosee using, e.g., partial disclosure. The discloser may reveal more content only after the disclosee agrees to the contractual terms provided in the prior disclosure.

Chain-link confidentiality contractually links the terms and obligations agreed by the initial recipient of the ACDC to subsequent recipients. That is, subsequent recipients of the ACDC must, at the very least, agree to the same contractual terms.

Given a discloser and a disclosee who wish to exchange an ACDC, IPEX has the following 5-step exchange protocol:

IPEX (Issuance and Presentation Exchange Protocol) Protocol (Reference: IPEX IETF Draft)

Step 1: Apply [Disclosee]

The disclosee sends an ‘Apply’ message to the discloser to request for a disclosure of an ACDC. The message’s content includes:

• a schema (or its SAID) of the requested ACDC,
• an optional list of requested attribute fields for selective disclosure,
• a signature on the ‘Apply’ message (or its SAID).

Note: If a graduated disclosure is not required in the exchange, the IPEX protocol may skip to Step 4 to fully disclose the ACDC.

Step 2A: Spurn [Discloser]

If the discloser does not wish to disclose the requested ACDC, the discloser may reject the Apply message and terminate the exchange interaction.

Step 2B: Offer [Discloser]

If the discloser wishes to disclose the ACDC but does not yet wish to disclose the whole content of the ACDC, the discloser may send an ‘Offer’ message that includes:

• a schema (or its SAID) of the offered ACDC,
• a metadata ACDC (or its SAID) that includes partial or selective disclosure of the content of the actual ACDC,
• a signature on the ‘Offer’ message (or its SAID).

The metadata ACDC is used to initiate a contractually-protected exchange without leaking correlation to the actual ACDC. The metadata ACDC may also contain contractual terms (as Ricardian contracts) in the "r" section, of which the disclosee must agree to further the graduated interaction.

Note 1: A metadata ACDC is an ACDC with an empty top-level UUID (Universal Unique Identifier) field, "u": "". The purpose of a metadata ACDC is to provide a mechanism for a discloser to make cryptographic commitments to the metadata of a yet-to-be-disclosed ACDC without providing any correlation to that yet-to-be-disclosed ACDC.

Note 2 Since all the variants of an ACDC are various degrees of expansion of the compact variant, a signature on any variant of the ACDC (compact, full, partial, etc.) makes a cryptographic commitment to all variants of that ACDC. Therefore, a signature on any variant may be used to verify the Issuer’s commitment to any other variant either directly or indirectly. In other words, any variant may be used in a graduated disclosure even if it is not the variant that the issuer signs. This property even applies to the metadata variant.

Step 3A: Spurn [Disclosee]

If the disclosee is not satisfied by the revealed information or does not agree to the contractual terms provided in the metadata ACDC, the disclosee may reject the ‘Offer’ message. Consequently, the exchange interaction may be terminated, or the discloser and the disclosee may negotiate for a new ‘Offer’ message, i.e., going back to Step 2.

Step 3B: Agree [Disclosee]

If the disclosee is satisfied by the revealed information and agrees to the contractual terms provided in the metadata ACDC, the disclosee may sign the Offer message (or its SAID). The disclosee then returns an ‘Agree’ message that contains the signed ‘Offer’ message to the discloser.

The discloser can retain the ‘Agree’ message as digital proof that the disclosee has non-repudiably signed and agreed to the contractual terms. In the event of a breach of the contractual terms, the discloser can use this digital proof to hold the disclosee legally accountable.

Step 4A: Spurn [Discloser]

The discloser may reject the ‘Agree’ message and refuse to disclose more content of the ACDC.

Step 4B: Grant [Discloser]

If the discloser decides to further the graduated interaction with the disclosee, the discloser may send a ‘Grant’ message to the disclosee that discloses more or the full content of the ACDC. The ‘Grant’ message includes:

• full disclosure of the ACDC or partial/selective disclosure that discloses more of its content,
• a signature on the ‘Grant’ message (or its SAID).

Step 5: Admit [Disclosee]

The disclosee signs the ‘Grant’ message (or its SAID) and return it as an ‘Admit’ message to the discloser.

Again, the discloser can retain the ‘Admit’ message as non-repudiable digital proof that the disclosee has admitted the disclosure of the ACDC.

Note: The exchange interaction may be repeated so that the discloser may progressively reveal more content of the ACDC as the disclosee agrees to more contractual terms.