---
title: "libsodium"
description: "Use libsodium for MainSDK crypto - an in-process library planned as a driver for signing, sealing and tokens, with no account."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/libsodium"
updated: "2026-10-28"
---

# libsodium

> Use libsodium for MainSDK crypto - an in-process library planned as a driver for signing, sealing and tokens, with no account.

Canonical: https://mainsdk.dev/docs/integrations/libsodium · Updated: 2026-10-28

libsodium is an open-source cryptography library that runs inside your app's process, and the driver in the [`crypto`](https://mainsdk.dev/docs/interfaces/crypto) catalog example. It is planned as a driver behind `crypto.token()`, signing and sealing, with no network call and no account; today the built-in WebCrypto driver does that work. Pick it as the starting point; move signing or encryption keys to Vault Transit or a cloud key service when you need keys held outside the app.

> **Note:** `crypto` has no spec yet. The calls and options on this page are provisional, taken from the catalog and the product requirements, and may change when the spec lands.

## Interfaces it serves

### Cryptography (`crypto`)

- Status: Building for 0.3 · ships as a beta API
- Driver: `libsodium` (libsodium). planned; the builtin driver covers every call today
- Docs: https://mainsdk.dev/docs/interfaces/crypto.md

```yaml
crypto:
  driver: libsodium
```

Swap to another provider: `builtin`, `cloud-kms`, `vault-transit`.

## Before you start

Nothing to sign up for. libsodium is a library, not a service. `crypto.seal()` and `crypto.sign()` take the keys you pass in; keep them in your secrets driver, never in code.

## Configure

```yaml title="main.yaml"
crypto:
  driver: libsodium
```

## Use it

```ts title="app/sign-up/actions.ts"
"use server";
import { crypto } from "mainsdk";

export async function prepareAccount() {
  const verifyToken = crypto.token();
  const stored = await crypto.hashHex(verifyToken);   // keep the hash, send the token
  return { verifyToken, stored };
}
```

## Local development and testing

The same driver runs in development, tests and production, since it needs no provider. `createTestApp()` from `@mainsdk/testing` runs `crypto` alongside every other interface on its fake.

## What MainSDK adds on top

- Modern algorithms only; there is no option to pick MD5, SHA-1 or DES, and `mainsdk check` carries `MAIN-CRYPTO-0002`.
- Keys never in code.

See [Cryptography](https://mainsdk.dev/docs/interfaces/crypto).

## Limits and notes

- Keys used by this driver live with your app, not in a key service. For records with per-user erasure, use [`keys`](https://mainsdk.dev/docs/interfaces/keys) with a KMS.
- Customer-managed keys arrive in phase 3 (spec `hsm-keys`), post-quantum signatures in phase 5.

## Swap to or from it

```yaml title="main.yaml"
crypto:
  driver: vault-transit   # was libsodium
```

> **Warning:** Data encrypted or signed with keys held by one driver still needs those keys to decrypt or verify. Plan a key migration before you switch. Password hashes are unaffected by where keys live.

## FAQ

**Is Argon2id the only password hash?** Yes. Only modern algorithms are offered, and passwords use Argon2id.

**When should I move off libsodium?** When your policy says signing or encryption keys must live in a key service, outside the app. Switch `crypto.driver` to `vault-transit` or `cloud-kms`; your calls stay the same.

## Next

- [Cryptography](https://mainsdk.dev/docs/interfaces/crypto) and [Encryption keys](https://mainsdk.dev/docs/interfaces/keys)
- [HashiCorp Vault](https://mainsdk.dev/docs/integrations/hashicorp-vault)