micro509

Appearance

micro509/keys ​

Canonical key generation and import/export domain surface. Owns the stable micro509/keys entrypoint.

DecryptRsaOaepErrorCode ​

Machine-readable failure reason for decryptRsaOaep.

'invalid_key' when the key is not an RSA-OAEP private key with decrypt usage; 'decryption_failed' for every ciphertext-level failure (wrong key, wrong label, tampered or truncated ciphertext) — OAEP deliberately does not reveal which.

ts
type DecryptRsaOaepErrorCode = invalid_key | decryption_failed

DecryptRsaOaepFailure ​

Structured failure payload for decryptRsaOaep.

ts
interface DecryptRsaOaepFailure extends Micro509Error<DecryptRsaOaepErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

DecryptRsaOaepResult ​

Success-or-failure result returned by decryptRsaOaep.

ts
type DecryptRsaOaepResult = {
  readonly ok: true;
  readonly value: Uint8Array
} | ErrorResult<DecryptRsaOaepErrorCode, Record<never, never>, DecryptRsaOaepFailure>

EcKeyAlgorithmInput ​

ECDSA variant of KeyAlgorithmInput.

ts
interface EcKeyAlgorithmInput {
	readonly kind: ecdsa;
	readonly curve?: EcNamedCurve;
}

Properties

  • readonly kind: ecdsa — Discriminant selecting ECDSA key generation.
  • readonly curve?: EcNamedCurve — NIST curve. Defaults to 'P-256'.

EcNamedCurve ​

NIST elliptic curve for ECDSA keys.

ts
type EcNamedCurve = P-256 | P-384 | P-521

Ed25519KeyAlgorithmInput ​

Ed25519 variant of KeyAlgorithmInput.

ts
interface Ed25519KeyAlgorithmInput {
	readonly kind: ed25519;
}

Properties

  • readonly kind: ed25519 — Discriminant selecting Ed25519 key generation.

EncryptedPkcs8Options ​

PBES2 encryption options for the encrypted PKCS#8 export/import functions.

ts
interface EncryptedPkcs8Options {
	readonly password: string;
	readonly iterations?: number;
	readonly salt?: Uint8Array;
	readonly iv?: Uint8Array;
	readonly cipher?: AES-128-CBC | AES-192-CBC | AES-256-CBC;
	readonly prf?: HMAC-SHA-1 | HMAC-SHA-256;
}

Properties

  • readonly password: string — Password fed to PBKDF2 for key derivation.
  • readonly iterations?: number — PBKDF2 iteration count. Default: 100_000.
  • readonly salt?: Uint8Array — PBKDF2 salt. Default: 16 cryptographically random bytes.
  • readonly iv?: Uint8Array — AES-CBC initialization vector. Default: 16 cryptographically random bytes.
  • readonly cipher?: AES-128-CBC | AES-192-CBC | AES-256-CBC — AES-CBC cipher. Default: 'AES-256-CBC'.
  • readonly prf?: HMAC-SHA-1 | HMAC-SHA-256 — PBKDF2 pseudo-random function. Default: 'HMAC-SHA-256'.

EncryptRsaOaepErrorCode ​

Machine-readable failure reason for encryptRsaOaep.

'invalid_key' when the key is not an RSA-OAEP public key with encrypt usage; 'message_too_long' when the plaintext exceeds the OAEP capacity of the key (modulus bytes − 2 × hash bytes − 2).

ts
type EncryptRsaOaepErrorCode = invalid_key | message_too_long

EncryptRsaOaepFailure ​

Structured failure payload for encryptRsaOaep.

ts
interface EncryptRsaOaepFailure extends Micro509Error<EncryptRsaOaepErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

EncryptRsaOaepResult ​

Success-or-failure result returned by encryptRsaOaep.

ts
type EncryptRsaOaepResult = {
  readonly ok: true;
  readonly value: Uint8Array
} | ErrorResult<EncryptRsaOaepErrorCode, Record<never, never>, EncryptRsaOaepFailure>

ImportEcKeyInput ​

ECDSA variant of PublicKeyImportInput / PrivateKeyImportInput.

ts
interface ImportEcKeyInput {
	readonly kind: ecdsa;
	readonly curve: EcNamedCurve;
}

Properties

  • readonly kind: ecdsa — Discriminant selecting ECDSA import.
  • readonly curve: EcNamedCurve — NIST curve the key belongs to. Required for EC import.

ImportEd25519KeyInput ​

Ed25519 variant of PublicKeyImportInput / PrivateKeyImportInput.

ts
interface ImportEd25519KeyInput {
	readonly kind: ed25519;
}

Properties

  • readonly kind: ed25519 — Discriminant selecting Ed25519 import.

ImportEncryptedKeyErrorCode ​

Machine-readable failure reason for the importEncrypted* key functions.

Distinguishes a wrong decryption password ('invalid_password') from structurally invalid input or algorithm mismatches ('malformed').

ts
type ImportEncryptedKeyErrorCode = malformed | invalid_password

ImportEncryptedKeyFailure ​

Structured failure payload for encrypted key import.

ts
interface ImportEncryptedKeyFailure extends Micro509Error<ImportEncryptedKeyErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

ImportEncryptedKeyResult ​

Success-or-failure result returned by the public importEncrypted* key functions.

On failure, code is 'invalid_password' when decryption failed (wrong password or corrupted ciphertext) and 'malformed' for everything else.

ts
type ImportEncryptedKeyResult<T> = {
  readonly ok: true;
  readonly value: T
} | ErrorResult<ImportEncryptedKeyErrorCode, Record<never, never>, ImportEncryptedKeyFailure>

ImportKeyErrorCode ​

Machine-readable failure reason for the import* key functions.

ts
type ImportKeyErrorCode = malformed

ImportKeyFailure ​

Structured failure payload for key import.

ts
interface ImportKeyFailure extends Micro509Error<ImportKeyErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

ImportKeyResult ​

Success-or-failure result returned by the public import* key functions.

On failure, code is always 'malformed': structurally invalid input, algorithm mismatches, and wrong-password decryption failures all surface the same way (see the throwing *OrThrow variants for raw error messages).

ts
type ImportKeyResult<T> = {
  readonly ok: true;
  readonly value: T
} | ErrorResult<ImportKeyErrorCode, Record<never, never>, ImportKeyFailure>

ImportRsaKeyInput ​

RSA variant of PublicKeyImportInput / PrivateKeyImportInput.

ts
interface ImportRsaKeyInput {
	readonly kind: rsa;
	readonly hash?: RsaHash;
	readonly scheme?: RsaScheme;
}

Properties

  • readonly kind: rsa — Discriminant selecting RSA import.
  • readonly hash?: RsaHash — Hash algorithm. Defaults to 'SHA-256'.
  • readonly scheme?: RsaScheme — Padding scheme. Defaults to 'pkcs1-v1_5'. Pass 'oaep' to import an RSA-OAEP encryption key (encrypt/decrypt usage instead of verify/sign).

KeyAlgorithmInput ​

Input for generateKeyPair. Selects algorithm family and parameters.

ts
type KeyAlgorithmInput = RsaKeyAlgorithmInput | EcKeyAlgorithmInput | Ed25519KeyAlgorithmInput

KeyPairMaterial ​

Key pair with convenience export helpers. Returned by generateKeyPair.

ts
interface KeyPairMaterial {
	readonly publicKey: CryptoKey;
	readonly privateKey: CryptoKey;
	exportSpkiDer(): Promise<Uint8Array>;
	exportSpkiPem(): Promise<string>;
	exportPkcs8Der(): Promise<Uint8Array>;
	exportPkcs8Pem(): Promise<string>;
	exportPublicJwk(): Promise<JsonWebKey>;
	exportPrivateJwk(): Promise<JsonWebKey>;
}

Properties

  • readonly publicKey: CryptoKey — The WebCrypto public key (extractable, verify usage; encrypt for RSA-OAEP).
  • readonly privateKey: CryptoKey — The WebCrypto private key (extractable, sign usage; decrypt for RSA-OAEP).

LegacyPemEncryptionOptions ​

Options for OpenSSL-style Proc-Type: 4,ENCRYPTED PEM encryption (PKCS#1/SEC1).

ts
interface LegacyPemEncryptionOptions {
	readonly password: string;
	readonly iv?: Uint8Array;
	readonly cipher?: AES-128-CBC | AES-192-CBC | AES-256-CBC;
}

Properties

  • readonly password: string — Passphrase used to derive the encryption key.
  • readonly iv?: Uint8Array — 16-byte initialization vector. Random when omitted.
  • readonly cipher?: AES-128-CBC | AES-192-CBC | AES-256-CBC — AES-CBC cipher. Defaults to 'AES-256-CBC'.

PrivateKeyImportInput ​

Algorithm descriptor for private key import functions. Same shape as PublicKeyImportInput.

ts
type PrivateKeyImportInput = PublicKeyImportInput

PublicKeyImportInput ​

Algorithm descriptor for public key import functions.

ts
type PublicKeyImportInput = ImportRsaKeyInput | ImportEcKeyInput | ImportEd25519KeyInput

RsaHash ​

Hash algorithm paired with an RSA key.

ts
type RsaHash = SHA-256 | SHA-384 | SHA-512

RsaKeyAlgorithmInput ​

RSA variant of KeyAlgorithmInput.

ts
interface RsaKeyAlgorithmInput {
	readonly kind: rsa;
	readonly modulusLength?: 2048 | 3072 | 4096;
	readonly hash?: RsaHash;
	readonly scheme?: RsaScheme;
}

Properties

  • readonly kind: rsa — Discriminant selecting RSA key generation.
  • readonly modulusLength?: 2048 | 3072 | 4096 — RSA modulus size in bits. Defaults to 2048.
  • readonly hash?: RsaHash — Hash algorithm for the key. Defaults to 'SHA-256'.
  • readonly scheme?: RsaScheme — Padding scheme. Defaults to 'pkcs1-v1_5'. Pass 'oaep' to generate an RSA-OAEP encryption pair (encrypt/decrypt usages instead of sign/verify).

RsaOaepOptions ​

Options shared by encryptRsaOaep and decryptRsaOaep.

ts
interface RsaOaepOptions {
	readonly label?: Uint8Array;
}

Properties

  • readonly label?: Uint8Array — Optional OAEP label bound to the ciphertext. Not encrypted, but decryption fails unless the exact same label is presented. Default: empty.

RsaScheme ​

RSA padding scheme: a signature scheme, or 'oaep' for RSA-OAEP encryption keys (usable with encryptRsaOaep / decryptRsaOaep).

ts
type RsaScheme = RsaSignatureScheme | oaep

RsaSignatureScheme ​

RSA signature padding scheme.

ts
type RsaSignatureScheme = pkcs1-v1_5 | pss

decryptRsaOaep ​

Decrypt an RSA-OAEP ciphertext with the matching private key.

ts
function decryptRsaOaep(
	privateKey: CryptoKey,
	ciphertext: Uint8Array,
	_: unknown,
): Promise<DecryptRsaOaepResult>

Parameters

  • privateKey: CryptoKey
  • ciphertext: Uint8Array
  • _: unknown

See also

  • decryptRsaOaepOrThrow for the throwing variant

Examples

ts
const decrypted = await decryptRsaOaep(keys.privateKey, ciphertext);
if (!decrypted.ok) {
	// decrypted.code: 'invalid_key' | 'decryption_failed'
	throw new Error(decrypted.message);
}
const plaintext = decrypted.value;

decryptRsaOaepOrThrow ​

Decrypt an RSA-OAEP ciphertext with the matching private key.

The key must have been generated or imported with { kind: 'rsa', scheme: 'oaep' }, and options.label must repeat the label used at encryption time (if any).

ts
function decryptRsaOaepOrThrow(
	privateKey: CryptoKey,
	ciphertext: Uint8Array,
	_: unknown,
): Promise<Uint8Array>

Parameters

  • privateKey: CryptoKey — RSA-OAEP private CryptoKey with decrypt usage
  • ciphertext: Uint8Array — Ciphertext produced by encryptRsaOaep (or any RSA-OAEP encryptor)
  • _: unknown

Throws

  • Error — If the key is not an RSA-OAEP private decryption key, or decryption fails — wrong key, wrong label, or corrupted ciphertext (OAEP deliberately does not reveal which)

See also

Examples

ts
const plaintext = await decryptRsaOaepOrThrow(keys.privateKey, ciphertext);

derivePublicKey ​

Derive the matching public key from an imported (or generated) private key.

The import* functions that read a PKCS#8 / PKCS#1 / SEC 1 / JWK private key return a bare CryptoKey with only sign (or, for RSA-OAEP, decrypt) usage — there is no accompanying public handle. This bridges that gap: it exports the private key's JWK, strips the private components, and re-imports the public half with verify (RSA-OAEP: encrypt) usage, so callers can go straight to exportSpkiDer / exportSpkiPem (e.g. to rebuild a self-signed cert or distribute the public key when only the private key is on disk).

Supports RSA (n/e), ECDSA (x/y), and Ed25519 (x). The derived key inherits the private key's algorithm parameters (hash, curve).

ts
function derivePublicKey(
	privateKey: CryptoKey,
): Promise<CryptoKey>

Parameters

  • privateKey: CryptoKey — An extractable private CryptoKey

Returns — Extractable public CryptoKey with verify (RSA-OAEP: encrypt) usage

Throws

  • Error — If the key is not a private key, is non-extractable, or uses an unsupported key type

See also

Examples

ts
const privateKey = await importPkcs8PemOrThrow(pem, { kind: 'ecdsa', curve: 'P-256' });
const publicKey = await derivePublicKey(privateKey);
const spkiPem = await exportSpkiPem(publicKey);

encryptRsaOaep ​

Encrypt a small message with an RSA-OAEP public key.

ts
function encryptRsaOaep(
	publicKey: CryptoKey,
	plaintext: Uint8Array,
	_: unknown,
): Promise<EncryptRsaOaepResult>

Parameters

  • publicKey: CryptoKey
  • plaintext: Uint8Array
  • _: unknown

See also

  • encryptRsaOaepOrThrow for the throwing variant

Examples

ts
const keys = await generateKeyPair({ kind: 'rsa', scheme: 'oaep' });
const encrypted = await encryptRsaOaep(keys.publicKey, plaintext);
if (!encrypted.ok) {
	// encrypted.code: 'invalid_key' | 'message_too_long'
	throw new Error(encrypted.message);
}
const ciphertext = encrypted.value;

encryptRsaOaepOrThrow ​

Encrypt a small message with an RSA-OAEP public key.

The key must have been generated or imported with { kind: 'rsa', scheme: 'oaep' }. RSA-OAEP encrypts at most modulus bytes − 2 × hash bytes − 2 per call (190 bytes for a 2048-bit key with SHA-256) — encrypt a symmetric key, not bulk data.

ts
function encryptRsaOaepOrThrow(
	publicKey: CryptoKey,
	plaintext: Uint8Array,
	_: unknown,
): Promise<Uint8Array>

Parameters

  • publicKey: CryptoKey — RSA-OAEP public CryptoKey with encrypt usage
  • plaintext: Uint8Array — Message bytes, at most the OAEP capacity of the key
  • _: unknown

Throws

  • Error — If the key is not an RSA-OAEP public encryption key, or the plaintext exceeds the key's OAEP capacity

See also

Examples

ts
const keys = await generateKeyPair({ kind: 'rsa', scheme: 'oaep' });
const ciphertext = await encryptRsaOaepOrThrow(
	keys.publicKey,
	new TextEncoder().encode('session key'),
);

exportBinaryBase64 ​

Export a key as raw base64 (no PEM headers).

Returns SPKI-encoded base64 for public keys, PKCS#8-encoded base64 for private keys. Useful for compact storage or transmission where PEM overhead is undesirable.

ts
function exportBinaryBase64(
	key: CryptoKey,
): Promise<string>

Parameters

  • key: CryptoKey

Throws

  • Error — If the key is a symmetric/secret key

See also

exportEncryptedPkcs1Pem ​

Export an RSA private key as legacy Proc-Type: 4,ENCRYPTED PEM (PKCS#1).

Uses OpenSSL's traditional PEM encryption with MD5-based key derivation. For modern encryption, prefer exportEncryptedPkcs8Pem.

ts
function exportEncryptedPkcs1Pem(
	privateKey: CryptoKey,
	options: LegacyPemEncryptionOptions,
): Promise<string>

Parameters

Throws

  • Error — If the key is not an RSA key

See also

exportEncryptedPkcs8Der ​

Export a private key as DER-encoded PBES2-encrypted PKCS#8 EncryptedPrivateKeyInfo.

Uses PBES2 (PKCS#5 v2.1) with AES-CBC and PBKDF2. Compatible with OpenSSL.

ts
function exportEncryptedPkcs8Der(
	privateKey: CryptoKey,
	options: EncryptedPkcs8Options,
): Promise<Uint8Array>

Parameters

  • privateKey: CryptoKey — The private key to export
  • options: EncryptedPkcs8Options — Encryption options including password and optional algorithm settings

See also

exportEncryptedPkcs8Pem ​

Export a private key as PEM-encoded PBES2-encrypted PKCS#8 EncryptedPrivateKeyInfo.

ts
function exportEncryptedPkcs8Pem(
	privateKey: CryptoKey,
	options: EncryptedPkcs8Options,
): Promise<string>

Parameters

See also

Examples

ts
const keys = await generateKeyPair();
const pem = await exportEncryptedPkcs8Pem(keys.privateKey, { password: 'secret' });
// -----BEGIN ENCRYPTED PRIVATE KEY-----
// MIHsMFcGCSqGSIb3DQEFDTBKMCkGCSqGSIb3DQEFDDAc...
// -----END ENCRYPTED PRIVATE KEY-----

exportEncryptedSec1Pem ​

Export an EC private key as legacy Proc-Type: 4,ENCRYPTED PEM (SEC 1).

Uses OpenSSL's traditional PEM encryption with MD5-based key derivation. For modern encryption, prefer exportEncryptedPkcs8Pem.

ts
function exportEncryptedSec1Pem(
	privateKey: CryptoKey,
	options: LegacyPemEncryptionOptions,
): Promise<string>

Parameters

Throws

  • Error — If the key is not an EC key

See also

exportPkcs1Der ​

Export an RSA private key as DER-encoded PKCS#1 RSAPrivateKey.

PKCS#1 is the legacy RSA-only format. For algorithm-agnostic export, use exportPkcs8Der.

ts
function exportPkcs1Der(
	privateKey: CryptoKey,
): Promise<Uint8Array>

Parameters

  • privateKey: CryptoKey

Throws

  • Error — If the key is not an RSA key

See also

exportPkcs1Pem ​

Export an RSA private key as PEM-encoded PKCS#1 RSAPrivateKey.

ts
function exportPkcs1Pem(
	privateKey: CryptoKey,
): Promise<string>

Parameters

  • privateKey: CryptoKey

Throws

  • Error — If the key is not an RSA key

See also

exportPkcs8Der ​

Export a private key as DER-encoded PKCS#8 PrivateKeyInfo.

ts
function exportPkcs8Der(
	privateKey: CryptoKey,
): Promise<Uint8Array>

Parameters

  • privateKey: CryptoKey

See also

exportPkcs8Pem ​

Export a private key as PEM-encoded PKCS#8 PrivateKeyInfo.

ts
function exportPkcs8Pem(
	privateKey: CryptoKey,
): Promise<string>

Parameters

  • privateKey: CryptoKey

See also

Examples

ts
const keys = await generateKeyPair();
const pem = await exportPkcs8Pem(keys.privateKey);
// -----BEGIN PRIVATE KEY-----
// MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEH...
// -----END PRIVATE KEY-----

exportPrivateJwk ​

Export a private key as a JSON Web Key.

ts
function exportPrivateJwk(
	privateKey: CryptoKey,
): Promise<JsonWebKey>

Parameters

  • privateKey: CryptoKey

See also

exportPublicJwk ​

Export a public key as a JSON Web Key.

ts
function exportPublicJwk(
	publicKey: CryptoKey,
): Promise<JsonWebKey>

Parameters

  • publicKey: CryptoKey

Examples

ts
const keys = await generateKeyPair({ kind: 'ecdsa', curve: 'P-256' });
const jwk = await exportPublicJwk(keys.publicKey);

exportSec1Der ​

Export an EC private key as DER-encoded SEC 1 ECPrivateKey.

SEC 1 is the legacy EC-only format. For algorithm-agnostic export, use exportPkcs8Der.

The output always carries the RFC 5915 parameters [0] named curve (matching OpenSSL), so it re-imports via importSec1Der without an explicit curve.

ts
function exportSec1Der(
	privateKey: CryptoKey,
): Promise<Uint8Array>

Parameters

  • privateKey: CryptoKey

Throws

  • Error — If the key is not an EC key

See also

exportSec1Pem ​

Export an EC private key as PEM-encoded SEC 1 ECPrivateKey.

ts
function exportSec1Pem(
	privateKey: CryptoKey,
): Promise<string>

Parameters

  • privateKey: CryptoKey

Throws

  • Error — If the key is not an EC key

See also

exportSpkiDer ​

Export a public key as DER-encoded SubjectPublicKeyInfo.

ts
function exportSpkiDer(
	publicKey: CryptoKey,
): Promise<Uint8Array>

Parameters

  • publicKey: CryptoKey

See also

exportSpkiPem ​

Export a public key as PEM-encoded SubjectPublicKeyInfo.

ts
function exportSpkiPem(
	publicKey: CryptoKey,
): Promise<string>

Parameters

  • publicKey: CryptoKey

Examples

ts
const keys = await generateKeyPair();
const pem = await exportSpkiPem(keys.publicKey);

generateKeyPair ​

Generate an asymmetric key pair for signing and verification, or — with { kind: 'rsa', scheme: 'oaep' } — for RSA-OAEP encryption and decryption.

ts
function generateKeyPair(
	_: unknown,
): Promise<KeyPairMaterial>

Parameters

  • _: unknown

Examples

ts
const ecKeys = await generateKeyPair({ kind: 'ecdsa', curve: 'P-384' });
const rsaKeys = await generateKeyPair({ kind: 'rsa', modulusLength: 4096 });
const edKeys = await generateKeyPair({ kind: 'ed25519' });
const oaepKeys = await generateKeyPair({ kind: 'rsa', scheme: 'oaep' });

// Default: ECDSA P-256
const keys = await generateKeyPair();
const pem = await keys.exportPkcs8Pem();

importEncryptedPkcs1Pem ​

Import an RSA private key from legacy Proc-Type: 4,ENCRYPTED PEM (PKCS#1).

ts
function importEncryptedPkcs1Pem(
	pem: string,
	password: string,
	_: unknown,
): Promise<ImportEncryptedKeyResult<CryptoKey>>

Parameters

  • pem: string
  • password: string
  • _: unknown

See also

  • importEncryptedPkcs1PemOrThrow for the throwing variant

importEncryptedPkcs1PemOrThrow ​

Import an RSA private key from legacy Proc-Type: 4,ENCRYPTED PEM (PKCS#1).

Decrypts OpenSSL's traditional PEM encryption format.

ts
function importEncryptedPkcs1PemOrThrow(
	pem: string,
	password: string,
	_: unknown,
): Promise<CryptoKey>

Parameters

  • pem: string
  • password: string
  • _: unknown

See also

importEncryptedPkcs8Der ​

Import a private key from DER-encoded PBES2-encrypted PKCS#8 EncryptedPrivateKeyInfo.

ts
function importEncryptedPkcs8Der(
	der: Uint8Array,
	password: string,
	algorithm?: PrivateKeyImportInput,
): Promise<ImportEncryptedKeyResult<CryptoKey>>

Parameters

See also

  • importEncryptedPkcs8DerOrThrow for the throwing variant

importEncryptedPkcs8DerOrThrow ​

Import a private key from DER-encoded PBES2-encrypted PKCS#8 EncryptedPrivateKeyInfo.

Decrypts the PBES2 envelope using the provided password, then imports the key.

When algorithm is omitted, it is inferred from the decrypted key's own privateKeyAlgorithm (see importPkcs8DerOrThrow).

ts
function importEncryptedPkcs8DerOrThrow(
	der: Uint8Array,
	password: string,
	algorithm?: PrivateKeyImportInput,
): Promise<CryptoKey>

Parameters

  • der: Uint8Array — DER-encoded EncryptedPrivateKeyInfo bytes
  • password: string — Decryption password
  • algorithm?: PrivateKeyImportInput — Optional expected algorithm; must match decrypted key when given

Throws

  • Error — If DER is malformed, password is wrong, or algorithm doesn't match

See also

importEncryptedPkcs8Pem ​

Import a private key from PEM-encoded PBES2-encrypted PKCS#8 EncryptedPrivateKeyInfo.

ts
function importEncryptedPkcs8Pem(
	pem: string,
	password: string,
	algorithm?: PrivateKeyImportInput,
): Promise<ImportEncryptedKeyResult<CryptoKey>>

Parameters

See also

  • importEncryptedPkcs8PemOrThrow for the throwing variant

importEncryptedPkcs8PemOrThrow ​

Import a private key from PEM-encoded PBES2-encrypted PKCS#8 EncryptedPrivateKeyInfo.

When algorithm is omitted, it is inferred from the decrypted key's own privateKeyAlgorithm (see importPkcs8DerOrThrow).

ts
function importEncryptedPkcs8PemOrThrow(
	pem: string,
	password: string,
	algorithm?: PrivateKeyImportInput,
): Promise<CryptoKey>

Parameters

Examples

ts
const key = await importEncryptedPkcs8PemOrThrow(pem, 'secret', { kind: 'rsa' });
const inferred = await importEncryptedPkcs8PemOrThrow(pem, 'secret');

importEncryptedSec1Pem ​

Import an EC private key from legacy Proc-Type: 4,ENCRYPTED PEM (SEC 1).

ts
function importEncryptedSec1Pem(
	pem: string,
	password: string,
	algorithm?: ImportEcKeyInput,
): Promise<ImportEncryptedKeyResult<CryptoKey>>

Parameters

See also

  • importEncryptedSec1PemOrThrow for the throwing variant

importEncryptedSec1PemOrThrow ​

Import an EC private key from legacy Proc-Type: 4,ENCRYPTED PEM (SEC 1).

Decrypts OpenSSL's traditional PEM encryption format.

ts
function importEncryptedSec1PemOrThrow(
	pem: string,
	password: string,
	algorithm?: ImportEcKeyInput,
): Promise<CryptoKey>

Parameters

See also

importPkcs1Der ​

Import an RSA private key from DER-encoded PKCS#1 RSAPrivateKey.

ts
function importPkcs1Der(
	der: Uint8Array,
	_: unknown,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

  • der: Uint8Array
  • _: unknown

See also

  • importPkcs1DerOrThrow for the throwing variant

importPkcs1DerOrThrow ​

Import an RSA private key from DER-encoded PKCS#1 RSAPrivateKey.

PKCS#1 is the legacy RSA-only format. Internally converts to PKCS#8 for import.

ts
function importPkcs1DerOrThrow(
	der: Uint8Array,
	_: unknown,
): Promise<CryptoKey>

Parameters

  • der: Uint8Array
  • _: unknown

See also

importPkcs1Pem ​

Import an RSA private key from PEM-encoded PKCS#1 RSAPrivateKey.

ts
function importPkcs1Pem(
	pem: string,
	_: unknown,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

  • pem: string
  • _: unknown

See also

  • importPkcs1PemOrThrow for the throwing variant

importPkcs1PemOrThrow ​

Import an RSA private key from PEM-encoded PKCS#1 RSAPrivateKey.

Expects the -----BEGIN RSA PRIVATE KEY----- PEM label.

ts
function importPkcs1PemOrThrow(
	pem: string,
	_: unknown,
): Promise<CryptoKey>

Parameters

  • pem: string
  • _: unknown

See also

importPkcs8Base64 ​

Import a private key from base64-encoded PKCS#8 PrivateKeyInfo (no PEM headers).

ts
function importPkcs8Base64(
	base64: string,
	algorithm?: PrivateKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importPkcs8Base64OrThrow for the throwing variant

importPkcs8Base64OrThrow ​

Import a private key from base64-encoded PKCS#8 PrivateKeyInfo (no PEM headers).

ts
function importPkcs8Base64OrThrow(
	base64: string,
	algorithm?: PrivateKeyImportInput,
): Promise<CryptoKey>

Parameters

See also

importPkcs8Der ​

Import a private key from DER-encoded PKCS#8 PrivateKeyInfo.

ts
function importPkcs8Der(
	der: Uint8Array,
	algorithm?: PrivateKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importPkcs8DerOrThrow for the throwing variant

importPkcs8DerOrThrow ​

Import a private key from DER-encoded PKCS#8 PrivateKeyInfo.

When algorithm is omitted, the algorithm (and, for EC keys, the curve) is inferred from the PrivateKeyInfo's own privateKeyAlgorithm — useful for keys whose type isn't known ahead of time. Pass algorithm to additionally assert that the DER matches an expected algorithm.

ts
function importPkcs8DerOrThrow(
	der: Uint8Array,
	algorithm?: PrivateKeyImportInput,
): Promise<CryptoKey>

Parameters

  • der: Uint8Array — DER-encoded PKCS#8 PrivateKeyInfo bytes
  • algorithm?: PrivateKeyImportInput — Optional expected algorithm; must match key contents when given

Returns — Extractable CryptoKey with sign usage

Throws

  • Error — If DER is malformed, encodes an unsupported algorithm, or doesn't match algorithm

See also

importPkcs8Pem ​

Import a private key from PEM-encoded PKCS#8 PrivateKeyInfo.

ts
function importPkcs8Pem(
	pem: string,
	algorithm?: PrivateKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importPkcs8PemOrThrow for the throwing variant

importPkcs8PemOrThrow ​

Import a private key from PEM-encoded PKCS#8 PrivateKeyInfo.

When algorithm is omitted, it is inferred from the key's own privateKeyAlgorithm (see importPkcs8DerOrThrow).

ts
function importPkcs8PemOrThrow(
	pem: string,
	algorithm?: PrivateKeyImportInput,
): Promise<CryptoKey>

Parameters

Examples

ts
const key = await importPkcs8PemOrThrow(pemString, { kind: 'ecdsa', curve: 'P-256' });
const inferred = await importPkcs8PemOrThrow(pemString);

importPrivateJwk ​

Import a private signing key from a JSON Web Key.

ts
function importPrivateJwk(
	jwk: JsonWebKey,
	algorithm?: PrivateKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importPrivateJwkOrThrow for the throwing variant

importPrivateJwkOrThrow ​

Import a private signing key from a JSON Web Key.

When algorithm is omitted, it is inferred from the JWK's own kty, crv, and alg members (see importPublicJwkOrThrow).

ts
function importPrivateJwkOrThrow(
	jwk: JsonWebKey,
	algorithm?: PrivateKeyImportInput,
): Promise<CryptoKey>

Parameters

  • jwk: JsonWebKey — JSON Web Key object with private key components
  • algorithm?: PrivateKeyImportInput — Optional expected algorithm; must match JWK's kty and crv when given

Returns — Extractable CryptoKey with sign usage

Throws

  • Error — If JWK is malformed, lacks private key material, encodes an unsupported algorithm, or doesn't match algorithm

See also

Examples

ts
const jwk = { kty: 'EC', crv: 'P-256', x: '...', y: '...', d: '...' };
const key = await importPrivateJwkOrThrow(jwk, { kind: 'ecdsa', curve: 'P-256' });
const inferred = await importPrivateJwkOrThrow(jwk);

importPublicJwk ​

Import a public verification key from a JSON Web Key.

ts
function importPublicJwk(
	jwk: JsonWebKey,
	algorithm?: PublicKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importPublicJwkOrThrow for the throwing variant

importPublicJwkOrThrow ​

Import a public verification key from a JSON Web Key.

When algorithm is omitted, it is inferred from the JWK's own kty, crv, and alg members (e.g. PS256 → RSA-PSS/SHA-256, RSA-OAEP-256 → RSA-OAEP/SHA-256; an RSA JWK without alg defaults to PKCS#1 v1.5 with SHA-256). Pass algorithm to additionally assert an expected algorithm.

ts
function importPublicJwkOrThrow(
	jwk: JsonWebKey,
	algorithm?: PublicKeyImportInput,
): Promise<CryptoKey>

Parameters

  • jwk: JsonWebKey — JSON Web Key object with public key components
  • algorithm?: PublicKeyImportInput — Optional expected algorithm; must match JWK's kty and crv when given

Returns — Extractable CryptoKey with verify usage

Throws

  • Error — If JWK is malformed, encodes an unsupported algorithm, or doesn't match algorithm

See also

importSec1Der ​

Import an EC private key from DER-encoded SEC 1 ECPrivateKey.

ts
function importSec1Der(
	der: Uint8Array,
	algorithm?: ImportEcKeyInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importSec1DerOrThrow for the throwing variant

importSec1DerOrThrow ​

Import an EC private key from DER-encoded SEC 1 ECPrivateKey.

SEC 1 is the legacy EC-only format. Internally converts to PKCS#8 for import. When the ECPrivateKey carries the optional RFC 5915 parameters [0] field (OpenSSL always writes it), its named-curve OID must match algorithm.curve; when the field is absent, the caller-supplied curve is trusted.

When algorithm is omitted, the curve is inferred from the embedded parameters [0] field; a key without a supported named curve then fails.

ts
function importSec1DerOrThrow(
	der: Uint8Array,
	algorithm?: ImportEcKeyInput,
): Promise<CryptoKey>

Parameters

Throws

  • Error — If DER is not an ECPrivateKey, its embedded curve doesn't match algorithm, or no curve is available (neither embedded nor supplied)

See also

importSec1Pem ​

Import an EC private key from PEM-encoded SEC 1 ECPrivateKey.

ts
function importSec1Pem(
	pem: string,
	algorithm?: ImportEcKeyInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importSec1PemOrThrow for the throwing variant

importSec1PemOrThrow ​

Import an EC private key from PEM-encoded SEC 1 ECPrivateKey.

Expects the -----BEGIN EC PRIVATE KEY----- PEM label. When algorithm is omitted, the curve is inferred from the embedded parameters [0] field (see importSec1DerOrThrow).

ts
function importSec1PemOrThrow(
	pem: string,
	algorithm?: ImportEcKeyInput,
): Promise<CryptoKey>

Parameters

See also

importSpkiBase64 ​

Import a public key from base64-encoded SubjectPublicKeyInfo (no PEM headers).

ts
function importSpkiBase64(
	base64: string,
	algorithm?: PublicKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importSpkiBase64OrThrow for the throwing variant

importSpkiBase64OrThrow ​

Import a public key from base64-encoded SubjectPublicKeyInfo (no PEM headers).

ts
function importSpkiBase64OrThrow(
	base64: string,
	algorithm?: PublicKeyImportInput,
): Promise<CryptoKey>

Parameters

See also

importSpkiDer ​

Import a public key from DER-encoded SubjectPublicKeyInfo.

ts
function importSpkiDer(
	der: Uint8Array,
	algorithm?: PublicKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importSpkiDerOrThrow for the throwing variant

importSpkiDerOrThrow ​

Import a public key from DER-encoded SubjectPublicKeyInfo.

When algorithm is omitted, the algorithm (and, for EC keys, the curve) is inferred from the SPKI's own AlgorithmIdentifier — useful for keys whose type isn't known ahead of time. Pass algorithm to additionally assert that the DER matches an expected algorithm.

ts
function importSpkiDerOrThrow(
	der: Uint8Array,
	algorithm?: PublicKeyImportInput,
): Promise<CryptoKey>

Parameters

  • der: Uint8Array — DER-encoded SubjectPublicKeyInfo bytes
  • algorithm?: PublicKeyImportInput — Optional expected algorithm; must match key contents when given

Returns — Extractable CryptoKey with verify usage

Throws

  • Error — If DER is malformed, encodes an unsupported algorithm, or doesn't match algorithm

See also

importSpkiPem ​

Import a public key from PEM-encoded SubjectPublicKeyInfo.

ts
function importSpkiPem(
	pem: string,
	algorithm?: PublicKeyImportInput,
): Promise<ImportKeyResult<CryptoKey>>

Parameters

See also

  • importSpkiPemOrThrow for the throwing variant

importSpkiPemOrThrow ​

Import a public key from PEM-encoded SubjectPublicKeyInfo.

ts
function importSpkiPemOrThrow(
	pem: string,
	algorithm?: PublicKeyImportInput,
): Promise<CryptoKey>

Parameters

See also

Examples

ts
const pem = `-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----`;
const key = await importSpkiPemOrThrow(pem, { kind: 'ecdsa', curve: 'P-256' });

Released under the MIT License.

Copyright © 2026-present Kaj Kowalski