Learning Digital Identity, from O'Reilly Media." /> Learning Digital Identity, from O'Reilly Media.">


This post is adapted from my forthcoming book, Learning Digital Identity, from O'Reilly Media.

Our physical wallets are, historically, for holding currency. But that may be the least interesting use case for wallets. Many of the things people put in their wallets represent relationships they have and authorizations they hold. Most people don't often leave home without their wallet.

But the analogy to a physical wallet can only take us so far, because as physical beings, our natural capabilities are multitude. In the digital world, we need tools to accomplish almost anything useful. The name wallet1 for the software we use to interact digitally doesn't do the tool justice.

A digital identity wallet is a secure, encrypted database that collects and holds keys, identifiers, and verifiable credentials (VCs). The wallet is also a digital address book, collecting and maintaining its controller's many relationships. The wallet is coupled with a software agent that speaks the protocols necessary to engage with others.

Wallets and agents are not the same thing, even though they're often conflated. Agents are tools for taking action. Wallets are where stuff is stored. Still, most people just say "wallet," even when they mean "wallet and agent." For this post, when I say "wallet" I mean wallet and when I say "agent" I mean agent.

Identity agents are software services that manage all the stuff in the wallet. Agents store, update, retrieve, and delete all the artifacts that a wallet holds. Beyond managing the wallet, agents perform many other important tasks:

  • Sending and receiving messages with other agents
  • Requesting that the wallet generate cryptographic key pairs
  • Managing encrypted data interactions with the wallet
  • Performing cryptographic functions like signing and verifying signatures
  • Backing up and retrieving data in the wallet
  • Maintaining relationships by communicating with other agents when DID documents are updated
  • Routing messages to other agents
The relationship between identity wallets and agents
The relationship between identity wallets and agents (click to enlarge)

This figure shows the relationship between an agent, a wallet, and the underlying operating system. While most current implementations pair a single agent with a single wallet, the presence of an API means that it's possible for one agent to use several wallets, or for multiple agents to access one wallet. Some specialized agents might not even need a wallet, such as those that just perform routing, although most will at least need to store their own keys.

The key-management functions in the wallet includes actions on cryptographic keys like generation, storage, rotation, and deletion. Key management is performed in cooperation with the operating system and underlying hardware. Ideally, the operating system and hardware provide a secure enclave for key storage and a trusted execution environment for performing key-management functions.

The basic functions shown in the diagram might not seem to have much to do with identity. Identity-related activities like authentication and credential exchange are built on top of these basic functions. The agent can issue, request, and accept VCs. The agent also presents and verifies credentials. Specialized messages perform these activities.

Agents and Credential Exchange

Agents speak a protocol called DIDComm (DID-based communication) that provides a secure communications layer for the exchange of identity information via verifiable credentials (VCs). Agents speak DIDComm to each other without a third-party intermediary (i.e., they're peer-to-peer). Because of DIDComm's flexibility and the ability to define protocols on top of DIDComm messaging, it promises to be as important as the identity layer it enables. The DIDComm protocol is governed by the DIDComm specification, hosted at the Decentralized Identity Foundation. The current ratified version is 2.0.

The specification's opening sentence states that "the purpose of DIDComm Messaging is to provide a secure, private communication methodology built atop the decentralized design of DIDs." Note that the specification describes DIDComm as a communications methodology. This means that DIDComm is more than just a way to send a message or chat with someone else. DIDComm messaging allows individual messages to be composed into application-level protocols and workflows. This makes DIDComm messaging a foundational technology for performing different kinds of interactions within the framework of trust that a DID-based relationship implies.

To enable the exchange of verifiable credentials, the agent, using the wallet as secure storage, performs three primary activities:

  1. Exchanging DIDs with other agents
  2. Requesting and issuing credentials
  3. Requesting and presenting credential proofs

The agent does these activities using protocols that run on top of DIDComm. DIDComm's job is to create a secure, mutually authenticated channel for exchanging DIDComm messages. The protocols that operate inside of it, carry out specific activities.

Exchanging DIDs

Agents take care of the tedious and tricky job of exchanging DIDs between parties who want to communicate so that people don't have to get entangled in the details of how DIDs work: how they're created, stored, and validated. Or the work that's necessary when one of the parties needs to rotate keys. The DIDComm v2 spec is capable of exchanging DIDs without a separate protocol so the process can be automated by smart identity agents working on behalf of the various parties.

Requesting and Issuing Credentials

Requesting and issuing credentials is defined in Aries RFC 0036: Issue Credential Protocol 1.0. The protocol "formalizes messages used to issue a credential." The protocol describes four primary messages: propose-credential, offer-credential, request-credential, and issue-credential. The protocol also defines the state machine that the agent operates in response to these messages. These messages combined with the state machine allow the credential issuer and the credential holder to engage is the ceremonies necessary for the issuer to issue a credential to the holder.

Requesting and Presenting Credential Proofs

Requesting and presenting credential proofs is defined in Aries RFC 0037: Present Proof Protocol 1.0. The protocol formalizes and generalizes message formats used for presenting a proof of the attributes in a credential. The protocol describes three primary messages: propose-proof, request-proof, and present-proof. The protocol also defines the state machine that the agent operates in response to these messages. These messages and state machine allow the credential holder and the credential verifier to engage in the ceremonies necessary for the holder to present a credential proof to the verifier.

The Nature of Wallets and Agents

Agents and wallets, working together, perform the work necessary for people, businesses, and devices to create mutually-authenticated, secure connections and use those connections to exchange verifiable credentials. People, businesses, and devices all have different needs and so they'll use different agents and wallets.

  • People will generally use agents and wallets running on smart phones, laptops, or other personal devices. Your Amazon Alexa, for example could have an agent/wallet pair installed on it to act on your behalf. Most people will have agents on every device. Most of these will have wallets associated with them. Wallets will use device secure enclaves to store sensitive cryptographic information. People will also have agents and wallets in the cloud. All of the agents and wallets under a person's control will interoperate with each other and perform different roles. For example, cloud-based agents are needed to route DIDComm messages to devices that may not have a routable IP address.
  • Businesses will use enterprise agents that are integrated with other enterprise systems like CRM, ERP, and IAM systems. The wallets associated with these will be more sophisticated than personal wallets since they have to manage DIDs and their associated keys that various employees, departments, and processes use. The ability to delegate authority and permission actions will be more rigorous than is needed in a personal wallet. A large business might operate thousands of enterprise agents for various business purposes.
  • Devices will use agents with associated wallets to create relationships and perform credential exchange with the device owner, other devices, their manufacturer, and other people or companies. How they operate and their sophistication depend in great measure on the nature of the device and its expected function. I wrote about the reasons for using agents as part of IoT devices in The Self-Sovereign Internet of Things.

Despite differences that these agents exhibit, they all run the same protocols and use DIDComm messaging. There are no intermediaries—the connections are all peer-to-peer. Every agent works on behalf of the entity who controls it. To get a feel for how they might interoperate, see Operationalizing Digital Relationships and SSI Interaction Patterns.

DIDComm-capable agents can be used to create sophisticated relationship networks that include people, institutions, and things. The relationships in that network are rich and varied—just like relationships in the real world. Smart agents allow people, business and devices to create, manage, and utilize secure, trustworthy communications channels with anyone online without reliance on any third party. The agent serves as flexible digital tool that people can use to manage their digital life.


  1. I've heard various people object to the term wallet, but so far, no one has come up with anything else that has stuck, so for now, wallet is the word the industry uses.

Please leave comments using the Hypothes.is sidebar.

Last modified: Fri Dec 16 10:08:27 2022.