The Hitchhiker’s Guide to KERI. Part 3: How do you use KERI?

This blog is the third part of a three-part series, the Hitchhiker’s Guide to KERI:

• Part 1: Why should you adopt KERI?
• Part 2: What exactly is KERI?
• Part 3: How do you use KERI?

Now that you grasp the rationale underpinning the adoption of KERI and have acquired a foundational understanding of its principles, this part of the series is dedicated to elucidating the preliminary steps necessary for embarking upon a journey with KERI and the development of applications grounded in its framework.

The resources provided below, while presented in no particular order, serve to supplement your exploration of KERI. Moreover, this blog will serve as an implementer guide to further deepen your understanding and proficiency in utilizing KERI.

Photo by Ilya Pavlov on Unsplash

Read the Whitepaper

The Key Event Receipt Infrastructure (KEI) protocol was first introduced in the KERI whitepaper by Dr. Samuel M. Smith in 2019. The whitepaper kickstarts the development of the entire ecosystem.

While the KERI whitepaper undoubtedly offers invaluable insights into the intricate workings and underlying rationale of the protocol, I would caution against starting your KERI journey with it. Its length exceeding 140 pages, may pose a significant challenge for all but a few cybersecurity experts. It is advisable to revisit the whitepaper once you have firmly grasped the foundational concepts of KERI. Nevertheless, should you be inclined towards a more rigorous learning approach, you are certainly encouraged to undertake the endeavor.

The KERI Whitepaper, first published July 2019.

I also recommend related whitepapers by Dr. Samuel M. Smith as follows:

• Universal Identifier Theory: a unifying framework for combining autonomic identifiers (AID) with human meaningful identifiers.
• Secure Privacy, Authenticity, and Confidentiality (SPAC): the whitepaper that laid the foundation for the ToIP trust-spanning protocol.
• Sustainable Privacy: a privacy-protection approach in the KERI ecosystem.

Read Introductory Contents

Before delving into the whitepaper and related specifications, I recommend the following introductory materials, which helped me personally:

• KERI Presentation at SSI Meetup Webinar, given by the originator of KERI, Dr. Samuel M. Smith, himself
• KERI for Muggles, by Samuel M. Smith and Drummond Reed. This was a presentation given at the Internet Identity Workshop #33.

Note: the author of this blog was first exposed to KERI by this presentation.

• Section 10.8 of “Self-Sovereign Identity” by Alex Preukschat & Drummond Reed, Manning Publication (2021). This section was also written by Dr. Samuel M. Smith.
• The Architecture of Identity Systems, by Phil Windley. Written by one of the most prominent writers in the SSI ecosystem, Phil compared administrative, algorithm, and autonomic identity systems.
• KERISSE, by Henk van Cann and Kor Dwarshuis, this an educational platform as well as a search engine for the KERI ecosystem.

More resources can also be found at https://keri.one/keri-resources/. Of course, this Hitchhiker’s Guide to KERI series has also been written as one such introductory content.

“Self-Sovereign Identity” by Alex Preukschat & Drummond Reed

Read the KERI and Related Specifications

As of 2024, the specifications for KERI and related protocols are being developed by the ACDC (Authentic Chained Data Container) Task Force under the Trust over IP (ToIP) Foundation. Currently, there are four specifications:

• Key Event Receipt Infrastructure (KERI): the specification for the KERI protocol itself.
• Authentic Chained Data Containers (ACDC): the specification for the variant of Verifiable Credentials (VCs) used within the KERI ecosystem.
• Composable Event Streaming Representation (CESR): the specification for a dual text-binary encoding format used for messages exchanged within the KERI protocol.
• DID Webs Method Specification: the specification did:webs method that improves the security property of did:web with the KERI protocol.

KERI Specification v1.0 Draft

There are also two related protocols, which do not have their own dedicated specifications:

• Self-Addressing Identifier (SAID): a protocol for generating identifiers used in the KERI protocol. Almost all identifiers in KERI are SAIDs, including AIDs, ACDCs’ identifiers, and schemas’ identifiers.
• Out-Of-Band-Introduction (OOBI): a discovery mechanism for AIDs and SAIDs using URLs.

To learn about these specifications, I also recommend my blog, the KERI jargon in a nutshell series.

Note: The KERI community intends to eventually publish the KERI specifications in ISO. However, this goal may take several years to achieve.

Check out the KERI Open-Source Projects

The open-source projects related to the KERI protocols and their implementations are hosted in WebOfTrust Github, all licensed under Apache Version 2.0.

Note: Apache License Version 2.0 is a permissive open-source software license that allows users to freely use, modify, and distribute software under certain conditions. It permits users to use the software for any purpose, including commercial purposes and grants patent rights to users. Additionally, it requires users to include a copy of the license and any necessary copyright notices when redistributing the software.

Here are some of the important projects being actively developed by the KERI community:

Reference Implementation: KERIpy

The core libraries and the reference implementation for the KERI protocol have been written in Python, called KERIpy. This is by far the most important project that all other KERI projects are based on.

• KERIpy (Python): https://github.com/WebOfTrust/keripy

KERIpy is also available in Dockerhub and PyPI:

• Dockerhub: https://hub.docker.com/r/weboftrust/keri
• PyPI: https://pypi.org/project/keri/

Edge Agent: Signify

The KERI ecosystem follows the principle of “key at the edge (KATE),” that is, all essential cryptographic operations are performed at edge devices. The Signify projects have been developed to provide lightweight KERI functionalities at edge devices. Currently, Signify is already in Python and Typescript.

• SignifyPy (Python) https://github.com/WebOfTrust/signifypy
• Signify-TS (Typescript) https://github.com/WebOfTrust/signify-ts

Signify is also available in PyPI and NPM:

• PyPI: https://pypi.org/project/signifypy/
• NPM: https://www.npmjs.com/package/signify-ts

Cloud Agent: KERIA

Signify is designed to be lightweight and is reliant on a KERI cloud agent, called KERIA. KERIA helps with data storage and facilitates communication with external parties. As mentioned above, all essential cryptographic operations are performed at the edge using KERIA. Private and sensitive data are also encrypted at the edge before being stored in a KERIA server.

• KERIA (Python): https://github.com/WebOfTrust/keria

KERIA is also available in Dockerhub:

• Dockerhub: https://hub.docker.com/r/weboftrust/keria

Browser Extension: Polaris

The browser extension project is based on Signify-TS for running in browser environments. There is also a companion repository called the Polaris Web for building frontend applications that are compatible with the Signify browser extension.

• Signify Browser Extension: https://github.com/WebOfTrust/signify-browser-extension
• Polaris web: https://github.com/WebOfTrust/polaris-web

Note: The Signify browser extension project was funded by Provanant Inc. and developed by RootsID. The project has been donated to the WebOfTrust Github project under Apache License Version 2.0.

Study KERI Command Line Interface (KLI)

Once you grasp the basic concept of KERI, one of the best ways to start learning about the KERI protocol is to work with the KERI command line interface (KLI), which uses simple bash scripts to provide an interactive experience.

I recommend the following tutorials on KLI:

• KERI & OOBI CLI Demo, by Phillip Feairheller & Henk van Cann.
• KERI KLI Tutorial Series, by Kent Bull. Currently, two tutorials are available: (1) Sign & Verify with KERI and (2) Issuing ACDC with KERI.

Many more examples of KLI scripts can be found in the KERIpy repository, at:

• KLI demo scripts: WebOfTrust/keripy/scripts/demo.

While KLI is a good introductory program for learning the KERI protocol, it is crucial to note that KLI is not suitable for developing end-user (client-side) applications in a production environment.

Note: KLI can be used in production for server-side applications.

KERI KLI Series: Sign and Verify by Kent Bull

Build an App with Signify and KERIA

For building a KERI-based application in production environments, it is recommended by the KERI community to utilize Signify for edge agents and KERIA for cloud agents. These projects were specifically designed to complement each other, enabling the implementation of “key at the edge (KATE)”. That is, essential cryptographic operations are performed at edge devices, including key pair generation and signing, while private and sensitive data are encrypted before being stored in an instance of KERIA cloud agent.

The Signify-KERIA protocol by Philip Feairheller can be found here:

• Signify/KERIA Request Authentication Protocol (SKRAP): https://github.com/WebOfTrust/keria/blob/main/docs/protocol.md

The API between a Signify client and KERIA server can be found here:

• KERI API (KAPI): https://github.com/WebOfTrust/kapi/blob/main/kapi.md

Example Signify scripts for interacting with a KERIA server can also be found here:

• Example scripts: https://github.com/WebOfTrust/signify-ts/tree/main/examples/integration-scripts

Join the KERI Community!

To embark on your KERI journey, I recommend joining the KERI community. As of April 2024, there are three primary ways to engage:

Join the WebOfTrust Discord Channel

The WebOfTrust Discord channel is used for casual discussions and reminders for community meetings. You can join with the link below:

• https://discord.gg/YEyTH5TfuB.

Join the ToIP ACDC Task Force

The ACDC Task Force under the ToIP foundation focuses on the development of the KERI and related specifications. It also includes reports on the news and activities of the community’s members as well as in-depth discussions of related technologies.

The ACDC Task Force’s homepage can be found here:

• https://wiki.trustoverip.org/display/HOME/ACDC+(Authentic+Chained+Data+Container)+Task+Force

Currently, they hold a meeting weekly on Tuesdays:

• NA/EU: 10:00–11:00 EST / 14:00–15:00 UTC
• Zoom Link: https://zoom.us/j/92692239100?pwd=UmtSQzd6bXg1RHRQYnk4UUEyZkFVUT09

For all authoritative meeting logistics and Zoom links, please see the ToIP Calendar.

Note: While anyone is welcome to join meetings of ToIP as an observer, only members are allowed to contribute. You can join ToIP for free here.

Join the KERI Implementer Call

Another weekly meeting is organized every Thursday:

• NA/EU: 10:00–11:00 EST / 14:00–15:00 UTC
• Zoom link: https://us06web.zoom.us/j/81679782107?pwd=cTFxbEtKQVVXSzNGTjNiUG9xVWdSdz09

In contrast to the ToIP ACDC Task Force’s meeting, the implementer call focuses on the development and maintenance of the open-source projects in WebOfTrust Github. As a result, the weekly Thursday meetings tend to delve deeper into technical details.

Note: There is also a weekly meeting on DID Webs Method every Friday. See the ToIP DID WebS Method Task Force’s homepage here: https://wiki.trustoverip.org/display/HOME/DID+WebS+Method+Task+Force.