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.

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.

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

Parameters

  • der: Uint8Array — DER-encoded EncryptedPrivateKeyInfo bytes
  • password: string — Decryption password
  • algorithm: PrivateKeyImportInput — Expected algorithm (must match decrypted key)

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.

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

Parameters

Examples

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

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.

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

Parameters

  • der: Uint8Array — DER-encoded PKCS#8 PrivateKeyInfo bytes
  • algorithm: PrivateKeyImportInput — Expected algorithm (must match key contents)

Returns — Extractable CryptoKey with sign usage

Throws

  • Error — If DER is malformed or algorithm doesn't match key

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.

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

Parameters

Examples

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

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.

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

Parameters

  • jwk: JsonWebKey — JSON Web Key object with private key components
  • algorithm: PrivateKeyImportInput — Expected algorithm (must match JWK's kty and crv)

Returns — Extractable CryptoKey with sign usage

Throws

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

See also

Examples

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

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.

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

Parameters

  • jwk: JsonWebKey — JSON Web Key object with public key components
  • algorithm: PublicKeyImportInput — Expected algorithm (must match JWK's kty and crv)

Returns — Extractable CryptoKey with verify usage

Throws

  • Error — If JWK is malformed or algorithm doesn't match

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.

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

Parameters

Throws

  • Error — If DER is not an ECPrivateKey or its embedded curve doesn't match algorithm

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.

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