crypto-browser

Browser-compatible cryptography utilities for Sigstore and TUF verification.

Used by tuf-browser and sigstore-browser.

[!CAUTION] This library has not received an independent security audit. Maintenance is performed by volunteers, and the project is not officially supported or endorsed by the Freedom of the Press Foundation.

Features

ASN.1 Parsing & Encoding

• ASN1Obj: Parse and encode DER-encoded ASN.1 structures
• ASN1Tag: Handle ASN.1 tags and type checking
• Length encoding/decoding: DER length format support
• Type parsers: Extract integers, OIDs, dates, bit strings, booleans from ASN.1

Encoding Utilities

• Base64: Encode/decode with standard and URL-safe variants
• Hex: Encode/decode hexadecimal strings
• PEM: Convert between PEM and DER formats
• UTF-8: String to Uint8Array conversion
• Bytes: concatBytes, and constant-time comparison with uint8ArrayEqual
• Digests: sha256(bytes) and digest(algorithm, bytes) returning bytes
• Merkle trees (RFC 6962): hashLeaf, hashChildren, rootHash, verifyInclusionProof, verifyConsistencyProof, tested against the transparency-dev vectors

Cryptographic Operations

• Key import: Support for ECDSA (P-256/P-384/P-521), Ed25519, and RSA keys
• Signature verification: Verify signatures using Web Crypto API
  • ECDSA with SHA-256/384/512
  • Ed25519
  • RSA-PSS and RSASSA-PKCS1-v1_5
• Digest verification: ECDSA signature verification over pre-computed digests, in the opt-in noble entry
• PKCS#1 to SPKI conversion: Convert RSA keys for Web Crypto compatibility

Additional Utilities

• ByteStream: Efficient byte buffer with auto-growing allocation
• Canonical JSON: OLPC canonical JSON (TUF) and RFC 8785 JCS (Rekor, WEBCAT), both tested against official vectors

Installation

npm install @freedomofpress/crypto-browser

Usage

Import a public key and verify a signature

import { importKey, verifySignature } from '@freedomofpress/crypto-browser';

const publicKey = await importKey('ECDSA', 'P-256', pemKey);
const isValid = await verifySignature(publicKey, message, signature, 'sha256');

Parse ASN.1 structures

import { ASN1Obj } from '@freedomofpress/crypto-browser';

const asn1 = ASN1Obj.parseBuffer(derBytes);
const oid = asn1.subs[0].toOID();
const integer = asn1.subs[1].toInteger();

Encode/decode utilities

import {
  base64ToUint8Array,
  uint8ArrayToHex,
  toDER,
  fromDER,
} from '@freedomofpress/crypto-browser';

const bytes = base64ToUint8Array('SGVsbG8=');
const hex = uint8ArrayToHex(bytes);
const der = toDER(pemString);
const pem = fromDER(derBytes, 'PUBLIC KEY');

Dependencies

• @noble/curves: only reached through @freedomofpress/crypto-browser/noble, so bundles that never import that entry do not carry it

Ed25519 fallback and digest verification

getSubtle() returns the platform's native SubtleCrypto. Platforms without Ed25519 in WebCrypto can route every helper through @noble/curves for Ed25519 keys only:

import { installEd25519Fallback } from "@freedomofpress/crypto-browser/noble";

await installEd25519Fallback();

The same entry exports verifySignatureOverDigest(key, digest, signature) for ECDSA signatures when only the digest of the signed data is available.

Structure

src/
  asn1/           # ASN.1 parsing and encoding
  encoding.ts     # Base64, hex, UTF-8 encoding
  pem.ts          # PEM format conversion
  stream.ts       # ByteStream utility
  crypto.ts       # Cryptographic operations
  canonicalize.ts # Canonical JSON

Development

# Install dependencies
npm install

# Build the project
npm run build

License

Apache-2.0 - see LICENSE file for details.

Acknowledgments

This package provides browser-compatible versions of cryptographic utilities from the Sigstore and TUF ecosystems. All code is licensed under Apache-2.0.

Primary Sources:

• sigstore-js - ASN.1 parsing, PEM encoding, and stream utilities
• tuf-js and sigstore-js - Canonical JSON implementations

All files maintain their original copyright headers.