Key Management

json‑seal uses RSA‑PSS keys for signing and verifying signed envelopes. The private key is used to create signatures. The public key is embedded directly in each envelope, making verification portable and self‑contained.

Generating keys

Keys are created using the WebCrypto API. json‑seal provides a helper that returns a ready‑to‑use RSA‑PSS key pair.

import { generateKeyPair } from "json-seal";

const { publicKey, privateKey } = await generateKeyPair();

Exporting keys

Keys can be exported for storage or transport. Private keys should be protected; public keys may be shared freely.

const pub = await crypto.subtle.exportKey("spki", publicKey);
const priv = await crypto.subtle.exportKey("pkcs8", privateKey);

Importing keys

Exported keys can be re‑imported into WebCrypto when needed.

const publicKey = await crypto.subtle.importKey(
  "spki",
  pub,
  { name: "RSA-PSS", hash: "SHA-256" },
  true,
  ["verify"]
);

Storing private keys

Private keys must be stored securely. Recommended options include:

• browser: IndexedDB with appropriate access controls
• Node: filesystem with restricted permissions
• native apps: secure storage APIs
• servers: environment‑specific secret management

json‑seal does not prescribe a storage strategy. It leaves key management to the host environment.

Key rotation

Each signed envelope embeds its own public key. This means:

• old envelopes remain verifiable indefinitely
• new envelopes can be signed with new keys at any time
• rotation does not break existing data

Rotation is as simple as generating a new key pair and signing with it.

Trust model

Verification trusts the embedded public key. If you need stronger guarantees—such as identity binding, certificate chains, or external trust anchors—those must be layered on top of json‑seal.

What json‑seal does not do

• does not store keys
• does not manage trust relationships
• does not provide encryption or confidentiality
• does not provide revocation

json‑seal focuses on one thing: producing and verifying signed, tamper‑evident JSON envelopes. Key management remains under your control.

← Back