micro509/crypto

Canonical detached-signature crypto surface. Owns raw sign/verify primitives and ECDSA signature encoding conversion.

SignatureProfileInput

Controls how the signature algorithm is chosen.

'auto' (default) infers the algorithm from the key. 'rsa-pss' forces RSA-PSS padding and requires an RSA-PSS private key.

type SignatureProfileInput = {
  readonly kind?: auto
} | {
  readonly kind: rsa-pss;
  readonly saltLength?: 32 | 48 | 64
}

SignDataResult

Result of signData: the signature plus its on-wire algorithm identity.

interface SignDataResult {
	readonly signature: Uint8Array;
	readonly algorithmOid: string;
	readonly parametersDer?: Uint8Array;
}

Properties

• readonly signature: Uint8Array — The signature bytes. ECDSA is DER ECDSA-Sig-Value, everything else raw.
• readonly algorithmOid: string — Dotted-decimal signature algorithm OID.
• readonly parametersDer?: Uint8Array — DER algorithm parameters when the algorithm carries them (NULL for PKCS#1 v1.5, RSA-PSS params).

VerifySignatureConfigFailure

Failure: the signature algorithm or its parameters are not supported.

interface VerifySignatureConfigFailure {
	readonly ok: false;
	readonly code: unsupported_signature_algorithm_parameters;
	readonly reason: string;
}

Properties

• readonly ok: false — Discriminant for the failure branch.
• readonly code: unsupported_signature_algorithm_parameters — Machine-readable failure code.
• readonly reason: string — Human-readable explanation of why the algorithm is unsupported.

VerifySignatureInput

Input for verifySignature.

interface VerifySignatureInput {
	readonly signerSpkiDer: Uint8Array;
	readonly signatureAlgorithm: {
  readonly oid: string;
  readonly parametersDer?: Uint8Array
};
	readonly publicKeyAlgorithm: {
  readonly oid: string;
  readonly parametersOid?: string
};
	readonly signature: Uint8Array;
	readonly data: Uint8Array;
}

Properties

• readonly signerSpkiDer: Uint8Array — DER SubjectPublicKeyInfo of the signer (subjectPublicKeyInfoDer on a parsed certificate).
• readonly signatureAlgorithm: { readonly oid: string; readonly parametersDer?: Uint8Array } — The signature algorithm as carried beside the signature.
• readonly publicKeyAlgorithm: { readonly oid: string; readonly parametersOid?: string } — The signer's public key algorithm as carried in its SPKI.
• readonly signature: Uint8Array — The signature bytes. ECDSA accepts DER or raw encoding.
• readonly data: Uint8Array — The exact bytes the signature covers.

VerifySignedDataFailure

Failure: signature verification could not run to completion.

interface VerifySignedDataFailure {
	readonly ok: false;
	readonly code: verification_error;
	readonly reason: string;
}

Properties

• readonly ok: false — Discriminant for the failure branch.
• readonly code: verification_error — Machine-readable failure code.
• readonly reason: string — Human-readable explanation of the verification failure.

VerifySignedDataResult

Result of a full signature verification: validity, unsupported params, or a runtime verification failure.

type VerifySignedDataResult = VerifySignedDataSuccess | VerifySignatureConfigFailure | VerifySignedDataFailure

VerifySignedDataSuccess

Success branch of VerifySignedDataResult.

interface VerifySignedDataSuccess {
	readonly ok: true;
	readonly valid: boolean;
}

Properties

• readonly ok: true — Discriminant for the success branch.
• readonly valid: boolean — Whether the cryptographic signature is valid for the given data and key.

ecdsaSignatureDerToRaw

Converts a DER ECDSA-Sig-Value (RFC 5480: SEQUENCE of INTEGERs r and s) to the fixed-width raw r || s encoding WebCrypto and JOSE use. Throws on malformed DER or integers too large for the curve.

function ecdsaSignatureDerToRaw(
	signature: Uint8Array,
	curve: EcNamedCurve,
): Uint8Array

Parameters

• signature: Uint8Array
• curve: EcNamedCurve

ecdsaSignatureRawToDer

Converts a fixed-width raw r || s ECDSA signature to the DER ECDSA-Sig-Value encoding X.509 and CMS structures embed. Throws when the input length does not match the curve.

function ecdsaSignatureRawToDer(
	signature: Uint8Array,
	curve: EcNamedCurve,
): Uint8Array

Parameters

• signature: Uint8Array
• curve: EcNamedCurve

signData

Signs data with a WebCrypto private key and returns the signature beside the resolved AlgorithmIdentifier material for embedding in a signed structure.

The algorithm is inferred from the key (RSASSA-PKCS1-v1_5, ECDSA, Ed25519); RSA-PSS keys require an explicit { kind: 'rsa-pss' } profile. ECDSA signatures are returned DER-encoded. Throws on unsupported key algorithms.

function signData(
	privateKey: CryptoKey,
	data: Uint8Array,
	profile?: SignatureProfileInput,
): Promise<SignDataResult>

Parameters

• privateKey: CryptoKey
• data: Uint8Array
• profile?: SignatureProfileInput

verifySignature

Verifies a detached signature against the signer's DER SubjectPublicKeyInfo.

Supports RSA PKCS#1 v1.5 (SHA-256/384/512), RSA-PSS with parsed parameters, ECDSA P-256/P-384/P-521, and Ed25519. When an ECDSA signature fails to verify under one encoding, the alternate DER/raw encoding is retried.

Returns a typed union: { ok: true, valid } when verification ran, unsupported_signature_algorithm_parameters or verification_error failures otherwise.

function verifySignature(
	input: VerifySignatureInput,
): Promise<VerifySignedDataResult>

Parameters

• input: VerifySignatureInput