pq-key-fingerprint

Generate stable fingerprints (cryptographic hashes) of PQ public keys. Accepts keys in any encoding that pq-key-encoder produces, plus raw bytes.

Audit status: This package has not yet been independently audited. A security audit is pending — see Security policy.

Installation

npm install pq-key-fingerprint

Usage

import {
  FingerprintError,
  fingerprintJWK,
  fingerprintPEM,
  fingerprintPublicKey,
  fingerprintPublicKeyBytes,
  fingerprintSPKI,
} from 'pq-key-fingerprint';

const mlKem512PublicKey = new Uint8Array(800);

// 1) Raw bytes + algorithm
const fromBytes = await fingerprintPublicKeyBytes(mlKem512PublicKey, 'ML-KEM-512');
// hex string by default

// 2) KeyData-like input
const fromPublicKeyObject = await fingerprintPublicKey({
  alg: 'ML-KEM-512',
  type: 'public',
  bytes: mlKem512PublicKey,
});

// 3) SPKI DER bytes
const spkiDer = new Uint8Array(/* SPKI DER bytes */);
const fromSpki = await fingerprintSPKI(spkiDer);

// 4) PEM
const pem = `-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----`;
const fromPem = await fingerprintPEM(pem);

// 5) JWK
const jwk = {
  kty: 'PQC' as const,
  alg: 'ML-KEM-512' as const,
  x: 'base64url-encoded-public-key-bytes',
};
const fromJwk = await fingerprintJWK(jwk);

Digest and encoding options

const sha512Base64Url = await fingerprintPublicKeyBytes(
  mlKem512PublicKey,
  'ML-KEM-512',
  { digest: 'SHA-512', encoding: 'base64url' },
);

const rawDigestBytes = await fingerprintPublicKeyBytes(
  mlKem512PublicKey,
  'ML-KEM-512',
  { digest: 'SHA-384', encoding: 'bytes' },
);

Option	Values
digest	'SHA-256' (default), 'SHA-384', 'SHA-512'
encoding	'hex' (default), 'base64url', 'bytes'

Error handling

All fingerprint functions throw FingerprintError for malformed inputs (invalid PEM, unsupported algorithm, wrong key length for the declared algorithm):

try {
  await fingerprintPEM('not-a-valid-pem');
} catch (error) {
  if (error instanceof FingerprintError) {
    console.error('Fingerprint failed:', error.message);
  } else {
    throw error;
  }
}