Web5 Crypto API

| A cryptography and JOSE library for building secure Web5 applications |
| --------------------------------------------------------------------- |

[![NPM Package][crypto-npm-badge]][crypto-npm-link]
[![NPM Downloads][crypto-downloads-badge]][crypto-npm-link]

[![Build Status][crypto-build-badge]][crypto-build-link]
[![Open Issues][crypto-issues-badge]][crypto-issues-link]
[![Code Coverage][crypto-coverage-badge]][crypto-coverage-link]

---

- Web5 Crypto API
- Supported Algorithms \& Key Types
- Extensions
- Getting Started
- Node.js
- Web Browsers
- React Native
- Contributing
- Core Concepts
- Key URIs
- Using a Local KMS
- JSON Web Key (JWK)
- Random Number Generation
- randomBytes()
- randomUuid()
- Customization
- Persistent Local KMS Key Store
- Cryptographic Primitives
- AES-CTR
- AES-GCM
- ConcatKDF
- Ed25519
- PBKDF2
- secp256k1
- SHA-256
- X25519
- XChaCha20
- XChaCha20-Poly1305
- Project Resources

---

The Web5 Crypto API is a core component of the Web5 JS
ecosystem, providing the cryptography and JSON Object Signing and Encryption (JOSE) capabilities
essential for building secure applications and services with Decentralized Identifiers
(DID) and Verifiable Credentials
(VC).

This JavaScript library was designed for modern development runtimes, including Node.js, web
browsers, and React Native. It provides cryptographic functionality for cipher, hash, and signature
algorithms and basic JOSE support for JSON Web Key (JWK). Additionally, it includes the crypto
interfaces and local Key Management System (KMS) implementation that are used by
other libraries in this monorepo.

$3

The following algorithms and key types are currently supported, with plans to expand its offerings
as the library progresses towards a 1.0 release.

| Capability | Details |
| -------------- | ----------------------------------------------- |
| Cipher | AES-CTR, AES-GCM, XChaCha20, XChaCha20-Poly1305 |
| Signature | ECDSA, EdDSA |
| Hash | SHA-256 |
| Key Derivation | ConcatKDF, ECDH, PBKDF2 |
| ECC Curves | Ed25519, secp256k1, X25519 |

$3

Packages that extend the functionality of the @web5/crypto library:

| Extension | Repository |
| ----------------- | ------------------------------------------------------ |
| AWS KMS extension | [TBD54566975/crypto-aws-kms][crypto-aws-kms-repo-link] |

Getting Started

The Web5 Crypto API is distributed as @web5/crypto via [npmjs.com][crypto-npm-link],
[jsdelivr.com][crypto-jsdelivr-link], [unpkg.com][crypto-unpkg-link], and
[github.com][crypto-repo-link].

$3

This library is designed and tested for the _active_ (v20) and _maintenance_
(v18) LTS releases of Node.js

Install the latest version of @web5/crypto using npm or your preferred package manager:

``shell
npm install @web5/crypto
`

Example ESM import:

`js
import { Ed25519 } from "@web5/crypto";
`

Example CJS require:

`js
const { Ed25519 } = require("@web5/crypto");
`

$3

A polyfilled distribution is published to [jsdelivr.com][crypto-jsdelivr-browser] and
[unpkg.com][crypto-unpkg-browser] that can imported in a module


`

> [!IMPORTANT]
> The @web5/crypto library depends on the
> Web Crypto API in web browsers.
> Web Crypto is available in all modern browsers but is accessible only in a
> secure context.
>
> This means you will not be able to use many @web5/crypto features in a browser unless the page
> is served over https:// or wss://. Locally-delivered resources such as those with
> http://127.0.0.1, http://localhost, or http://*.localhost URLs are also considered to have
> been delivered securely.

$3

For React Native, you may need a
polyfill for crypto.getRandomValues.

`js
import "react-native-get-random-values";
`

Contributing

We welcome you to join our open source community. Whether you're new to open source or a seasoned
contributor, there's a place for you here. From coding to documentation, every contribution matters.
Check out our [contribution guide][contributing-link] for ways to get started.

For help, discussion about best practices, or to chat with others building on Web5 join our
[Discord Server][discord-link]:

[![discord-badge]][discord-link]

Remember, contributing is not just about code; it's about building together. Join us in shaping the
future of the Web!

Core Concepts

$3

One of the core design principles for the SDKs in the Web5 ecosystem is the protection of private
key material. Instead of directly handling sensitive key information, our SDKs interact with
cryptographic keys through Key Management Systems (KMS) referenced by a unique identifier called a
Key URI. This approach ensures that private keys remain secure, while still allowing for
versatile cryptographic functionalities.

Each KMS assigns a unique identifier to a key when it is created. This identifier can be used to
form a Uniform Resource Identifier (URI) by adding
a prefix. The following table shows the format of supported Key URIs:

| Prefix | Key URI Format |
| --------- | -------------------------- |
| urn:jwk | urn:jwk: |

All cryptographic keys are represented in JSON Web Key
(JWK) format and the jwk-thumbprint, a
standardized, deterministic, and unique hash of the
key, acts as a fingerprint, enabling consistent key referencing across all Web5 libraries without
exposing private key information.

$3

This library includes a self-contained Key Management System (KMS) implementation that supports
generating keys, hashing, and creating/verifying digital signatures. Cryptographic operations are
performed within the confines of the local environment, without relying on external services. This
KMS is designed to be used by browser-based web apps or when testing backend services that depend on
cloud-based services (e.g., AWS KMS). Extensions that support external KMS services are
listed here.

Start by instantiating a local KMS implementation of the CryptoApi interface:

`ts
import { LocalKeyManager } from "@web5/crypto";

const kms = new LocalKeyManager();
`

An ephemeral, in-memory key store is used by default but any persistent store that implements the
KeyValueStore
interface can also be passed. See the Persistent Key Store customization
for an example.

Generate a random private key:

`ts
const privateKeyUri = await kms.generateKey({ algorithm: "Ed25519" });
console.log(privateKeyUri);
// Output: urn:jwk:8DaTzHZcvQXUVvl8ezQKgGQHza1hiOZlPkdrB55Vt6Q
`

Create an EdDSA signature over arbitrary data using the private key:

`ts
const data = new TextEncoder().encode("Message");
const signature = await kms.sign({
keyUri: privateKeyUri,
data,
});
console.log(signature);
// Output:
// Uint8Array(64) [
// 208, 172, 103, 148, 119, 138, 101, 95, 41, 218, 64,
// 178, 132, 102, 15, 126, 102, 85, 3, 174, 96, 140,
// 203, 58, 186, 72, 85, 64, 15, 250, 235, 12, 97,
// 247, 52, 31, 110, 58, 85, 191, 161, 253, 82, 4,
// 1, 4, 230, 135, 81, 145, 59, 128, 83, 106, 105,
// 135, 32, 124, 96, 0, 25, 41, 218, 75
// ]
`

Get the public key in JWK format:

`ts
const publicKey = await kms.getPublicKey({ keyUri: privateKeyUri });
console.log(publicKey);
// Output:
// {
// kty: "OKP",
// crv: "Ed25519",
// alg: "EdDSA",
// kid: "8DaTzHZcvQXUVvl8ezQKgGQHza1hiOZlPkdrB55Vt6Q",
// x: "6alAHg28tLuqWtaj0YOg7d5ySM4ERwPqQrLoy2pwdZk"
// }
`

Verify the signature using the public key:

`ts
const isValid = await kms.verify({
key: publicKey,
signature,
data,
});
console.log(isValid);
// Output: true
`

Export the private key:

`ts
const privateKey = await kms.exportKey({ keyUri });
console.log(privateKey);
// Output:
// {
// kty: "OKP",
// crv: "Ed25519",
// alg: "EdDSA",
// kid: "8DaTzHZcvQXUVvl8ezQKgGQHza1hiOZlPkdrB55Vt6Q",
// x: "6alAHg28tLuqWtaj0YOg7d5ySM4ERwPqQrLoy2pwdZk",
// d: "0xLuQyXFaWjrqp2o0orhwvwhtYhp2Z7KeRcioIs78CY"
// }
`

Import a private key generated by another library:

`ts
import type { Jwk } from "@web5/crypto";

const privateKey: Jwk = {
kty: "OKP",
crv: "Ed25519",
x: "0thnrEFw6MVSs1XFgd4OD-Yn05XGQv24hvskmGajtKQ",
d: "0xLuQyXFaWjrqp2o0orhwvwhtYhp2Z7KeRcioIs78CY",
};

const keyUri = await kms.importKey({ key: privateKey });
`

Compute the hash digest of arbitrary data:

`ts
const data = new TextEncoder().encode("Message");
const hash = await kms.digest({ algorithm: "SHA-256", data });
console.log(hash);
// Output:
// Uint8Array(32) [
// 8, 187, 94, 93, 110, 170, 193, 4,
// 158, 222, 8, 147, 211, 14, 208, 34,
// 177, 164, 217, 181, 180, 141, 180, 20,
// 135, 31, 81, 201, 203, 53, 40, 61
// ]
`

$3

A JSON Web Key (JWK) is a standardized format for
representing cryptographic keys in a JSON data structure. The JWK format is used by all
Web5 SDKs to promote portability and
interoperability.

Defining a JWK:

`ts
import type { Jwk } from "@web5/crypto";

const publicKey: Jwk = {
kty: "OKP",
crv: "Ed25519",
x: "KsZRg2-gm9MoSrZqN9aSHUv-zYW8ajgyCfKxLGWJ2DI",
};
`

Computing the thumbprint of a JWK outputs a value
that can be used as a unique key identifier (kid) or to securely compare JWKs to determine if they
are equivalent:

`ts
import { computeJwkThumbprint } from "@web5/crypto";

const thumbprint = await computeJwkThumbprint({ jwk: publicKey });
console.log(thumbprint);
// Output: VhWyK5rpk2u_51_KniJxjRhwTUOsL8BLuKJaqpNYuEA
`

The provided type guard functions can be used for type narrowing or to perform runtime verification
of a specific JWK key type:

`ts
isPublicJwk(publicKey); // true
isPrivateJwk(publicKey); // false
isOkpPublicJwk(publicKey); // true
isOkpPrivateJwk(publicKey); // false
isOctPrivateJwk(publicKey); // false
isEcPublicJwk(publicKey); // false
isEcPrivateJwk(publicKey); // false
`

$3

Cryptographically strong random number generation is vital in cryptography. The unpredictability of
these random numbers is crucial for creating secure cryptographic keys, initialization vectors, and
nonces (numbers used once). Their strength lies in their resistance to being guessed or replicated,
making them foundational to maintaining the integrity and confidentiality of cryptographic systems.

The Web5 Crypto API includes two utility functions for random number generation:

#### randomBytes()

The randomBytes() method generates cryptographically strong random values (CSPRNG) of the
specified length. The implementation relies on
crypto.getRandomValues,
which defers to the runtime (browser, Node.js, etc.) for entropy. The pseudo-random number
generator algorithm may vary across runtimes, but is suitable for generating initialization vectors,
nonces and other random values.

> [!IMPORTANT]
> Use a cipher algorithm's generateKey() method to generate encryption keys rather than
> randomBytes(). This ensures that secrets used for encryption are guaranteed to be generated in a
> secure context and
> that the runtime uses the best
> source of entropy
> available.

`typescript
import { CryptoUtils } from "@web5/crypto";

const nonce = CryptoUtils.randomBytes(24);
`

#### randomUuid()

The randomUuid() method generates a UUID (Universally Unique Identifier) using a cryptographically
strong random number generator (CSPRNG) following the version 4 format, as specified in
RFC 4122.

UUIDs are of a fixed size (128 bits), can guarantee uniqueness across space and time, and can be
generated without a centralized authority to administer them. Since UUIDs are unique and persistent,
they make excellent Uniform Resource Names (URN).
The following is an example of the string representation of a UUID as a URN:
urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6.

> [!NOTE]
> This function is available only in secure contexts (HTTPS and localhost).

`typescript
import { CryptoUtils } from "@web5/crypto";

const uuid = CryptoUtils.randomUuid();
`

Customization

$3

By default, LocalKeyManager uses an in-memory key store to simplify prototyping and testing.
To persist keys that are generated or imported, an implementation of the
KeyValueStore
interface can be passed.

For example, to use the LevelDB-backed store from @web5/common:

`ts
import type { KeyIdentifier, Jwk } from "@web5/crypto";
import { Level } from "level";
import { LevelStore } from "@web5/common";

const db = new Level("db_location", {
valueEncoding: "json",
});
const keyStore = new LevelStore({ db });
const kms = new LocalKeyManager({ keyStore });
`

Cryptographic Primitives

This library encourages using its capabilities through concrete implementations of the CryptoApi
interface (e.g., LocalKeyManager or
[AwsKeyManager][crypto-aws-kms-repo-link]). These implementations provides high-level,
user-friendly access to a range of cryptographic functions. However, for developers requiring
lower-level control or specific customizations, the library also exposes its cryptographic
primitives directly. These primitives include a variety of cipher, hash, signature, key derivation,
and key conversion algorithms for advanced use cases.

> [!WARNING]
> While @web5/crypto offers low-level cryptographic primitives, it's crucial to acknowledge the
> complexity and potential risks associated with their use. Secure key management and security
> system design are highly specialized fields, often requiring expert knowledge. Even with correct
> usage of cryptographic functions, designing a secure system poses significant challenges.
>
> It's important to approach the creation of secure systems with caution, seeking expert review and
> continual learning to ensure effectiveness and security. Crypto 101 is
> an introductory course on cryptography to _begin_ your learning journey, freely available for
> developers of all skill levels.

#### AES-CTR

`ts
import { AesCtr, CryptoUtils } from "@web5/crypto";

// Key Generation
const length = 256; // Length of the key in bits (e.g., 128, 192, 256)
const privateKey = await AesCtr.generateKey({ length });

// Encryption
const data = new TextEncoder().encode("Message");
const counter = CryptoUtils.randomBytes(16); // Initial value of the counter block
const encryptedData = await AesCtr.encrypt({
data,
counter,
key: privateKey,
length: 64, // Length of the counter in bits
});

// Decryption
const decryptedData = await AesCtr.decrypt({
data: encryptedData,
counter,
key: privateKey,
length: 64, // Length of the counter in bits
});
`

#### AES-GCM

`ts
import { AesGcm, CryptoUtils } from "@web5/crypto";

// Key Generation
const length = 256; // Length of the key in bits (e.g., 128, 192, 256)
const privateKey = await AesGcm.generateKey({ length });

// Encryption
const data = new TextEncoder().encode("Message");
const iv = CryptoUtils.randomBytes(12); // Initialization vector
const encryptedData = await AesGcm.encrypt({
data,
iv,
key: privateKey,
});

// Decryption
const decryptedData = await AesGcm.decrypt({
data: encryptedData,
iv,
key: privateKey,
});
`

#### ConcatKDF

`ts
import { ConcatKdf, CryptoUtils } from "@web5/crypto";

// Key Derivation
const derivedKeyingMaterial = await ConcatKdf.deriveKey({
sharedSecret: CryptoUtils.randomBytes(32),
keyDataLen: 128,
otherInfo: {
algorithmId: "A128GCM",
partyUInfo: "Alice",
partyVInfo: "Bob",
suppPubInfo: 128,
},
});
`

#### Ed25519

`ts
import { Ed25519 } from "@web5/crypto";

// Key Generation
const privateKey = await Ed25519.generateKey();

// Public Key Derivation
const publicKey = await Ed25519.computePublicKey({ key: privateKey });

// EdDSA Signing
const signature = await Ed25519.sign({
key: privateKey,
data: new TextEncoder().encode("Message"),
});

// EdDSA Signature Verification
const isValid = await Ed25519.verify({
key: publicKey,
signature: signature,
data: new TextEncoder().encode("Message"),
});
`

#### PBKDF2

`ts
import { Pbkdf2, CryptoUtils } from "@web5/crypto";

// Key Derivation
const derivedKey = await Pbkdf2.deriveKey({
hash: "SHA-256", // Hash function to use ('SHA-256', 'SHA-384', 'SHA-512')
password: new TextEncoder().encode("password"), // Password as a Uint8Array
salt: CryptoUtils.randomBytes(16), // Salt value
iterations: 1000, // Number of iterations
length: 256, // Length of the derived key in bits
});
`

#### secp256k1

`ts
import { Secp256k1 } from "@web5/crypto";

// Key Generation
const privateKey = await Secp256k1.generateKey();

// Public Key Derivation
const publicKey = await Secp256k1.computePublicKey({ key: privateKey });

// ECDH Shared Secret Computation
const sharedSecret = await Secp256k1.sharedSecret({
privateKeyA: privateKey,
publicKeyB: anotherPublicKey,
});

// ECDSA Signing
const signature = await Secp256k1.sign({
key: privateKey,
data: new TextEncoder().encode("Message"),
});

// ECDSA Signature Verification
const isValid = await Secp256k1.verify({
key: publicKey,
signature: signature,
data: new TextEncoder().encode("Message"),
});
`

#### SHA-256

`ts
import { Sha256 } from "@web5/crypto";

// Hashing
const data = new TextEncoder().encode("Message");
const hash = await Sha256.digest({ data });
`

#### X25519

`ts
import { X25519 } from "@web5/crypto";

// Key Generation
const privateKey = await X25519.generateKey();

// Public Key Derivation
const publicKey = await X25519.computePublicKey({ key: privateKey });

// ECDH Shared Secret Computation
const sharedSecret = await X25519.sharedSecret({
privateKeyA: privateKey,
publicKeyB: anotherPublicKey,
});
`

#### XChaCha20

`ts
import { XChaCha20, CryptoUtils } from "@web5/crypto";

// Key Generation
const privateKey = await XChaCha20.generateKey();

// Encryption
const data = new TextEncoder().encode("Message");
const nonce = CryptoUtils.randomBytes(24);
const encryptedData = await XChaCha20.encrypt({
data,
nonce,
key: privateKey,
});

// Decryption
const decryptedData = await XChaCha20.decrypt({
data: encryptedData,
nonce,
key: privateKey,
});
`

#### XChaCha20-Poly1305

`ts
import { XChaCha20Poly1305, CryptoUtils } from "@web5/crypto";

// Key Generation
const privateKey = await XChaCha20Poly1305.generateKey();

// Encryption
const data = new TextEncoder().encode("Message");
const nonce = CryptoUtils.randomBytes(24);
const additionalData = new TextEncoder().encode("Associated data");
const { ciphertext, tag } = await XChaCha20Poly1305.encrypt({
data,
nonce,
additionalData,
key: privateKey,
});

// Decryption
const decryptedData = await XChaCha20Poly1305.decrypt({
data: ciphertext,
nonce,
tag,
additionalData,
key: privateKey,
});
``

Project Resources

| Resource | Description |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| [CODEOWNERS][codeowners-link] | Outlines the project lead(s) |
| [CODE OF CONDUCT][code-of-conduct-link] | Expected behavior for project contributors, promoting a welcoming environment |
| [CONTRIBUTING][contributing-link] | Developer guide to build, test, run, access CI, chat, discuss, file issues |
| [GOVERNANCE][governance-link] | Project governance |
| [LICENSE][license-link] | Apache License, Version 2.0 |

[crypto-npm-badge]: https://img.shields.io/npm/v/@web5/crypto.svg?style=flat&color=blue&santize=true
[crypto-npm-link]: https://www.npmjs.com/package/@web5/crypto
[crypto-downloads-badge]: https://img.shields.io/npm/dt/@web5/crypto?&color=blue
[crypto-build-badge]: https://img.shields.io/github/actions/workflow/status/TBD54566975/web5-js/tests-ci.yml?branch=main&label=build
[crypto-build-link]: https://github.com/TBD54566975/web5-js/actions/workflows/tests-ci.yml
[crypto-coverage-badge]: https://img.shields.io/codecov/c/gh/TBD54566975/web5-js/main?style=flat&token=YI87CKF1LI
[crypto-coverage-link]: https://app.codecov.io/github/TBD54566975/web5-js/tree/main/packages%2Fcrypto
[crypto-issues-badge]: https://img.shields.io/github/issues/TBD54566975/web5-js/package:%20crypto?label=issues
[crypto-issues-link]: https://github.com/TBD54566975/web5-js/issues?q=is%3Aopen+is%3Aissue+label%3A"package%3A+crypto"
[crypto-aws-kms-repo-link]: https://github.com/TBD54566975/web5-js/tree/main/packages/crypto-aws-kms
[crypto-repo-link]: https://github.com/TBD54566975/web5-js/tree/main/packages/crypto
[crypto-jsdelivr-link]: https://www.jsdelivr.com/package/npm/@web5/crypto
[crypto-jsdelivr-browser]: https://cdn.jsdelivr.net/npm/@web5/crypto/dist/browser.mjs
[crypto-unpkg-link]: https://unpkg.com/@web5/crypto
[crypto-unpkg-browser]: https://unpkg.com/@web5/crypto/dist/browser.mjs
[codeowners-link]: https://github.com/TBD54566975/web5-js/blob/main/CODEOWNERS
[code-of-conduct-link]: https://github.com/TBD54566975/web5-js/blob/main/CODE_OF_CONDUCT.md
[contributing-link]: https://github.com/TBD54566975/web5-js/blob/main/CONTRIBUTING.md
[governance-link]: https://github.com/TBD54566975/web5-js/blob/main/GOVERNANCE.md
[license-link]: https://github.com/TBD54566975/web5-js/blob/main/LICENSE
[discord-badge]: https://img.shields.io/discord/937858703112155166?color=5865F2&logo=discord&logoColor=white
[discord-link]: https://discord.com/channels/937858703112155166/969272658501976117