Stateful hash-based signatures: LMS and XMSS

Stateful hash-based signature VERIFICATION: HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST SP 800-208. Verify only. Each one-time key must be used exactly once, so the private key embeds a monotonic index whose state must advance and persist atomically across every signature and every process restart. A single index reuse (a restored VM snapshot, a crashed writer, a concurrent signer) forfeits security and can leak enough one-time-key material to forge, which is why SP 800-208 sec. 8 constrains signing-state handling to hardware. So this module never mints a signature; it verifies signatures produced in an HSM elsewhere. Verification is pure public-input SHA-256 / SHAKE256 hashing (no secret, no side-channel surface), so a pure-JavaScript verifier is safe.

pki.shbs.verify

since 0.2.1 stable
pki.shbs.verify(publicKey, message, signature) -> boolean

Verify an HSS (Hierarchical Signature System) signature over message under publicKey, the wire form RFC 9802 (X.509) and RFC 9708 (CMS) carry for id-alg-hss-lms-hashsig. The public key and signature are the raw HSS octet blobs the certificate / CMS parsers already surface (no ASN.1 wrapping). Every level of the hierarchy must verify: a single failing level yields false. Returns true for a valid signature, false for a well-formed signature that does not verify; a malformed blob (bad length, unknown or unapproved typecode, truncation, a typecode disagreeing between the key and the signature) throws a typed ShbsError. Verification only: this module never signs.

Example

async function example() {
  // throws: shbs/bad-public-key -- an Ed25519 key is not an HSS public key, and
  // the verifier fails closed on the wrong key type rather than returning true
  var pair = await pki.key.generate("Ed25519");
  var der = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
    notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
    { key: await pki.key.export(pair.privateKey) });
  var cert = pki.schema.x509.parse(der);
  var ok = pki.shbs.verify(cert.subjectPublicKeyInfo.publicKey.bytes,
                           cert.tbsBytes, cert.signatureValue.bytes);
}
example();

See also: pki.shbs.verifyLms

References

pki.shbs.verifyLms

since 0.2.1 stable
pki.shbs.verifyLms(publicKey, message, signature) -> boolean

Verify a single-tree LMS (Leighton-Micali Signature) over message: the component an HSS hierarchy composes at each level, and a standalone algorithm in its own right. Same verdict contract as pki.shbs.verify: true / false for a well-formed signature, a typed ShbsError for a malformed blob.

Example

// throws: shbs/unsupported-parameter-set -- lmsPublicKey / lmsSignature are raw
// LMS blobs (an HSS level, or a bare LMS-signed artifact); arbitrary bytes carry
// no recognized LMS typecode, so the verifier refuses them instead of returning
var bytes = Buffer.alloc(64);
var ok = pki.shbs.verifyLms(bytes, bytes, bytes);

See also: pki.shbs.verify

References