Cryptography

crypto gives you everyday building blocks: seal and open, sign and verify, hash, HMAC, derive a key and make tokens, with modern algorithms only, on WebCrypto. For records with per-user erasure, use keys.

crypto:
  fips: false

import { crypto } from "mainsdk";

const resetToken = crypto.token();                 // 32 random bytes, URL-safe
const stored = await crypto.hashHex(resetToken);   // keep the hash, never the token

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { crypto } from "mainsdk";

describe("crypto", () => {
  it("opens only with the same key and aad", async () => {
    const key = crypto.generateKey();
    const box = await crypto.seal(key, "hello", { aad: "note:1" });
    await assert.rejects(crypto.open(key, box, { aad: "note:2" }), { code: "MAIN-CRYPTO-0003" });
    assert.equal(new TextDecoder().decode(await crypto.open(key, box, { aad: "note:1" })), "hello");
  });
});

crypto:
  driver: builtin

Quick start

There is nothing to declare in main.yaml. Import crypto and call it.

import { crypto } from "mainsdk";

const token = crypto.token();                  // 32 random bytes, 43 URL-safe characters
const stored = await crypto.hashHex(token);    // keep this, never the token

use mainsdk::prelude::*;
let app = App::test();
let pair = app.crypto().keypair().await?;
let sig = app.crypto().sign(&pair.seed, b"hello").await?;
assert!(app.crypto().verify(&pair.public_key, b"hello", &sig).await?);

Configuration

None today. crypto has no main.yaml section, and the algorithms are not a free choice: only modern ones are offered. A crypto.driver for a key service such as Vault Transit or a cloud KMS is planned. Until then use keys, which has those drivers.

What you get

The calls are free, run offline on WebCrypto on Node and edge runtimes, and need no dependency. Only modern algorithms are offered, so a weak one cannot be picked by accident. You hold the keys and pass them in; nothing is stored or logged. Reach for it for a single operation such as a token, a hash or a signature. The spec is keys (AC8 to AC13).

Examples

Password reset token

import { crypto } from "mainsdk";

export async function startReset() {
  const token = crypto.token();
  const stored = await crypto.hashHex(token);
  // save `stored` with an expiry, then send `token` to the person
  return { token, stored };
}

export async function checkReset(token: string, stored: string) {
  return crypto.equal(await crypto.hashHex(token), stored);   // constant time
}

Store only the hash of the token, with an expiry, never the token itself. crypto.token(bytes) takes 16 or more.

Seal and open data

You hold the key. For keys held in a KMS, with per-user erasure, use keys.

import { crypto } from "mainsdk";

const key = crypto.generateKey();   // 32 bytes; keep it in your secrets driver
const box = await crypto.seal(key, "hello", { aad: "note:1" });
const plain = await crypto.open(key, box, { aad: "note:1" });   // Uint8Array

aad binds the box to a context: opening it with another aad, another key or changed bytes fails with MAIN-CRYPTO-0003. A key that is not 32 bytes fails with MAIN-CRYPTO-0001.

Sign and verify

import { crypto } from "mainsdk";

const pair = await crypto.generateSigningKeyPair();   // ed25519: PKCS#8 private key, 32-byte public key
const signature = await crypto.sign(pair.privateKey, "payload");   // 64 bytes
const ok = await crypto.verify(pair.publicKey, { data: "payload", signature });   // true

verify returns false for a changed message or another key. To keep the private key in a key service, so it never reaches your code, see keys.sign() (planned).

Hash, HMAC and derive a key

import { crypto } from "mainsdk";

const digest = await crypto.hashHex("abc");               // SHA-256; "sha384" and "sha512" are allowed
const secret = crypto.token();   // in an app, read this from your secrets driver
const tag = await crypto.hmac(secret, "body");
const good = await crypto.verifyHmac(secret, "body", tag);   // false on a mismatch, never throws
const subkey = await crypto.deriveKey("a-long-enough-secret", "exports");   // HKDF-SHA-256, 32 bytes

An HMAC key needs 16 bytes or more. MD5, SHA-1 and DES are refused with MAIN-CRYPTO-0002; there is no option to pick them.

The other helpers are crypto.randomBytes(n), crypto.b64u(), crypto.fromB64u() and crypto.toHex().

Use the helpers without the app

cryptoApi is an object, not a function (the catalog lists it as cryptoApi(...)). It is what crypto forwards to: every helper above under one name. Import it when you need these helpers where no app is running, such as a script or a library.

import { cryptoApi } from "mainsdk";

const digest = await cryptoApi.hashHex("abc");

Planned

• Password hashing with Argon2id. Not in the code yet. Do not use crypto.hash() for passwords: SHA-2 is fast by design.
• Field encryption with a data label. Not in the code yet. Until it lands, encrypt a value with keys.encrypt(), which wraps a data key per value.
• Drivers (libsodium, vault-transit, cloud-kms) behind the same calls.
• Customer-held keys with crypto.keys.customer() (phase 3, spec hsm-keys); post-quantum signatures and hybrid key exchange (phase 5, spec post-quantum).

Errors and checks

mainsdk check carries the same rule in source as MAIN-CRYPTO-0002; the rules belong to Main 27.

Swapping drivers

crypto has one driver today, the built-in WebCrypto one, so there is nothing to swap. Drivers for libsodium, vault-transit and cloud-kms are planned behind the same calls. Until then, use keys when the key must live in a key service. See Swap a driver.

Testing

crypto is pure and offline, so tests call it directly.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { crypto } from "mainsdk";

describe("crypto", () => {
  it("opens only with the same key and aad", async () => {
    const key = crypto.generateKey();
    const box = await crypto.seal(key, "hello", { aad: "note:1" });
    await assert.rejects(crypto.open(key, box, { aad: "note:2" }), { code: "MAIN-CRYPTO-0003" });
    assert.equal(new TextDecoder().decode(await crypto.open(key, box, { aad: "note:1" })), "hello");
  });
});

Security and privacy

• Modern algorithms only: AES-256-GCM, ed25519, SHA-2 and HKDF-SHA-256.
• Every seal uses a fresh random nonce. Comparison with crypto.equal() takes time that depends only on length.
• Keys are bytes you pass in; nothing is logged or stored by crypto.

FAQ

When do I use crypto and when keys? keys encrypts records with their own data keys, wrapped by a KMS, with per-user keys for erasure. crypto is for single operations such as a hash, an HMAC or a signature, with keys you hold.

Can I choose SHA-1 or bcrypt? No. Only modern algorithms are offered.

Next

• Encryption keys
• Secrets
• Main 27