# Web5 Terminology

Web5 is enabled by several foundational technologies, each of which is defined by a standard:

- [Decentralized Identifiers](https://www.w3.org/TR/did-core/)
- [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/)
- [DWeb Node personal datastores](https://identity.foundation/decentralized-web-node/spec/)

The [Web5-js library](https://github.com/TBD54566975/web5-js) is an open source project that provides a toolkit for building decentralized web applications leveraging these components that are interoperable, secure, and user-controlled.

The foundational technologies of DIDs, VCs, and DWNs have been organized as depicted in the diagram below. [Agents](#Agents), [Identity Vaults](#Identity-Vaults), [Data Stores](#Data-Stores), and [Key Stores](#Key-Stores) are all important components of decentralized identity and decentralized web systems, but they serve different functions and interact with each other in different ways. We'll begin by defining each and providing some context for the capabilities they provide.


***Note**: In the diagram above, figures with hashed line backgrounds (e.g., keys, profile, DIDs, etc.) indicate that Agents interact with these objects via the component they reside in but are actually managed & stored by another component. Objects appear with solid backgrounds in the component they are managed & stored by. For example, while keys are accessed through a specific [Account](#Accounts) in an [Identity Vault](#Identity-Vaults), they are physically stored and secured by a [Key Store](#Key-Stores). Three types of [Key Stores](#Key-Stores) are shown in the example, which use different approaches to storing/securing keys: browser local storage, TPM/SE, and DWN data store.*

## Notes on Terminology

- For simplicity and readability the term "user" appears frequently but can be understood to mean any one of: person, organization, or device.

## Agents

An [Agent](#Agents) is defined as a software program that acts on behalf of a user to manage identity information, public/private data, and interactions with other entities in a decentralized network. These capabilities are enabled by the [Identity Vaults](#Identity-Vaults), [Data Stores](#Data-Stores), and [Key Stores](#Key-Stores) components that an [Agent](#Agents) interacts with.

The key features facilitated by an _**Agent**_ include:

- Secure storage of data: An agent securely stores and manages the data of people, organizations, devices, and other entities, including private/public information, credentials, and any other data relevant to their identity.
- Messaging and communication: An agent can communicate with other agents and entities in the decentralized network, using standardized messaging protocols and decentralized identifiers (DIDs).
- Interoperability with other agents and networks: An agent is designed to work seamlessly with other agents and decentralized identity networks, enabling entities to easily connect and transact with others in a decentralized ecosystem.
- User-controlled sharing of data: An agent allows entities to selectively share their data with other parties on a need-to-know basis, without revealing any unnecessary information.
- Identity verification and authentication: An agent provides the necessary tools and protocols for verifying and authenticating the an entity's identity in a decentralized network.
- Identity revocation and recovery: An agent allows entities to revoke or recover their identity credentials in case of loss, theft, or compromise.
- Privacy and anonymity: An agent provides entities with the ability to maintain their privacy and anonymity while still participating in a decentralized identity network.

This [Web5 library](https://github.com/TBD54566975/web5-js) can be used to build [Agents](#Agents) for a variety of deployment environments, including:

- Cloud Instances
- Desktop OS (macOS, Linux, Windows)
- Mobile OS (Android, iOS)
- Web Browsers

## Identity Vaults

While an [Agent](#Agents) can be thought of as an intermediary that facilitates the interactions and exchange of information between entities (people, devices, issuers, verifiers, etc.), an [Identity Vault](#Identity-Vaults), on the other hand, provides users with greater control over their personal identity information and how it is shared with others. [Identity Vaults](#Identity-Vaults) are also commonly referred to as _identity wallets_ or just _wallets_.

Unlike traditional identity systems, which are often centralized and controlled by third-party entities such as governments or corporations, decentralized [Identity Vaults](#Identity-Vaults) allow users to manage their own identity data in a secure and privacy-preserving manner.

An [Identity Vault](#Identity-Vaults) typically manages private keys, verifiable credentials, and decentralized identifiers, and enables the user to perform functions such as authentication, signing, verification, and selective sharing of identity data.

[Agents](#Agents) and [Identity Vaults](#Identity-Vaults) interact in a variety of ways. For example:

- **Authentication**: Agents can use a user's DID or credentials stored in their Identity Vault to authenticate the user for a particular service or application.
- **Credential Issuance**: Agents can also act of behalf of the user to apply for and store credentials in the user's Identity Vault. The Identity Vault provides a secure storage environment for the credentials, while the Agent handles the issuance process.
- **Verification**: When a user wants to present their credentials to a third-party verifier, the Agent can access the user's Identity Vault to provide the necessary credentials and attestations. The verifier can then verify the authenticity and validity of the credentials.

While [Identity Vaults](#Identity-Vaults) surface capabilities such as cryptographic key generation, storage, and signing, they rely on a [Key Store](#Key-Stores), which is a secure storage environment for private keys.

Expected methods for [Identity Vaults](#Identity-Vaults) include:

- `backupVault`: This method would create a backup of the entire vault, including all associated data and credentials, in a secure and portable format.
- `restoreVault`: This method would restore a backup of the vault, including all associated data and credentials, to a new or existing vault.
- `changeMasterKey`: This method would allow the user to change the vault's master key or passphrase, for increased security.
- `enableBiometrics`: Enable use of biometric authentication (facial or fingerprint recognition) to unlock the vault.
- `disableBiometrics`: Disable use of biometric authentication.
- `lockVault`: This method would lock the vault, requiring the user to enter the master key or passphrase to access its contents.
- `unlockVault`: This method would unlock the vault, allowing the user to access its contents after entering the correct master key or passphrase.
- `getVaultStatus`: This method would return the current status of the vault, including whether it is locked or unlocked, and whether any errors or warnings are present.

### Accounts

A [Account](#Accounts) is an isolated space within an [Identity Vault](#Identity-Vaults) that stores and manages a specific set of identity data that are relevant to a particular context or use case. A [Account](#Accounts) might also be referred to as a _Context_ or _Identity Container_ (or just _Container_).

For example, a person might have one [Account](#Accounts) within their [Identity Vault](#Identity-Vaults) for their work-related identity data, another [Account](#Accounts) for personal/family, and yet another [Account](#Accounts) for their social media identity.

By organizing identity keys, profile information, data, and credentials into separate [Accounts](#Accounts), an [Identity Vault](#Identity-Vaults) can help users maintain greater control over their personal information and how it is shared with others. Users can choose which [Account](#Accounts) to share with different parties, depending on the context and level of trust involved.

Expected methods for [Accounts](#Accounts) include:

- `createAccount`: This method would create a new Account for the user, such as a work or social context, allowing the user to segregate their different personas and identities. Optionally, would generate a new key pair if one wasn't provided.
- `switchAccount`: This method would switch the user's current Account within the Identity Vault, allowing them to access different personas and identities as needed.
- `importAccount`: This method would import an existing Account for the user, including the user's public and private keys and any associated personal data and preferences.
- `exportAccount`: This method would export the Account, including all associated data and credentials, in a portable format that can be imported into another system.
- `deleteAccount`: This method would delete an existing Account for the user, including all associated public and private keys and personal data.
- `listAccounts`: This method would list all the Account objects in the vault.
- `setProfileData`: This method would set or update the user's personal data within the Account, such as their name, email address, or profile picture.
- `getProfileData`: This method would retrieve the user's personal data from the Account.
- `getPublicKey`: This method would retrieve the user's public key from the Account, which can be used to verify digital signatures and other cryptographic operations.
- `signData`: This method would use the user's private key within the Account to sign a specific piece of data, such as a transaction or message.
- `verifyData`: This method would use the user's public key within the Account to verify the signature on a specific piece of data.

## Key Stores

A [Key Store](#Key-Stores) is a secure storage environment for a user's private keys, which are used to authenticate the user's identity and sign transactions across a range of decentralized applications and platforms.

The following features are typically expected of a key store:

- **Security**: The key store should provide strong security measures to protect private keys from unauthorized access or theft. This might include using encryption, multi-factor authentication, and other security best practices.
- **Usability**: The key store should provide a developer-friendly API with a clear and intuitive interface for managing private keys and other related information.
- **Interoperability**: The key store should be designed to work with a variety of decentralized identity protocols and systems, allowing the user to use their private keys across different applications and platforms.
- **Backup and recovery**: The key store should have robust backup and recovery mechanisms, allowing the user to recover their private keys in the event of a lost or stolen device or other unforeseen circumstances.
- **Access control**: The key store should allow the user to control who has access to their private keys and under what conditions, helping to prevent unauthorized use or theft of their identity.
- **Compatibility**: The key store should be compatible with a range of devices and platforms, including desktop computers, mobile devices, and other types of hardware.

Expected methods for a [Key Store](#Key-Stores) include:

- `generateKey`: This method would generate a new public/private key pair for the user.
- `storeKey`: This method would store the user's private key in the key store, associated with a specific [Account](#Accounts). This method would not be implemented in the case of a TPM/Secure Element Key Store.
- `getKey`: This method would retrieve the user's private key from the key store. This method would not be implemented in the case of a TPM/Secure Element Key Store.
- `deleteKey`: This method would delete the user's private key from the key store.
- `exportKey`: This method would export the user's private key from the key store in a specific format, such as PEM or JWK. This method would not be implemented in the case of a TPM/Secure Element Key Store.
- `importKey`: This method would import a private key into the key store from a specific format, such as PEM or JWK. This method may not be implemented in the case of a TPM/Secure Element Key Store.
- `getPublicKey`: This method would retrieve the user's public key from the key store.
- `setPassphrase`: This method would set or update the passphrase or password used to access the key store.
- `sign`: This method would use the user's private key to sign a specific piece of data, such as a transaction or message.
- `verify`: This method would use the user's public key to verify the signature on a specific piece of data.
- `encrypt`: This method takes the data to be encrypted, a key ID, and an encryption algorithm as input parameters. It applies the encryption algorithm on the data using the specified private key, returning the encrypted data.
- `decrypt`: This method requires the encrypted data, a key ID, and algorithm as input parameters. It applies a decryption algorithm on the encrypted data using the provided key, returning the decrypted data.

All methods that access key material would be scoped by the [Account](#Accounts), such that the Work [Account](#Accounts) couldn't access/mutate the key material associated with the Social [Account](#Accounts).

## Data Stores

A personal datastore, such as a Decentralized Web Node (DWN), is a data storage and message relay mechanism that enables users to store and manage their data in a secure and decentralized manner and to locate public or private permissioned data related to a given Decentralized Identifier (DID).

In addition to facilitating the exchange of identity information, [Agents](#Agents) also facilitate secure data storage, data sharing, and messaging in a decentralized web ecosystem by leveraging the capabilities of a DWN.

Typically, this would involve an Agent coordinating the interaction between the [Identity Vault](#Identity-Vaults) and [Data Stores](#Data-Stores). For example, an Agent might use the [Key Store](#Key-Stores) associated with a user's social [Account](#Accounts) DID to sign a DWN message that is then transported over HTTPS to a remote user's DWN. Similarily, an Agent could facilitate the signing of a message with the user's personal [Account](#Accounts) to be transported via HTTPS to a participating financial institution (PFI).

More detailed technical information can be found in the [DIF DWN Spec](https://identity.foundation/decentralized-web-node/spec/) and dwn-sdk-js reference implementation.

## FAQ

### Why use the term "Identity Vault" and not "Wallet"?

"Wallet" is an overloaded term in the identity space and often means different things to different people/projects. Additionally, while familiar to novice end users, "wallet" can also be confusing when users assume a high degree of similarity to physical wallets or assume that it implies a connection to financial transactions.

The term "identity vault" may be less confusing for end users, as it better conveys the idea of a secure storage space for identity-related information. It also avoids the potential confusion with financial transactions that can arise from the use of the term "wallet."

### What is the difference between a *key store* and a *keychain*?

A *key store* and a *keychain* are similar concepts, but they may have slightly different meanings depending on the context.

In the context of decentralized identity, a key store is a secure storage environment for a user's private keys, which are used to authenticate the user's identity, encrypt data, or sign transactions. A key store is typically designed to work with a variety of decentralized identity protocols and systems, allowing the user to use their private keys across different applications and platforms.

On the other hand, a keychain is a similar concept, but is typically used in the context of operating systems, such as macOS or iOS. A keychain is a secure storage mechanism for sensitive information such as passwords, certificates, and private keys, which are used to authenticate the user and provide access to various system resources and applications. A keychain is typically designed to work with the operating system's built-in security mechanisms, and may be integrated with other security features such as Touch ID or Face ID.

### What are other names for "key store"?

In the context of decentralized identity, a key store is also commonly referred to as a "key manager" or "private key manager." Other possible names for a key store might include a "keychain," "keyring," or "crypto wallet," although these terms may be more commonly associated with cryptocurrency wallets and may not convey the specific purpose of a key store in a decentralized identity ecosystem.

### Isn't a Profile and Account the same thing?

No, a "profile" is not the same as an "account" in the context of decentralized identity systems. While both terms relate to the management of identity information, they refer to different aspects of the identity ecosystem.

An Account refers to a specific digital space within a decentralized Identity Vault where a user's identity data area stored and managed. Each Account is typically associated with a specific context or use case, such as work, personal, or social interactions.

On the other hand, a profile generally refers to a collection of identity attributes that describe a person or entity. A profile may include a variety of personal information, such as name, address, age, and contact information, as well as more specialized attributes such as professional qualifications, social media profiles, or purchase history. In the context of decentralized identity, a profile might be associated with a particular Account, but it does not refer to the Account itself.