micro509

Appearance

micro509/pkcs ​

PKCS container APIs: PFX/PKCS#12 and PKCS#7/CMS.

Owns PFX archive creation and parsing, PKCS#7 certificate bags and SignedData, and PKCS#12 MAC integrity helpers.

CreatePfxErrorCode ​

Caller-correctable failure code from createPfx.

The only parse boundary in creation is the certificate source: it is normalized from untrusted PEM/DER. Private keys are either a WebCrypto CryptoKey (platform errors stay throws) or raw PKCS#8 bytes passed through unvalidated, so there is no distinct invalid_private_key failure to model.

ts
type CreatePfxErrorCode = invalid_certificate

CreatePfxFailure ​

Error payload for a failed PFX creation.

ts
interface CreatePfxFailure extends Micro509Error<CreatePfxErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

CreatePfxInput ​

Input for createPfx.

ts
interface CreatePfxInput {
	readonly certificates?: readonly PfxCertificateBagInput[];
	readonly privateKeys?: readonly PfxPrivateKeyBagInput[];
	readonly encryption?: PfxEncryptionOptions;
	readonly mac?: Pkcs12MacOptions;
}

Properties

  • readonly certificates?: readonly PfxCertificateBagInput[] — Certificates to include as certBag entries.
  • readonly privateKeys?: readonly PfxPrivateKeyBagInput[] — Private keys to include as keyBag entries.
  • readonly encryption?: PfxEncryptionOptions — PBES2 encryption settings for the key-bag ContentInfo. Omit for unencrypted.
  • readonly mac?: Pkcs12MacOptions — PKCS#12 MAC integrity settings. Omit to skip MAC generation.

CreatePfxResult ​

Success-or-failure result from createPfx.

ts
type CreatePfxResult = {
  readonly ok: true;
  readonly value: PfxMaterial
} | ErrorResult<CreatePfxErrorCode, Record<never, never>, CreatePfxFailure>

ParsedPfx ​

Fully decoded PFX container returned by parsePfxDer / parsePfxPem.

ts
interface ParsedPfx {
	readonly bags: readonly ParsedPfxBag[];
	readonly certificates: readonly ParsedCertificate[];
	readonly privateKeys: readonly Uint8Array[];
	readonly macData?: ParsedPkcs12MacData;
}

Properties

  • readonly bags: readonly ParsedPfxBag[] — All SafeBags in the PFX, including unknown types.
  • readonly certificates: readonly ParsedCertificate[] — Convenience: only the parsed certificates extracted from certBag entries.
  • readonly privateKeys: readonly Uint8Array``[] — Convenience: raw PKCS#8 DER of each private key extracted from keyBag entries.
  • readonly macData?: ParsedPkcs12MacData — MAC verification metadata, present when the PFX includes a MacData block.

ParsedPfxAttribute ​

A single PKCS#12 bag attribute as decoded by parsePfxDer.

ts
interface ParsedPfxAttribute {
	readonly oid: string;
	readonly valuesHex: readonly string[];
}

Properties

  • readonly oid: string — Dotted-decimal OID identifying this attribute type.
  • readonly valuesHex: readonly string``[] — Hex-encoded DER of each attribute value.

ParsedPfxBag ​

Discriminated union of SafeBag types decoded from a PFX container.

Use kind to narrow: 'certificate' | 'privateKey' | 'unknown'.

ts
type ParsedPfxBag = {
  readonly kind: certificate;
  readonly bagId: string;
  readonly attributes: ParsedPfxBagAttributes;
  readonly certificate: ParsedCertificate
} | {
  readonly kind: privateKey;
  readonly bagId: string;
  readonly attributes: ParsedPfxBagAttributes;
  readonly pkcs8Der: Uint8Array
} | {
  readonly kind: unknown;
  readonly bagId: string;
  readonly attributes: ParsedPfxBagAttributes;
  readonly valueDer: Uint8Array
}

ParsedPfxBagAttributes ​

Decoded bag attributes for a single SafeBag inside a PFX.

ts
interface ParsedPfxBagAttributes {
	readonly entries: readonly ParsedPfxAttribute[];
	readonly friendlyName?: string;
	readonly localKeyId?: string;
}

Properties

  • readonly entries: readonly ParsedPfxAttribute[] — All raw attributes as OID + hex-encoded values.
  • readonly friendlyName?: string — Decoded BMPString friendly-name attribute, if present.
  • readonly localKeyId?: string — Hex-encoded localKeyId attribute, if present.

ParsePfxErrorCode ​

Error codes returned by parsePfxDer and parsePfxPem.

ts
type ParsePfxErrorCode = malformed | invalid_password | password_required

ParsePfxFailure ​

Error payload for a failed PFX parse.

ts
interface ParsePfxFailure extends Micro509Error<ParsePfxErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

ParsePfxOptions ​

Options for parsePfxDer and parsePfxPem.

ts
interface ParsePfxOptions {
	readonly password?: string;
	readonly macPassword?: string;
}

Properties

  • readonly password?: string — Password used to decrypt PBES2-encrypted ContentInfo entries. Also used for MAC verification when macPassword is omitted.
  • readonly macPassword?: string — Separate password for MAC verification. Falls back to password when omitted.

ParsePfxResult ​

Success-or-failure result from parsePfxDer / parsePfxPem.

ts
type ParsePfxResult = {
  readonly ok: true;
  readonly value: ParsedPfx
} | ErrorResult<ParsePfxErrorCode, Record<never, never>, ParsePfxFailure>

PfxBagAttributesInput ​

Optional metadata attached to a certificate or key bag inside a PFX.

ts
interface PfxBagAttributesInput {
	readonly friendlyName?: string;
	readonly localKeyId?: Uint8Array;
}

Properties

  • readonly friendlyName?: string — Human-readable label stored as a BMPString attribute.
  • readonly localKeyId?: Uint8Array — Opaque identifier linking a certificate bag to its corresponding key bag.

PfxCertificateBagInput ​

A certificate to embed in a PFX container. Input for createPfx.

ts
interface PfxCertificateBagInput {
	readonly certificate: PfxCertificateSource;
	readonly attributes?: PfxBagAttributesInput;
}

Properties

PfxCertificateSource ​

PEM string or DER bytes for a certificate to include in a PFX bag.

ts
type PfxCertificateSource = string | Uint8Array | ParsedCertificate

PfxEncryptionOptions ​

PBES2 encryption settings for PFX key-bag protection. Alias of EncryptedPkcs8Options.

ts
type PfxEncryptionOptions = EncryptedPkcs8Options

PfxMaterial ​

DER, PEM, and base64 encodings of a PFX container produced by createPfx.

ts
interface PfxMaterial {
	readonly der: Uint8Array;
	readonly pem: string;
	readonly base64: string;
}

Properties

  • readonly der: Uint8Array — Raw DER-encoded PFX bytes.
  • readonly pem: string — PEM-armored PFX (-----BEGIN PKCS12-----).
  • readonly base64: string — Base64-encoded DER (no PEM armor).

PfxPrivateKeyBagInput ​

A private key to embed in a PFX container. Input for createPfx.

ts
interface PfxPrivateKeyBagInput {
	readonly privateKey: PfxPrivateKeySource;
	readonly attributes?: PfxBagAttributesInput;
}

Properties

  • readonly privateKey: PfxPrivateKeySource — Private key as a WebCrypto CryptoKey or raw PKCS#8 DER bytes.
  • readonly attributes?: PfxBagAttributesInput — Optional bag-level attributes (friendly name, local key ID).

PfxPrivateKeySource ​

A WebCrypto private key or raw PKCS#8 DER bytes for a PFX key bag.

ts
type PfxPrivateKeySource = CryptoKey | Uint8Array

createPfx ​

Builds a PKCS#12/PFX archive containing certificates and/or private keys.

When encryption is provided, the key-bag ContentInfo is PBES2-encrypted. When mac is provided, a PKCS#12 MAC integrity block is appended.

Returns a CreatePfxResult: the container material on success, or a typed invalid_certificate failure when a certificate source is not a single PEM/DER certificate.

ts
function createPfx(
	input: CreatePfxInput,
): Promise<CreatePfxResult>

Parameters

Examples

ts
import { createPfx, unwrap } from 'micro509';

const result = await createPfx({
  certificates: [{ certificate: certPem }],
  privateKeys: [{ privateKey: keyPair.privateKey }],
  encryption: { password: 's3cret' },
  mac: { password: 's3cret' },
});
if (result.ok) {
  const pfx = result.value; // pfx.der, pfx.pem, pfx.base64
}
// or, when inputs are already validated: const pfx = unwrap(result);

parsePfxDer ​

Decodes a DER-encoded PKCS#12/PFX container into its constituent bags.

Returns a result union — check ok before accessing value. Encrypted containers require options.password. MAC verification uses options.macPassword (falls back to options.password).

ts
function parsePfxDer(
	der: Uint8Array,
	options?: ParsePfxOptions,
): Promise<ParsePfxResult>

Parameters

Examples

ts
import { parsePfxDer } from 'micro509';

const result = await parsePfxDer(pfxBytes, { password: 's3cret' });
if (result.ok) {
  console.log(result.value.certificates.length);
}

parsePfxPem ​

Decodes a PEM-armored PKCS#12/PFX container. Expects exactly one PKCS12 block.

Delegates to parsePfxDer after PEM decoding.

ts
function parsePfxPem(
	pem: string,
	options?: ParsePfxOptions,
): Promise<ParsePfxResult>

Parameters

Examples

ts
import { parsePfxPem } from 'micro509';

const result = await parsePfxPem(pfxPemString, { password: 's3cret' });
if (result.ok) {
  console.log(result.value.privateKeys.length);
}

CreatePkcs7CertBagErrorCode ​

Caller-correctable failure code from createPkcs7CertBag.

ts
type CreatePkcs7CertBagErrorCode = invalid_certificate

CreatePkcs7CertBagFailure ​

Error payload for a failed PKCS#7 certificate bag creation.

ts
interface CreatePkcs7CertBagFailure extends Micro509Error<CreatePkcs7CertBagErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

CreatePkcs7CertBagResult ​

Success-or-failure result from createPkcs7CertBag.

ts
type CreatePkcs7CertBagResult = {
  readonly ok: true;
  readonly value: Pkcs7CertBagMaterial
} | ErrorResult<CreatePkcs7CertBagErrorCode, Record<never, never>, CreatePkcs7CertBagFailure>

CreatePkcs7SignedDataErrorCode ​

Caller-correctable failure codes from createPkcs7SignedData.

ts
type CreatePkcs7SignedDataErrorCode = no_signers | invalid_signer_certificate | invalid_certificate | unsupported_signer_key

CreatePkcs7SignedDataFailure ​

Error payload for a failed PKCS#7 SignedData creation.

ts
interface CreatePkcs7SignedDataFailure extends Micro509Error<CreatePkcs7SignedDataErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

CreatePkcs7SignedDataInput ​

Input for createPkcs7SignedData.

ts
interface CreatePkcs7SignedDataInput {
	readonly content: Uint8Array;
	readonly signers: readonly Pkcs7Signer[];
	readonly additionalCertificates?: readonly Pkcs7CertificateSource[];
	readonly encapsulatedContentTypeOid?: string;
	readonly detached?: boolean;
}

Properties

  • readonly content: Uint8Array — Content to encapsulate and sign (the eContent).
  • readonly signers: readonly Pkcs7Signer[] — One or more signers. Each produces a SignerInfo with signed attributes.
  • readonly additionalCertificates?: readonly Pkcs7CertificateSource[] — Additional certificates to embed (e.g. intermediates). Signer certificates are always embedded; duplicate DER is removed.
  • readonly encapsulatedContentTypeOid?: string — Encapsulated content type OID.
  • readonly detached?: boolean — Omit eContent from encapContentInfo (RFC 5652 Section 5.2 detached form). The signature still covers content via the messageDigest signed attribute, but the bytes are not embedded — the verifier must supply them externally (e.g. git x509 commit signing, S/MIME detached signatures).

CreatePkcs7SignedDataResult ​

Success-or-failure result from createPkcs7SignedData.

ts
type CreatePkcs7SignedDataResult = {
  readonly ok: true;
  readonly value: Pkcs7SignedDataMaterial
} | ErrorResult<CreatePkcs7SignedDataErrorCode, Record<never, never>, CreatePkcs7SignedDataFailure>

ParsedPkcs7SignedData ​

Decoded PKCS#7 SignedData content, including certificates and signer info.

ts
interface ParsedPkcs7SignedData {
	readonly der?: Uint8Array;
	readonly contentTypeOid: string;
	readonly version: number;
	readonly digestAlgorithmOids: readonly string[];
	readonly digestAlgorithmNames: readonly string[];
	readonly encapsulatedContentTypeOid: string;
	readonly encapsulatedContent?: Uint8Array;
	readonly certificates: readonly ParsedCertificate[];
	readonly signerInfos: readonly ParsedPkcs7SignerInfo[];
}

Properties

  • readonly der?: Uint8Array — Original DER bytes when this object came from parsePkcs7SignedDataDer or PEM parsing.
  • readonly contentTypeOid: string — Outer ContentInfo type OID (always pkcs7-signedData).
  • readonly version: number — SignedData version number.
  • readonly digestAlgorithmOids: readonly string``[] — OIDs of digest algorithms declared in digestAlgorithms.
  • readonly digestAlgorithmNames: readonly string``[] — Human-readable digest algorithm names declared in digestAlgorithms.
  • readonly encapsulatedContentTypeOid: string — OID of the encapsulated content type (e.g. pkcs7-data).
  • readonly encapsulatedContent?: Uint8Array — Raw encapsulated content bytes. Absent in degenerate (certs-only) bags.
  • readonly certificates: readonly ParsedCertificate[] — Certificates included in the SignedData certificate set.
  • readonly signerInfos: readonly ParsedPkcs7SignerInfo[] — Decoded signer info entries. Empty for degenerate cert bags.

ParsedPkcs7SignerInfo ​

A single SignerInfo decoded from a PKCS#7 SignedData structure.

Discriminated on hasSignedAttrs: when true, signedAttrsDer is always present; when false, it cannot exist.

ts
type ParsedPkcs7SignerInfo = (ParsedPkcs7SignerInfoBase & {
  readonly hasSignedAttrs: true;
  readonly signedAttrsDer: Uint8Array
}) | (ParsedPkcs7SignerInfoBase & {
  readonly hasSignedAttrs: false;
  readonly signedAttrsDer?: undefined
})

ParsedPkcs7SignerInfoBase ​

Fields shared by every decoded SignerInfo, regardless of signed-attribute presence.

ts
interface ParsedPkcs7SignerInfoBase {
	readonly version: number;
	readonly issuer?: ParsedName;
	readonly serialNumberHex?: string;
	readonly subjectKeyIdentifier?: string;
	readonly digestAlgorithmOid: string;
	readonly digestAlgorithmName: string;
	readonly signatureAlgorithmOid: string;
	readonly signatureAlgorithmName: string;
	readonly signatureAlgorithmParametersDer?: Uint8Array;
	readonly signatureHex: string;
	readonly signature: Uint8Array;
}

Properties

  • readonly version: number — CMS SignerInfo version (typically 1 for issuerAndSerialNumber).
  • readonly issuer?: ParsedName — Parsed issuer distinguished name, if present (issuerAndSerialNumber signer identifier).
  • readonly serialNumberHex?: string — Hex-encoded serial number used to locate the signer certificate, if present.
  • readonly subjectKeyIdentifier?: string — Hex-encoded SubjectKeyIdentifier used to locate the signer certificate, if present.
  • readonly digestAlgorithmOid: string — OID of the digest algorithm used to hash the content.
  • readonly digestAlgorithmName: string — Human-readable digest algorithm name (e.g. "SHA-256").
  • readonly signatureAlgorithmOid: string — OID of the algorithm used to produce the signature.
  • readonly signatureAlgorithmName: string — Human-readable signature algorithm name.
  • readonly signatureAlgorithmParametersDer?: Uint8Array — Raw DER of the signature AlgorithmIdentifier parameters, if present.
  • readonly signatureHex: string — Hex-encoded raw signature bytes.
  • readonly signature: Uint8Array — Raw signature bytes.

ParsePkcs7CertBagResult ​

Success-or-failure result from parsePkcs7CertBagDer / parsePkcs7CertBagPem.

ts
type ParsePkcs7CertBagResult = {
  readonly ok: true;
  readonly value: readonly ParsedCertificate[]
} | ErrorResult<ParsePkcs7ErrorCode, Record<never, never>, ParsePkcs7Failure>

ParsePkcs7ErrorCode ​

Error codes for PKCS#7 parse failures.

ts
type ParsePkcs7ErrorCode = malformed | not_signed_data

ParsePkcs7Failure ​

Error payload for a failed PKCS#7 parse.

ts
interface ParsePkcs7Failure extends Micro509Error<ParsePkcs7ErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

ParsePkcs7SignedDataResult ​

Success-or-failure result from parsePkcs7SignedDataDer / parsePkcs7SignedDataPem.

ts
type ParsePkcs7SignedDataResult = {
  readonly ok: true;
  readonly value: ParsedPkcs7SignedData
} | ErrorResult<ParsePkcs7ErrorCode, Record<never, never>, ParsePkcs7Failure>

Pkcs7CertBagMaterial ​

DER, PEM, and base64 encodings of a PKCS#7 certificate bag.

ts
interface Pkcs7CertBagMaterial {
	readonly der: Uint8Array;
	readonly pem: string;
	readonly base64: string;
}

Properties

  • readonly der: Uint8Array — Raw DER-encoded PKCS#7 structure.
  • readonly pem: string — PEM-armored PKCS#7 (-----BEGIN PKCS7-----).
  • readonly base64: string — Base64-encoded DER (no PEM armor).

Pkcs7CertificateSource ​

PEM text (may contain multiple CERTIFICATE blocks), raw DER bytes, or an already-parsed certificate.

ts
type Pkcs7CertificateSource = string | Uint8Array | ParsedCertificate

Pkcs7SignedDataMaterial ​

DER, PEM, and base64 encodings of a PKCS#7 SignedData structure.

ts
interface Pkcs7SignedDataMaterial {
	readonly der: Uint8Array;
	readonly pem: string;
	readonly base64: string;
}

Properties

  • readonly der: Uint8Array — Raw DER-encoded PKCS#7 SignedData.
  • readonly pem: string — PEM-armored PKCS#7 (-----BEGIN PKCS7-----).
  • readonly base64: string — Base64-encoded DER (no PEM armor).

Pkcs7Signer ​

A single signer for createPkcs7SignedData.

ts
interface Pkcs7Signer {
	readonly certificate: Pkcs7CertificateSource;
	readonly privateKey: CryptoKey;
	readonly signature?: SignatureProfileInput;
}

Properties

  • readonly certificate: Pkcs7CertificateSource — Signer certificate (PEM text with one CERTIFICATE block, or raw DER). Embedded in the SignedData certificate set and referenced by the SignerInfo via issuerAndSerialNumber.
  • readonly privateKey: CryptoKey — Private key matching the certificate's public key, used to sign.
  • readonly signature?: SignatureProfileInput — Signature profile. Defaults to inferring the algorithm from the key (e.g. ECDSA→ecdsa-with-SHA*, RSA→sha*WithRSAEncryption, Ed25519). Pass { kind: 'rsa-pss' } to force RSA-PSS padding for an RSA-PSS key.

VerifyPkcs7SignedDataErrorCode ​

Error codes for verifyPkcs7SignedData failures.

detached_content_required means the SignedData carries no eContent (detached signature or degenerate cert bag) and no external content was supplied via VerifyPkcs7SignedDataOptions.

ts
type VerifyPkcs7SignedDataErrorCode = signer_not_found | signature_invalid | message_digest_mismatch | detached_content_required | ParsePkcs7ErrorCode

VerifyPkcs7SignedDataFailure ​

Error payload for a failed verifyPkcs7SignedData call.

ts
interface VerifyPkcs7SignedDataFailure extends Micro509Error<VerifyPkcs7SignedDataErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

VerifyPkcs7SignedDataOptions ​

Options for verifyPkcs7SignedData.

ts
interface VerifyPkcs7SignedDataOptions {
	readonly content?: Uint8Array;
}

Properties

  • readonly content?: Uint8Array — External content for a detached SignedData (RFC 5652 Section 5.2, absent eContent). Required to verify a detached signature; ignored when the SignedData embeds its own content.

VerifyPkcs7SignedDataResult ​

Success-or-failure result from verifyPkcs7SignedData.

ts
type VerifyPkcs7SignedDataResult = {
  readonly ok: true;
  readonly value: ParsedPkcs7SignedData
} | ErrorResult<VerifyPkcs7SignedDataErrorCode, Record<never, never>, VerifyPkcs7SignedDataFailure>

createPkcs7CertBag ​

Creates a degenerate PKCS#7 SignedData structure containing only certificates (no signers), returning DER, PEM, and base64 forms, or a typed invalid_certificate failure when a certificate source is not valid PEM/DER.

ts
function createPkcs7CertBag(
	certificates: readonly Pkcs7CertificateSource[],
): CreatePkcs7CertBagResult

Parameters

createPkcs7SignedData ​

Creates a PKCS#7/CMS SignedData with one or more signers over content.

Each signer uses the RFC 5652 Section 5.4 signed-attributes flow: the signature covers a SET OF authenticated attributes carrying contentType and messageDigest (the digest of the encapsulated content). By default the content is embedded (attached signature), so the result verifies with verifyPkcs7SignedData without any external data. With detached: true the eContent is omitted (RFC 5652 Section 5.2) and the verifier must supply the content externally.

The content digest is derived from each signer's key (P-256/RSA-SHA256 → SHA-256, P-384 → SHA-384, P-521 → SHA-512, Ed25519 → SHA-512 per RFC 8419).

Returns a CreatePkcs7SignedDataResult: DER, PEM, and base64 forms on success, or a typed failure for caller-correctable input (no signers, a signer source that is not exactly one certificate, or an unsupported signer key).

ts
function createPkcs7SignedData(
	input: CreatePkcs7SignedDataInput,
): Promise<CreatePkcs7SignedDataResult>

Parameters

parsePkcs7CertBagDer ​

Parses a DER-encoded PKCS#7 cert bag, returning the contained certificates.

ts
function parsePkcs7CertBagDer(
	der: Uint8Array,
): ParsePkcs7CertBagResult

Parameters

  • der: Uint8Array

parsePkcs7CertBagPem ​

Parses a PEM-armored PKCS#7 cert bag. Expects exactly one PKCS7 PEM block.

ts
function parsePkcs7CertBagPem(
	pem: string,
): ParsePkcs7CertBagResult

Parameters

  • pem: string

parsePkcs7SignedDataDer ​

Decodes a DER-encoded PKCS#7 ContentInfo expecting signedData content type.

ts
function parsePkcs7SignedDataDer(
	der: Uint8Array,
): ParsePkcs7SignedDataResult

Parameters

  • der: Uint8Array

parsePkcs7SignedDataPem ​

Decodes a PEM-armored PKCS#7 SignedData. Expects exactly one PKCS7 PEM block.

ts
function parsePkcs7SignedDataPem(
	pem: string,
): ParsePkcs7SignedDataResult

Parameters

  • pem: string

verifyPkcs7SignedData ​

Verifies all signer signatures in a PKCS#7 SignedData structure.

Accepts PEM text, raw DER, or an already-parsed ParsedPkcs7SignedData. For each signer, locates the matching certificate in the embedded set and verifies the signature (including signed-attribute digest checks per RFC 5652 Section 5.4).

For a detached SignedData (absent eContent), pass the externally-held content via options.content; without it, verification fails with the typed detached_content_required code. When the SignedData embeds its own content, that embedded content is verified and options.content is ignored.

ts
function verifyPkcs7SignedData(
	input: string | Uint8Array | ParsedPkcs7SignedData,
	_: unknown,
): Promise<VerifyPkcs7SignedDataResult>

Parameters

Examples

ts
import { verifyPkcs7SignedData } from 'micro509';

const result = await verifyPkcs7SignedData(pkcs7Pem);
if (result.ok) {
  console.log('all signers verified');
}

// Detached signature: supply the content externally
const detached = await verifyPkcs7SignedData(cmsBlob, { content: signedBytes });

ParsedPkcs12MacData ​

Decoded PKCS#12 MacData block returned by parsePkcs12MacData.

ts
interface ParsedPkcs12MacData {
	readonly digestAlgorithmOid: string;
	readonly digestAlgorithmName: string;
	readonly digestHex: string;
	readonly saltHex: string;
	readonly iterations: number;
	readonly verification: valid | invalid | unchecked;
}

Properties

  • readonly digestAlgorithmOid: string — OID of the digest algorithm (currently always SHA-256).
  • readonly digestAlgorithmName: string — Human-readable digest algorithm name (currently "SHA-256").
  • readonly digestHex: string — Hex-encoded MAC digest value.
  • readonly saltHex: string — Hex-encoded salt bytes used during key derivation.
  • readonly iterations: number — Number of PKCS#12 KDF iterations.
  • readonly verification: valid | invalid | unchecked — MAC verification outcome: 'unchecked' when no password was supplied during parsing, otherwise 'valid' or 'invalid'.

ParsePkcs12MacDataErrorCode ​

Machine-readable failure reason for parsePkcs12MacData.

ts
type ParsePkcs12MacDataErrorCode = malformed

ParsePkcs12MacDataFailure ​

Structured failure payload for MacData parsing.

ts
interface ParsePkcs12MacDataFailure extends Micro509Error<ParsePkcs12MacDataErrorCode> {
	readonly ok: false;
}

Properties

  • readonly ok: false — Always false for failures.

ParsePkcs12MacDataResult ​

Success-or-failure result from parsePkcs12MacData.

ts
type ParsePkcs12MacDataResult = {
  readonly ok: true;
  readonly value: ParsedPkcs12MacData
} | ErrorResult<ParsePkcs12MacDataErrorCode, Record<never, never>, ParsePkcs12MacDataFailure>

Pkcs12MacOptions ​

Input for createPkcs12MacData.

ts
interface Pkcs12MacOptions {
	readonly password: string;
	readonly iterations?: number;
	readonly salt?: Uint8Array;
}

Properties

  • readonly password: string — Password used to derive the HMAC key via the PKCS#12 KDF.
  • readonly iterations?: number — PKCS#12 KDF iteration count. Default: 2048.
  • readonly salt?: Uint8Array — Random salt. Default: 16 cryptographically random bytes.

createPkcs12MacData ​

Computes a PKCS#12 HMAC-SHA-256 MAC over the AuthenticatedSafe and returns the DER-encoded MacData block alongside its parsed representation.

ts
function createPkcs12MacData(
	authenticatedSafe: Uint8Array,
	options: Pkcs12MacOptions,
): Promise<{
  readonly der: Uint8Array;
  readonly parsed: ParsedPkcs12MacData
}>

Parameters

parsePkcs12MacData ​

Decodes a DER-encoded MacData block. When password is provided, verifies the MAC and reports the outcome in verification.

Returns a typed failure (code: 'malformed') on malformed input. For the throwing form use parsePkcs12MacDataOrThrow.

ts
function parsePkcs12MacData(
	der: Uint8Array,
	authenticatedSafe: Uint8Array,
	password?: string,
): Promise<ParsePkcs12MacDataResult>

Parameters

  • der: Uint8Array
  • authenticatedSafe: Uint8Array
  • password?: string

parsePkcs12MacDataOrThrow ​

Throwing core for parsePkcs12MacData. When password is provided, verifies the MAC and reports the outcome in verification.

ts
function parsePkcs12MacDataOrThrow(
	der: Uint8Array,
	authenticatedSafe: Uint8Array,
	password?: string,
): Promise<ParsedPkcs12MacData>

Parameters

  • der: Uint8Array
  • authenticatedSafe: Uint8Array
  • password?: string

Released under the MIT License.

Copyright © 2026-present Kaj Kowalski