@wirebench/engine 2.1.1

package/dist/wss/incoming/verify.js

@@ -0,0 +1,440 @@
+/**
+ * Verification of an *incoming* message: every `ds:Signature` in a `wsse:Security` header, and
+ * the header's `wsu:Timestamp`.
+ *
+ * Two questions are answered separately, because they fail for different reasons and a user
+ * has to be able to tell them apart:
+ *
+ * - **validity** — does the signature actually hold over the bytes that arrived? That is
+ *   Task 38's {@link verifySignature}, run against the certificate the message's own `KeyInfo`
+ *   points at.
+ * - **trust** — is that certificate one we accept? A signature verifies perfectly against the
+ *   key that made it, including a key an attacker owns, so the certificate is checked against
+ *   the configured truststore: stored verbatim, or (with `verifyChain`) chaining to one of its
+ *   certificates.
+ *
+ * `KeyInfo` is therefore a *hint* about which key to look up, never a source of trust.
+ */
+import forge from 'node-forge';
+import { NS } from '../../xml/namespaces.js';
+import { parseXml } from '../../xml/parse.js';
+import { serializeXml } from '../../xml/serialize.js';
+import { renderDn, renderDnRfc2253 } from '../keystore/certificate.js';
+import { certificateBase64, subjectKeyIdentifierBase64, thumbprintSha1Base64, WSS_TOKEN_TYPES, } from '../key-identifiers.js';
+import { childElement, findElement } from '../security-header.js';
+import { verifySignature } from '../outgoing/signature.js';
+/** Every descendant-or-self of `root` in `namespace` with local name `localName`, in document order. */
+function findAll(root, namespace, localName) {
+    const found = [];
+    const walk = (node) => {
+        if (node.namespaceURI === namespace && node.localName === localName) {
+            found.push(node);
+        }
+        for (let child = node.firstChild; child !== null; child = child.nextSibling) {
+            if (child.nodeType === 1) {
+                walk(child);
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+/**
+ * Every element under `root` by the value of its `Id` attribute (in any namespace, or none),
+ * built once per document.
+ *
+ * A *list* per id rather than the first match: a duplicated id is how a signature-wrapping
+ * attack hides a second element behind a reference, so ambiguity has to be visible rather than
+ * resolved by document order.
+ */
+function idIndex(root) {
+    const index = new Map();
+    const walk = (node) => {
+        for (let position = 0; position < node.attributes.length; position += 1) {
+            const attribute = node.attributes.item(position);
+            if (attribute !== null && attribute.localName === 'Id' && attribute.value !== '') {
+                const found = index.get(attribute.value);
+                if (found === undefined) {
+                    index.set(attribute.value, [node]);
+                }
+                else {
+                    found.push(node);
+                }
+            }
+        }
+        for (let child = node.firstChild; child !== null; child = child.nextSibling) {
+            if (child.nodeType === 1) {
+                walk(child);
+            }
+        }
+    };
+    walk(root);
+    return index;
+}
+/** The one element carrying `id`, or `undefined` when no element — or more than one — does. */
+function uniqueById(index, id) {
+    const found = index.get(id);
+    return found?.length === 1 ? found[0] : undefined;
+}
+/** The text of `element` with every whitespace character removed, so wrapped base64 compares. */
+function textOf(element) {
+    return element === undefined ? '' : (element.textContent ?? '').replace(/\s+/g, '');
+}
+/** A forge certificate from base64 DER, or `undefined` when the bytes are not one. */
+function certificateFromBase64(value) {
+    if (value === '') {
+        return undefined;
+    }
+    try {
+        const der = forge.util.createBuffer(Buffer.from(value, 'base64').toString('binary'));
+        return forge.pki.certificateFromAsn1(forge.asn1.fromDer(der));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The leaf of an `X509PKIPathv1` value: a DER `SEQUENCE OF Certificate`, leaf first (as
+ * `pkiPathBase64` writes it). `undefined` when the bytes are not such a sequence.
+ */
+function certificateFromPkiPath(value) {
+    try {
+        const der = forge.util.createBuffer(Buffer.from(value, 'base64').toString('binary'));
+        const sequence = forge.asn1.fromDer(der);
+        const first = Array.isArray(sequence.value) ? sequence.value[0] : undefined;
+        return first === undefined ? undefined : forge.pki.certificateFromAsn1(first);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Every certificate the truststore holds, parsed — and rendered to PEM and DER — once per call.
+ * Re-deriving these per signature is what made a large truststore quadratic.
+ */
+function truststoreCertificates(truststore) {
+    if (truststore === undefined) {
+        return [];
+    }
+    const certificates = [];
+    for (const alias of truststore.aliases) {
+        for (const pem of [alias.certPem, ...alias.chainPem]) {
+            try {
+                const cert = forge.pki.certificateFromPem(pem);
+                const normalized = forge.pki.certificateToPem(cert);
+                certificates.push({ cert, pem: normalized, der: certificateBase64(normalized) });
+            }
+            catch {
+                // A truststore entry this build cannot parse simply trusts nothing.
+            }
+        }
+    }
+    return certificates;
+}
+/**
+ * Parses an RFC 2253/4514 distinguished name into its attributes: split on unescaped `,` (and
+ * `+`, which joins a multi-valued RDN), then on the first unescaped `=`, unescaping `\x` and
+ * `\XX` hex pairs in the value.
+ *
+ * Needed because an `X509IssuerName` is only *semantically* equal to the DN this build renders:
+ * a peer is free to space, order and escape it differently, and comparing the rendered strings
+ * would reject a certificate we do hold.
+ */
+function parseRfc2253(dn) {
+    const parts = [];
+    let current = '';
+    for (let index = 0; index < dn.length; index += 1) {
+        const char = dn.charAt(index);
+        if (char === '\\') {
+            current += char + dn.charAt(index + 1);
+            index += 1;
+        }
+        else if (char === ',' || char === '+') {
+            parts.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    parts.push(current);
+    const attributes = [];
+    for (const part of parts) {
+        const separator = part.indexOf('=');
+        if (separator <= 0) {
+            continue;
+        }
+        attributes.push({
+            type: part.slice(0, separator).trim(),
+            value: unescapeRfc2253(part.slice(separator + 1).trim()),
+        });
+    }
+    return attributes;
+}
+/** Undoes RFC 2253 escaping: `\c` is `c`, `\XX` is the byte `XX`. */
+function unescapeRfc2253(value) {
+    let out = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value.charAt(index);
+        if (char !== '\\') {
+            out += char;
+            continue;
+        }
+        const pair = value.slice(index + 1, index + 3);
+        if (/^[0-9a-fA-F]{2}$/.test(pair)) {
+            out += String.fromCharCode(Number.parseInt(pair, 16));
+            index += 2;
+        }
+        else {
+            out += value.charAt(index + 1);
+            index += 1;
+        }
+    }
+    return out;
+}
+/** A DN's attributes as a sorted, comparable key: type case-insensitive, value verbatim. */
+function dnKey(attributes) {
+    return attributes
+        .map((attribute) => `${attribute.type.toLowerCase()}=${attribute.value}`)
+        .sort()
+        .join(',');
+}
+/** Whether `issuerName` names the same DN as `attributes`, whatever rendering it arrived in. */
+function sameDn(issuerName, attributes) {
+    const rendered = renderDnRfc2253(attributes);
+    // Fast path: the common case is a peer that renders the DN exactly as this build does.
+    return rendered === issuerName || dnKey(parseRfc2253(rendered)) === dnKey(parseRfc2253(issuerName));
+}
+/**
+ * The certificate a `ds:KeyInfo` names. Every X.509 token profile form is understood: the ones
+ * that *carry* the certificate (a `wsse:Reference` to a `BinarySecurityToken`, an `X509v3`
+ * `KeyIdentifier`, an inline `ds:X509Certificate`) yield it directly; the ones that merely
+ * *name* it (`IssuerSerial`, `SubjectKeyIdentifier`, `ThumbprintSHA1`) are looked up among
+ * `trusted`, which is why an untrusted signer using one of them cannot be resolved at all.
+ */
+function certificateFromKeyInfo(ids, keyInfo, trusted) {
+    if (keyInfo === undefined) {
+        return undefined;
+    }
+    const reference = findElement(keyInfo, NS.WSSE, 'Reference');
+    if (reference !== undefined) {
+        const uri = reference.getAttribute('URI') ?? '';
+        const token = uri.startsWith('#') ? uniqueById(ids, uri.slice(1)) : undefined;
+        const value = textOf(token);
+        return certificateFromBase64(value) ?? certificateFromPkiPath(value);
+    }
+    const identifier = findElement(keyInfo, NS.WSSE, 'KeyIdentifier');
+    if (identifier !== undefined) {
+        const valueType = identifier.getAttribute('ValueType') ?? '';
+        const value = textOf(identifier);
+        if (valueType === WSS_TOKEN_TYPES.THUMBPRINT_SHA1) {
+            return lookup(trusted, (pem) => thumbprintSha1Base64(pem) === value);
+        }
+        if (valueType === WSS_TOKEN_TYPES.X509_SUBJECT_KEY_IDENTIFIER) {
+            return lookup(trusted, (pem) => subjectKeyIdentifierBase64(pem) === value);
+        }
+        return certificateFromBase64(value) ?? certificateFromPkiPath(value);
+    }
+    const issuerSerial = findElement(keyInfo, NS.DS, 'X509IssuerSerial');
+    if (issuerSerial !== undefined) {
+        const issuer = (childElement(issuerSerial, NS.DS, 'X509IssuerName')?.textContent ?? '').trim();
+        const serial = (childElement(issuerSerial, NS.DS, 'X509SerialNumber')?.textContent ?? '').trim();
+        return trusted.find((candidate) => sameDn(issuer, candidate.cert.issuer.attributes) &&
+            BigInt(`0x${candidate.cert.serialNumber}`).toString(10) === serial)?.cert;
+    }
+    const inline = findElement(keyInfo, NS.DS, 'X509Certificate');
+    return inline === undefined ? undefined : certificateFromBase64(textOf(inline));
+}
+/** The first trusted certificate whose PEM satisfies `matches`; a form it cannot compute never matches. */
+function lookup(trusted, matches) {
+    return trusted.find((candidate) => {
+        try {
+            return matches(candidate.pem);
+        }
+        catch {
+            return false;
+        }
+    })?.cert;
+}
+/**
+ * Whether `certificate` is trusted: byte-identical to a truststore certificate, or — with
+ * `verifyChain` — issued (transitively) by one of them, with every certificate in the path
+ * valid at `at`.
+ */
+function isTrusted(certificate, trusted, verifyChain, at) {
+    if (trusted.length === 0) {
+        return false;
+    }
+    const der = certificateBase64(forge.pki.certificateToPem(certificate));
+    if (trusted.some((candidate) => candidate.der === der)) {
+        // Pinned, but an expired certificate is not a trusted one: the equality path has to judge
+        // validity against the injected clock exactly as the chain path does.
+        return (certificate.validity.notBefore.getTime() <= at.getTime() &&
+            at.getTime() <= certificate.validity.notAfter.getTime());
+    }
+    if (!verifyChain) {
+        return false;
+    }
+    try {
+        const caStore = forge.pki.createCaStore(trusted.map((candidate) => candidate.cert));
+        // `validityCheckDate` is what makes the injected clock reach forge; without it the chain
+        // would be judged against the wall clock and a frozen-clock test could not exist.
+        return forge.pki.verifyCertificateChain(caStore, [certificate], { validityCheckDate: at });
+    }
+    catch {
+        return false;
+    }
+}
+/** The `URI`s of a `ds:Signature`'s references, without their leading `#`. */
+function referenceIds(signature) {
+    const signedInfo = childElement(signature, NS.DS, 'SignedInfo');
+    if (signedInfo === undefined) {
+        return [];
+    }
+    return findAll(signedInfo, NS.DS, 'Reference')
+        .map((reference) => reference.getAttribute('URI') ?? '')
+        .filter((uri) => uri.startsWith('#'))
+        .map((uri) => uri.slice(1));
+}
+/** The envelope's `soap:Body`, in either SOAP version, or `undefined` for a non-SOAP document. */
+function bodyElement(root) {
+    return findElement(root, NS.SOAP11_ENV, 'Body') ?? findElement(root, NS.SOAP12_ENV, 'Body');
+}
+/** Parses `wsu:Created`/`wsu:Expires`, returning `undefined` for anything not a date. */
+function parseInstant(value) {
+    if (value === undefined || value.trim() === '') {
+        return undefined;
+    }
+    const parsed = new Date(value.trim());
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+/** Judges the `wsu:Timestamp` under `security`, or `undefined` when there is none. */
+function readTimestamp(security, options) {
+    const timestamp = findElement(security, NS.WSU, 'Timestamp');
+    if (timestamp === undefined) {
+        return undefined;
+    }
+    const createdText = childElement(timestamp, NS.WSU, 'Created')?.textContent ?? '';
+    const expiresElement = childElement(timestamp, NS.WSU, 'Expires');
+    const expiresText = expiresElement?.textContent ?? undefined;
+    const created = parseInstant(createdText);
+    const expires = parseInstant(expiresText);
+    const base = {
+        created: createdText.trim(),
+        ...(expiresText !== undefined ? { expires: expiresText.trim() } : {}),
+    };
+    if (created === undefined) {
+        return { ...base, fresh: false, error: 'The timestamp has no readable wsu:Created.' };
+    }
+    const skewMs = options.skewSeconds * 1000;
+    const now = options.clock().getTime();
+    if (now + skewMs < created.getTime()) {
+        return { ...base, fresh: false, error: 'The message was created in the future.' };
+    }
+    if (expires !== undefined) {
+        return now - skewMs > expires.getTime()
+            ? { ...base, fresh: false, error: 'The message expired.' }
+            : { ...base, fresh: true };
+    }
+    // No `Expires`: the skew window is all there is to judge against, so a `Created` older than
+    // it is stale rather than merely unbounded.
+    return now - skewMs > created.getTime()
+        ? { ...base, fresh: false, error: 'The message is older than the tolerated clock skew.' }
+        : { ...base, fresh: true };
+}
+/**
+ * Verifies every `ds:Signature` in `xml`'s `wsse:Security` headers and reads its
+ * `wsu:Timestamp`.
+ *
+ * Never throws: an unparsable, unsigned or non-SOAP message simply produces no signatures and
+ * no timestamp, which is what "this response had no WS-Security" has to look like.
+ *
+ * @param xml the (already decrypted) response envelope
+ * @param options the truststore, the clock, the tolerated skew and whether to follow chains
+ * @returns one result per signature, plus the timestamp when the message carries one
+ */
+export function verifyIncoming(xml, options) {
+    let doc;
+    let root;
+    try {
+        doc = parseXml(xml, { location: 'envelope' });
+        root = doc.documentElement ?? undefined;
+    }
+    catch {
+        return { signatures: [] };
+    }
+    if (doc === undefined || root === undefined) {
+        return { signatures: [] };
+    }
+    const securities = findAll(root, NS.WSSE, 'Security');
+    const securitySignatures = new Set(securities.flatMap((security) => findAll(security, NS.DS, 'Signature')));
+    // Document order, and every `ds:Signature` — including one planted outside a `wsse:Security`
+    // header, which is reported as a failure rather than quietly ignored, because a wrapping
+    // payload the user cannot see is worse than one that reads as broken.
+    const signatures = findAll(root, NS.DS, 'Signature');
+    const trusted = truststoreCertificates(options.truststore);
+    const ids = idIndex(root);
+    const body = bodyElement(root);
+    const at = options.clock();
+    // A `ds:Signature` outside every `wsse:Security` header is never itself validated (see the
+    // early return below) — it is noise a wrapping attack planted to be picked up as content, not
+    // a signature this build ever trusts. Removing that noise once, up front, is not the isolation
+    // this code once did per signature (which stripped *every other* signature, including a
+    // legitimate sibling in the same `wsse:Security` header, corrupting the digest of any
+    // reference — such as an enveloped-signature transform over the header itself — that
+    // legitimately covered that sibling). A header signature is always verified against the
+    // document exactly as its Security header holds it; only content that could never have been
+    // part of a real signature's input is taken out first.
+    const headerSignatures = signatures.filter((signature) => securitySignatures.has(signature));
+    for (const signature of signatures) {
+        if (!securitySignatures.has(signature)) {
+            signature.parentNode?.removeChild(signature);
+        }
+    }
+    const sanitizedXml = serializeXml(doc);
+    const results = signatures.map((signature) => {
+        const empty = { references: [], referenceNames: [], coversBody: false, trusted: false };
+        if (!securitySignatures.has(signature)) {
+            return { ...empty, ok: false, error: 'A ds:Signature outside the wsse:Security header is not accepted.' };
+        }
+        const referenced = referenceIds(signature);
+        const duplicated = referenced.filter((id) => (ids.get(id)?.length ?? 0) > 1);
+        if (duplicated.length > 0) {
+            return {
+                ...empty,
+                ok: false,
+                references: referenced,
+                error: `duplicate-id: more than one element carries the referenced id "${duplicated[0] ?? ''}".`,
+            };
+        }
+        const certificate = certificateFromKeyInfo(ids, childElement(signature, NS.DS, 'KeyInfo'), trusted);
+        if (certificate === undefined) {
+            return {
+                ...empty,
+                ok: false,
+                error: 'The signing certificate could not be resolved from the message or the truststore.',
+            };
+        }
+        const certPem = forge.pki.certificateToPem(certificate);
+        // Verified by the signature's position among `wsse:Security` header signatures — never by
+        // isolating it from its own header siblings, which would change the bytes a signature whose
+        // own references cover the wsse:Security header (an enveloped-signature transform over a
+        // header that holds a second signature) was actually computed over.
+        const result = verifySignature(sanitizedXml, {
+            certPem,
+            signature: { index: headerSignatures.indexOf(signature) },
+        });
+        const covered = result.references.map((id) => uniqueById(ids, id));
+        return {
+            ok: result.ok,
+            references: result.references,
+            referenceNames: covered.map((element, index) => element?.localName ?? result.references[index] ?? ''),
+            coversBody: result.ok && body !== undefined && covered.includes(body),
+            signerSubject: renderDn(certificate.subject.attributes),
+            trusted: isTrusted(certificate, trusted, options.verifyChain, at),
+            ...(result.error !== undefined ? { error: result.error } : {}),
+        };
+    });
+    const timestamp = securities.map((security) => readTimestamp(security, options)).find((found) => found !== undefined);
+    return { signatures: results, ...(timestamp !== undefined ? { timestamp } : {}) };
+}

package/dist/wss/key-identifiers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The `<ds:KeyInfo>` content an outgoing signature carries: a `wsse:SecurityTokenReference`
+ * (or a bare `ds:X509Data`) pointing at the signing certificate in one of the five forms the
+ * X.509 token profile defines.
+ *
+ * These are produced as XML *strings* rather than DOM nodes because `xml-crypto` builds the
+ * whole `<ds:Signature>` element by string concatenation and asks for the KeyInfo contents the
+ * same way. Every element therefore declares the prefixes it uses on itself.
+ */
+import type { WssKeyIdentifierType } from './model.js';
+/** `ValueType`/`EncodingType` URIs from the WS-Security X.509 token profile. */
+export declare const WSS_TOKEN_TYPES: {
+    /** A single DER-encoded certificate. */
+    readonly X509V3: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3";
+    /** An ordered DER PKIPath of certificates. */
+    readonly X509_PKI_PATH_V1: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1";
+    /** The certificate's subject key identifier extension value. */
+    readonly X509_SUBJECT_KEY_IDENTIFIER: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier";
+    /** SHA-1 of the DER encoding of the certificate. */
+    readonly THUMBPRINT_SHA1: "http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1";
+    /** Base64 content encoding. */
+    readonly BASE64_BINARY: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary";
+};
+/** What every key-identifier builder needs about the signing certificate. */
+export interface KeyIdentifierInput {
+    /** The signing (leaf) certificate, PEM encoded. */
+    readonly certPem: string;
+    /** The issuing chain, nearest first; only used for `X509PKIPathv1`. */
+    readonly chainPem: readonly string[];
+    /** Emit only the leaf rather than the whole path. */
+    readonly useSingleCertificate: boolean;
+    /** The `wsu:Id` a `BinarySecurityToken` gets (and the `wsse:Reference` points at). */
+    readonly tokenId: string;
+}
+/** The KeyInfo content plus, for `BinarySecurityToken`, the token that must precede the signature. */
+export interface KeyIdentifier {
+    /** The XML that goes inside `<ds:KeyInfo>`. */
+    readonly keyInfoXml: string;
+    /** The `<wsse:BinarySecurityToken>` to insert into `wsse:Security`, when this form needs one. */
+    readonly binarySecurityTokenXml?: string;
+}
+/** The DER bytes of a PEM certificate. */
+export declare function certificateDer(certPem: string): Buffer;
+/** Base64 of the DER encoding of `certPem`, unwrapped (one line). */
+export declare function certificateBase64(certPem: string): string;
+/**
+ * Base64 of the DER `PKIPath` (an ASN.1 SEQUENCE OF Certificate) holding the leaf and its chain.
+ *
+ * @param certPems the certificates, leaf first
+ * @returns the base64 the `X509PKIPathv1` value type expects
+ */
+export declare function pkiPathBase64(certPems: readonly string[]): string;
+/** SHA-1 of the certificate's DER encoding, base64 encoded (the `ThumbprintSHA1` value). */
+export declare function thumbprintSha1Base64(certPem: string): string;
+/**
+ * The certificate's subject key identifier extension value, base64 encoded.
+ *
+ * @param certPem the certificate to read
+ * @returns the base64 `X509SubjectKeyIdentifier` value
+ * @throws WssError `wss-ski-missing` when the certificate carries no such extension
+ */
+export declare function subjectKeyIdentifierBase64(certPem: string): string;
+/** The certificate's issuer as an RFC 2253 distinguished name (most specific attribute first). */
+export declare function issuerDnRfc2253(certPem: string): string;
+/** The certificate's serial number in decimal, as `ds:X509SerialNumber` requires. */
+export declare function serialNumberDecimal(certPem: string): string;
+/**
+ * Builds the `ds:KeyInfo` content (and any `wsse:BinarySecurityToken`) for one key identifier
+ * form.
+ *
+ * @param type which of the five X.509 token profile forms to emit
+ * @param input the signing certificate, its chain and the token id to use
+ * @returns the KeyInfo XML, plus the binary security token when the form needs one
+ * @throws WssError `wss-ski-missing` for `SubjectKeyIdentifier` on a certificate without one
+ */
+export declare function buildKeyIdentifier(type: WssKeyIdentifierType, input: KeyIdentifierInput): KeyIdentifier;

package/dist/wss/key-identifiers.js

@@ -0,0 +1,139 @@
+/**
+ * The `<ds:KeyInfo>` content an outgoing signature carries: a `wsse:SecurityTokenReference`
+ * (or a bare `ds:X509Data`) pointing at the signing certificate in one of the five forms the
+ * X.509 token profile defines.
+ *
+ * These are produced as XML *strings* rather than DOM nodes because `xml-crypto` builds the
+ * whole `<ds:Signature>` element by string concatenation and asks for the KeyInfo contents the
+ * same way. Every element therefore declares the prefixes it uses on itself.
+ */
+import { createHash } from 'node:crypto';
+import forge from 'node-forge';
+import { WssError } from '../errors.js';
+import { NS } from '../xml/namespaces.js';
+import { renderDnRfc2253 } from './keystore/certificate.js';
+/** `ValueType`/`EncodingType` URIs from the WS-Security X.509 token profile. */
+export const WSS_TOKEN_TYPES = {
+    /** A single DER-encoded certificate. */
+    X509V3: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3',
+    /** An ordered DER PKIPath of certificates. */
+    X509_PKI_PATH_V1: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1',
+    /** The certificate's subject key identifier extension value. */
+    X509_SUBJECT_KEY_IDENTIFIER: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier',
+    /** SHA-1 of the DER encoding of the certificate. */
+    THUMBPRINT_SHA1: 'http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1',
+    /** Base64 content encoding. */
+    BASE64_BINARY: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary',
+};
+/** Escapes the five XML significant characters in attribute/text content. */
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/** The DER bytes of a PEM certificate. */
+export function certificateDer(certPem) {
+    const der = forge.asn1.toDer(forge.pki.certificateToAsn1(forge.pki.certificateFromPem(certPem))).getBytes();
+    return Buffer.from(der, 'binary');
+}
+/** Base64 of the DER encoding of `certPem`, unwrapped (one line). */
+export function certificateBase64(certPem) {
+    return certificateDer(certPem).toString('base64');
+}
+/**
+ * Base64 of the DER `PKIPath` (an ASN.1 SEQUENCE OF Certificate) holding the leaf and its chain.
+ *
+ * @param certPems the certificates, leaf first
+ * @returns the base64 the `X509PKIPathv1` value type expects
+ */
+export function pkiPathBase64(certPems) {
+    const certificates = certPems.map((pem) => forge.pki.certificateToAsn1(forge.pki.certificateFromPem(pem)));
+    const sequence = forge.asn1.create(forge.asn1.Class.UNIVERSAL, forge.asn1.Type.SEQUENCE, true, certificates);
+    return Buffer.from(forge.asn1.toDer(sequence).getBytes(), 'binary').toString('base64');
+}
+/** SHA-1 of the certificate's DER encoding, base64 encoded (the `ThumbprintSHA1` value). */
+export function thumbprintSha1Base64(certPem) {
+    return createHash('sha1').update(certificateDer(certPem)).digest('base64');
+}
+/**
+ * The certificate's subject key identifier extension value, base64 encoded.
+ *
+ * @param certPem the certificate to read
+ * @returns the base64 `X509SubjectKeyIdentifier` value
+ * @throws WssError `wss-ski-missing` when the certificate carries no such extension
+ */
+export function subjectKeyIdentifierBase64(certPem) {
+    const cert = forge.pki.certificateFromPem(certPem);
+    const extension = cert.extensions.find((candidate) => candidate.name === 'subjectKeyIdentifier' || candidate.id === '2.5.29.14');
+    const hex = extension?.subjectKeyIdentifier;
+    if (typeof hex !== 'string' || hex.length === 0) {
+        throw new WssError('wss-ski-missing', 'The signing certificate has no Subject Key Identifier extension; choose another key identifier type.');
+    }
+    return Buffer.from(hex, 'hex').toString('base64');
+}
+/** The certificate's issuer as an RFC 2253 distinguished name (most specific attribute first). */
+export function issuerDnRfc2253(certPem) {
+    const cert = forge.pki.certificateFromPem(certPem);
+    return renderDnRfc2253(cert.issuer.attributes);
+}
+/** The certificate's serial number in decimal, as `ds:X509SerialNumber` requires. */
+export function serialNumberDecimal(certPem) {
+    const cert = forge.pki.certificateFromPem(certPem);
+    return BigInt(`0x${cert.serialNumber}`).toString(10);
+}
+/** Opens a `wsse:SecurityTokenReference`, declaring both WS-Security prefixes on itself. */
+function securityTokenReference(inner) {
+    return `<wsse:SecurityTokenReference xmlns:wsse="${NS.WSSE}" xmlns:wsu="${NS.WSU}">${inner}</wsse:SecurityTokenReference>`;
+}
+/** A `<wsse:KeyIdentifier>` carrying base64 content of the given value type. */
+function keyIdentifierElement(valueType, value) {
+    return (`<wsse:KeyIdentifier ValueType="${valueType}" EncodingType="${WSS_TOKEN_TYPES.BASE64_BINARY}">` +
+        `${value}</wsse:KeyIdentifier>`);
+}
+/**
+ * Builds the `ds:KeyInfo` content (and any `wsse:BinarySecurityToken`) for one key identifier
+ * form.
+ *
+ * @param type which of the five X.509 token profile forms to emit
+ * @param input the signing certificate, its chain and the token id to use
+ * @returns the KeyInfo XML, plus the binary security token when the form needs one
+ * @throws WssError `wss-ski-missing` for `SubjectKeyIdentifier` on a certificate without one
+ */
+export function buildKeyIdentifier(type, input) {
+    switch (type) {
+        case 'BinarySecurityToken': {
+            const valueType = input.useSingleCertificate ? WSS_TOKEN_TYPES.X509V3 : WSS_TOKEN_TYPES.X509_PKI_PATH_V1;
+            const value = input.useSingleCertificate
+                ? certificateBase64(input.certPem)
+                : pkiPathBase64([input.certPem, ...input.chainPem]);
+            return {
+                keyInfoXml: securityTokenReference(`<wsse:Reference URI="#${input.tokenId}" ValueType="${valueType}"/>`),
+                binarySecurityTokenXml: `<wsse:BinarySecurityToken xmlns:wsse="${NS.WSSE}" xmlns:wsu="${NS.WSU}" ` +
+                    `wsu:Id="${input.tokenId}" EncodingType="${WSS_TOKEN_TYPES.BASE64_BINARY}" ` +
+                    `ValueType="${valueType}">${value}</wsse:BinarySecurityToken>`,
+            };
+        }
+        case 'IssuerSerial':
+            return {
+                keyInfoXml: `<ds:X509Data xmlns:ds="${NS.DS}"><ds:X509IssuerSerial>` +
+                    `<ds:X509IssuerName>${escapeXml(issuerDnRfc2253(input.certPem))}</ds:X509IssuerName>` +
+                    `<ds:X509SerialNumber>${serialNumberDecimal(input.certPem)}</ds:X509SerialNumber>` +
+                    `</ds:X509IssuerSerial></ds:X509Data>`,
+            };
+        case 'SubjectKeyIdentifier':
+            return {
+                keyInfoXml: securityTokenReference(keyIdentifierElement(WSS_TOKEN_TYPES.X509_SUBJECT_KEY_IDENTIFIER, subjectKeyIdentifierBase64(input.certPem))),
+            };
+        case 'X509KeyIdentifier':
+            return {
+                keyInfoXml: securityTokenReference(keyIdentifierElement(WSS_TOKEN_TYPES.X509V3, certificateBase64(input.certPem))),
+            };
+        case 'Thumbprint':
+            return {
+                keyInfoXml: securityTokenReference(keyIdentifierElement(WSS_TOKEN_TYPES.THUMBPRINT_SHA1, thumbprintSha1Base64(input.certPem))),
+            };
+    }
+}