pq_crypto 0.3.2 → 0.5.0

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/verify.h

@@ -0,0 +1,464 @@
+/*
+ * Copyright (c) The mlkem-native project authors
+ * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+ */
+
+/* References
+ * ==========
+ *
+ * - [FIPS203]
+ *   FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/203/final
+ *
+ * - [REF]
+ *   CRYSTALS-Kyber C reference implementation
+ *   Bos, Ducas, Kiltz, Lepoint, Lyubashevsky, Schanck, Schwabe, Seiler, Stehlé
+ *   https://github.com/pq-crystals/kyber/tree/main/ref
+ *
+ * - [libmceliece]
+ *   libmceliece implementation of Classic McEliece
+ *   Bernstein, Chou
+ *   https://lib.mceliece.org/
+ *
+ * - [optblocker]
+ *   PQC forum post on opt-blockers using volatile globals
+ *   Daniel J. Bernstein
+ *   https://groups.google.com/a/list.nist.gov/g/pqc-forum/c/hqbtIGFKIpU/m/H14H0wOlBgAJ
+ */
+
+#ifndef MLK_VERIFY_H
+#define MLK_VERIFY_H
+
+
+#include "cbmc.h"
+#include "common.h"
+
+/* Constant-time comparisons and conditional operations
+
+   We reduce the risk for compilation into variable-time code
+   through the use of 'value barriers'.
+
+   Functionally, a value barrier is a no-op. To the compiler, however,
+   it constitutes an arbitrary modification of its input, and therefore
+   harden's value propagation and range analysis.
+
+   We consider two approaches to implement a value barrier:
+   - An empty inline asm block which marks the target value as clobbered.
+   - XOR'ing with the value of a volatile global that's set to 0;
+     see @[optblocker] for a discussion of this idea, and
+     @[libmceliece, inttypes/crypto_intN.h] for an implementation.
+
+   The first approach is cheap because it only prevents the compiler
+   from reasoning about the value of the variable past the barrier,
+   but does not directly generate additional instructions.
+
+   The second approach generates redundant loads and XOR operations
+   and therefore comes at a higher runtime cost. However, it appears
+   more robust towards optimization, as compilers should never drop
+   a volatile load.
+
+   We use the empty-ASM value barrier for GCC and clang, and fall
+   back to the global volatile barrier otherwise.
+
+   The global value barrier can be forced by setting
+   MLK_CONFIG_NO_ASM_VALUE_BARRIER.
+
+*/
+
+#if defined(MLK_HAVE_INLINE_ASM) && !defined(MLK_CONFIG_NO_ASM_VALUE_BARRIER)
+#define MLK_USE_ASM_VALUE_BARRIER
+#endif
+
+#if !defined(MLK_USE_ASM_VALUE_BARRIER)
+
+/*
+ * Declaration of global volatile that the global value barrier
+ * is loading from and masking with.
+ */
+#define mlk_ct_opt_blocker_u64 MLK_NAMESPACE(ct_opt_blocker_u64)
+extern volatile uint64_t mlk_ct_opt_blocker_u64;
+
+/* Helper functions for obtaining global masks of various sizes */
+
+/* This contract is not proved but treated as an axiom.
+ *
+ * Its validity relies on the assumption that the global opt-blocker
+ * constant mlk_ct_opt_blocker_u64 is not modified.
+ */
+static MLK_INLINE uint64_t mlk_ct_get_optblocker_u64(void)
+__contract__(ensures(return_value == 0)) { return mlk_ct_opt_blocker_u64; }
+
+static MLK_INLINE uint8_t mlk_ct_get_optblocker_u8(void)
+__contract__(ensures(return_value == 0)) { return (uint8_t)mlk_ct_get_optblocker_u64(); }
+
+static MLK_INLINE uint32_t mlk_ct_get_optblocker_u32(void)
+__contract__(ensures(return_value == 0)) { return (uint32_t)mlk_ct_get_optblocker_u64(); }
+
+static MLK_INLINE int32_t mlk_ct_get_optblocker_i32(void)
+__contract__(ensures(return_value == 0)) { return (int32_t)mlk_ct_get_optblocker_u64(); }
+
+/* Opt-blocker based implementation of value barriers */
+static MLK_INLINE uint32_t mlk_value_barrier_u32(uint32_t b)
+__contract__(ensures(return_value == b)) { return (b ^ mlk_ct_get_optblocker_u32()); }
+
+static MLK_INLINE int32_t mlk_value_barrier_i32(int32_t b)
+__contract__(ensures(return_value == b)) { return (b ^ mlk_ct_get_optblocker_i32()); }
+
+static MLK_INLINE uint8_t mlk_value_barrier_u8(uint8_t b)
+__contract__(ensures(return_value == b)) { return (b ^ mlk_ct_get_optblocker_u8()); }
+
+#else /* !MLK_USE_ASM_VALUE_BARRIER */
+
+static MLK_INLINE uint32_t mlk_value_barrier_u32(uint32_t b)
+__contract__(ensures(return_value == b))
+{
+  __asm__ volatile("" : "+r"(b));
+  return b;
+}
+
+static MLK_INLINE int32_t mlk_value_barrier_i32(int32_t b)
+__contract__(ensures(return_value == b))
+{
+  __asm__ volatile("" : "+r"(b));
+  return b;
+}
+
+static MLK_INLINE uint8_t mlk_value_barrier_u8(uint8_t b)
+__contract__(ensures(return_value == b))
+{
+  __asm__ volatile("" : "+r"(b));
+  return b;
+}
+
+#endif /* MLK_USE_ASM_VALUE_BARRIER */
+
+#ifdef CBMC
+#pragma CPROVER check push
+#pragma CPROVER check disable "conversion"
+#endif
+/*************************************************
+ * Name:        mlk_cast_uint16_to_int16
+ *
+ * Description: Cast uint16 value to int16
+ *
+ * Returns:     For uint16_t x, the unique y in int16_t
+ *              so that x == y mod 2^16.
+ *
+ *              Concretely:
+ *              - x <  32768: returns x
+ *              - x >= 32768: returns x - 65536
+ *
+ **************************************************/
+static MLK_ALWAYS_INLINE int16_t mlk_cast_uint16_to_int16(uint16_t x)
+{
+  /*
+   * PORTABILITY: This relies on uint16_t -> int16_t
+   * being implemented as the inverse of int16_t -> uint16_t,
+   * which is implementation-defined (C99 6.3.1.3 (3))
+   * CBMC (correctly) fails to prove this conversion is OK,
+   * so we have to suppress that check here
+   */
+  return (int16_t)x;
+}
+#ifdef CBMC
+#pragma CPROVER check pop
+#endif
+
+/*************************************************
+ * Name:        mlk_cast_int32_to_uint16
+ *
+ * Description: Cast int32 value to uint16 as per C standard.
+ *
+ * Returns:     For int32_t x, the unique y in uint16_t
+ *              so that x == y mod 2^16.
+ **************************************************/
+static MLK_ALWAYS_INLINE uint16_t mlk_cast_int32_to_uint16(int32_t x)
+{
+  return (uint16_t)(x & (int32_t)UINT16_MAX);
+}
+
+/*************************************************
+ * Name:        mlk_cast_int16_to_uint16
+ *
+ * Description: Cast int16 value to uint16 as per C standard.
+ *
+ * Returns:     For int16_t x, the unique y in uint16_t
+ *              so that x == y mod 2^16.
+ **************************************************/
+static MLK_ALWAYS_INLINE uint16_t mlk_cast_int16_to_uint16(int32_t x)
+{
+  return mlk_cast_int32_to_uint16((int32_t)x);
+}
+
+/*************************************************
+ * Name:        mlk_ct_cmask_neg_i16
+ *
+ * Description: Return 0 if input is non-negative, and -1 otherwise.
+ *
+ * Arguments:   uint16_t x: Value to be converted into a mask
+ *
+ **************************************************/
+
+/* Reference: Embedded in polynomial compression function in the
+ *            reference implementation @[REF].
+ *            - Used as part of signed->unsigned conversion for modular
+ *              representatives to detect whether the input is negative.
+ *              This happen in `mlk_poly_reduce()` here, and as part of
+ *              polynomial compression functions in the reference
+ *              implementation. See `mlk_poly_reduce()`.
+ *            - We use value barriers to reduce the risk of
+ *              compiler-introduced branches. */
+static MLK_INLINE uint16_t mlk_ct_cmask_neg_i16(int16_t x)
+__contract__(ensures(return_value == ((x < 0) ? 0xFFFF : 0)))
+{
+  int32_t tmp = mlk_value_barrier_i32((int32_t)x);
+  tmp >>= 16;
+  return mlk_cast_int32_to_uint16(tmp);
+}
+
+/*************************************************
+ * Name:        mlk_ct_cmask_nonzero_u16
+ *
+ * Description: Return 0 if input is zero, and -1 otherwise.
+ *
+ * Arguments:   uint16_t x: Value to be converted into a mask
+ *
+ **************************************************/
+
+/* Reference: Embedded in `cmov_int16()` in the reference implementation @[REF].
+ *            - Use value barrier and shift instead of `b = -b` to
+ *              convert condition into mask. */
+static MLK_INLINE uint16_t mlk_ct_cmask_nonzero_u16(uint16_t x)
+__contract__(ensures(return_value == ((x == 0) ? 0 : 0xFFFF)))
+{
+  int32_t tmp = mlk_value_barrier_i32(-((int32_t)x));
+  tmp >>= 16;
+  return mlk_cast_int32_to_uint16(tmp);
+}
+
+/*************************************************
+ * Name:        mlk_ct_cmask_nonzero_u8
+ *
+ * Description: Return 0 if input is zero, and -1 otherwise.
+ *
+ * Arguments:   uint8_t x: Value to be converted into a mask
+ *
+ **************************************************/
+
+/* Reference: Embedded in `verify()` and `cmov()` in the
+ *            reference implementation @[REF].
+ *            - We include a value barrier not present in the
+ *              reference implementation, to prevent the compiler
+ *              from realizing that this function returns a mask. */
+static MLK_INLINE uint8_t mlk_ct_cmask_nonzero_u8(uint8_t x)
+__contract__(ensures(return_value == ((x == 0) ? 0 : 0xFF)))
+{
+  uint16_t mask = mlk_ct_cmask_nonzero_u16((uint16_t)x);
+  return (uint8_t)(mask & 0xFF);
+}
+
+/*************************************************
+ * Name:        mlk_ct_sel_int16
+ *
+ * Description: Functionally equivalent to cond ? a : b,
+ *              but implemented with guards against
+ *              compiler-introduced branches.
+ *
+ * Arguments:   int16_t a:       First alternative
+ *              int16_t b:       Second alternative
+ *              uint16_t cond:   Condition variable.
+ *
+ * Specification:
+ * - With `a = MLKEM_Q_HALF` and `b=0`, this essentially
+ *   implements `Decompress_1` @[FIPS203, Eq (4.8)] in `mlk_poly_frommsg()`.
+ * - With `a = x + MLKEM_Q`, `b = x`, and `cond` indicating whether `x`
+ *   is negative, implements signed->unsigned conversion of modular
+ *   representatives. Questions of representation are not considered
+ *   in the specification @[FIPS203, Section 2.4.1, "The pseudocode is
+ *   agnostic regarding how an integer modulo 𝑚 is represented in
+ *   actual implementations"].
+ *
+ **************************************************/
+
+/* Reference: Embedded in polynomial compression function in the
+ *            reference implementation @[REF].
+ *            - Used as part of signed->unsigned conversion for modular
+ *              representatives. This happen in `mlk_poly_reduce()` here,
+ *              and as part of polynomial compression functions in @[REF].
+ *              See `mlk_poly_reduce()`.
+ *            - Barrier to reduce the risk of compiler-introduced branches.
+ *            For `a = MLKEM_Q_HALF` and `b=0`, also embedded in
+ *            `poly_frommsg()` from the reference implementation, which uses
+ *            `cmov_int16()` instead. */
+static MLK_INLINE int16_t mlk_ct_sel_int16(int16_t a, int16_t b, uint16_t cond)
+__contract__(ensures(return_value == (cond ? a : b)))
+{
+  uint16_t au = mlk_cast_int16_to_uint16(a);
+  uint16_t bu = mlk_cast_int16_to_uint16(b);
+  uint16_t res = bu ^ (mlk_ct_cmask_nonzero_u16(cond) & (au ^ bu));
+  return mlk_cast_uint16_to_int16(res);
+}
+
+/*************************************************
+ * Name:        mlk_ct_sel_uint8
+ *
+ * Description: Functionally equivalent to cond ? a : b,
+ *              but implemented with guards against
+ *              compiler-introduced branches.
+ *
+ * Arguments:   uint8_t a:       First alternative
+ *              uint8_t b:       Second alternative
+ *              uuint8_t cond:   Condition variable.
+ *
+ **************************************************/
+
+/* Reference: Embedded into `cmov()` in the reference implementation @[REF].
+ *            - Use value barrier to get mask from condition value. */
+static MLK_INLINE uint8_t mlk_ct_sel_uint8(uint8_t a, uint8_t b, uint8_t cond)
+__contract__(ensures(return_value == (cond ? a : b)))
+{
+  return b ^ (mlk_ct_cmask_nonzero_u8(cond) & (a ^ b));
+}
+
+/*************************************************
+ * Name:        mlk_ct_memcmp
+ *
+ * Description: Compare two arrays for equality in constant time.
+ *
+ * Arguments:   const uint8_t *a: pointer to first byte array
+ *              const uint8_t *b: pointer to second byte array
+ *              size_t len:       length of the byte arrays, upper-bounded
+ *                                to UINT16_MAX to control proof complexity
+ *                                only.
+ *
+ * Returns 0 if the byte arrays are equal, 0xFF otherwise.
+ *
+ * Specification:
+ * - Used to securely compute conditional move in
+ *   @[FIPS203, Algorithm 18 (ML-KEM.Decaps_Internal, L9-11]
+ *
+ **************************************************/
+
+/* Reference: `cmov()` in the reference implementation @[REF]
+ *            - We return `uint8_t`, not `int`.
+ *            - We use an additional XOR-accumulator in the comparison loop
+ *              which prevents early abort if the OR-accumulator is 0xFF.
+ *            - We use a value barrier to convert the OR-accumulator into
+ *              a mask. The reference implementation uses a shift which the
+ *              compiler can argue to result in either 0 of 0xFF..FF. */
+static MLK_INLINE uint8_t mlk_ct_memcmp(const uint8_t *a, const uint8_t *b,
+                                        const size_t len)
+__contract__(
+  requires(len <= UINT16_MAX)
+  requires(memory_no_alias(a, len))
+  requires(memory_no_alias(b, len))
+  ensures((return_value == 0) || (return_value == 0xFF))
+  ensures((return_value == 0) == forall(i, 0, len, (a[i] == b[i]))))
+{
+  uint8_t r = 0, s = 0;
+  unsigned i;
+
+  for (i = 0; i < len; i++)
+  __loop__(
+    invariant(i <= len)
+    invariant((r == 0) == (forall(k, 0, i, (a[k] == b[k])))))
+  {
+    r |= a[i] ^ b[i];
+    /* s is useless, but prevents the loop from being aborted once r=0xff. */
+    s ^= a[i] ^ b[i];
+  }
+
+  /*
+   * - Convert r into a mask; this may not be necessary, but is an additional
+   *   safeguard
+   *   towards leaking information about a and b.
+   * - XOR twice with s, separated by a value barrier, to prevent the compile
+   *   from dropping the s computation in the loop.
+   */
+  return (mlk_value_barrier_u8(mlk_ct_cmask_nonzero_u8(r) ^ s) ^ s);
+}
+
+/*************************************************
+ * Name:        mlk_ct_cmov_zero
+ *
+ * Description: Copy len bytes from x to r if b is zero;
+ *              don't modify x if b is non-zero.
+ *              assumes two's complement representation of negative integers.
+ *              Runs in constant time.
+ *
+ * Arguments:   uint8_t *r:       pointer to output byte array
+ *              const uint8_t *x: pointer to input byte array
+ *              size_t len:       Amount of bytes to be copied
+ *              uint8_t b:        Condition value.
+ *
+ * Specification:
+ * - Used to securely compute conditional move in
+ *   @[FIPS203, Algorithm 18 (ML-KEM.Decaps_Internal, L9-11]
+ *
+ **************************************************/
+
+/* Reference: `cmov()` in the reference implementation @[REF].
+ *            - We move if condition value is `0`, not `1`.
+ *            - We use `mlk_ct_sel_uint8` for constant-time selection. */
+static MLK_INLINE void mlk_ct_cmov_zero(uint8_t *r, const uint8_t *x,
+                                        size_t len, uint8_t b)
+__contract__(
+  requires(len <= MLK_MAX_BUFFER_SIZE)
+  requires(memory_no_alias(r, len))
+  requires(memory_no_alias(x, len))
+  assigns(memory_slice(r, len))
+  ensures(forall(i, 0, len, (r[i] == (b == 0 ? x[i] : old(r)[i])))))
+{
+  size_t i;
+  for (i = 0; i < len; i++)
+  __loop__(
+    invariant(i <= len)
+    invariant(forall(k, 0, i, r[k] == (b == 0 ? x[k] : loop_entry(r)[k]))))
+  {
+    r[i] = mlk_ct_sel_uint8(r[i], x[i], b);
+  }
+}
+
+/*************************************************
+ * Name:        mlk_zeroize
+ *
+ * Description: Force-zeroize a buffer.
+ *
+ * Arguments:   uint8_t *r:       pointer to byte array to be zeroed
+ *              size_t len:       Amount of bytes to be zeroed
+ *
+ * Specification: Used to implement
+ * @[FIPS203, Section 3.3, Destruction of intermediate values]
+ *
+ **************************************************/
+
+/* Reference: Not present in the reference implementation @[REF]. */
+#if !defined(MLK_CONFIG_CUSTOM_ZEROIZE)
+#if defined(MLK_SYS_WINDOWS)
+#include <windows.h>
+static MLK_INLINE void mlk_zeroize(void *ptr, size_t len)
+__contract__(
+  requires(memory_no_alias(ptr, len))
+  assigns(memory_slice(ptr, len))) { SecureZeroMemory(ptr, len); }
+#elif defined(MLK_HAVE_INLINE_ASM)
+#include <string.h>
+static MLK_INLINE void mlk_zeroize(void *ptr, size_t len)
+__contract__(
+  requires(memory_no_alias(ptr, len))
+  assigns(memory_slice(ptr, len)))
+{
+  mlk_memset(ptr, 0, len);
+  /* This follows OpenSSL and seems sufficient to prevent the compiler
+   * from optimizing away the memset.
+   *
+   * If there was a reliable way to detect availability of memset_s(),
+   * that would be preferred. */
+  __asm__ volatile("" : : "r"(ptr) : "memory");
+}
+#else /* !MLK_SYS_WINDOWS && MLK_HAVE_INLINE_ASM */
+#error No plausibly-secure implementation of mlk_zeroize available. Please provide your own using MLK_CONFIG_CUSTOM_ZEROIZE.
+#endif /* !MLK_SYS_WINDOWS && !MLK_HAVE_INLINE_ASM */
+#endif /* !MLK_CONFIG_CUSTOM_ZEROIZE */
+
+#endif /* !MLK_VERIFY_H */

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/zetas.inc

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) The mlkem-native project authors
+ * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+ */
+
+/*
+ * WARNING: This file is auto-generated from scripts/autogen
+ *          in the mlkem-native repository.
+ *          Do not modify it directly.
+ */
+
+
+/*
+ * Table of zeta values used in the reference NTT and inverse NTT.
+ * See autogen for details.
+ */
+static MLK_ALIGN const int16_t mlk_zetas[128] = {
+    -1044, -758,  -359,  -1517, 1493,  1422,  287,   202,  -171,  622,   1577,
+    182,   962,   -1202, -1474, 1468,  573,   -1325, 264,  383,   -829,  1458,
+    -1602, -130,  -681,  1017,  732,   608,   -1542, 411,  -205,  -1571, 1223,
+    652,   -552,  1015,  -1293, 1491,  -282,  -1544, 516,  -8,    -320,  -666,
+    -1618, -1162, 126,   1469,  -853,  -90,   -271,  830,  107,   -1421, -247,
+    -951,  -398,  961,   -1508, -725,  448,   -1065, 677,  -1275, -1103, 430,
+    555,   843,   -1251, 871,   1550,  105,   422,   587,  177,   -235,  -291,
+    -460,  1574,  1653,  -246,  778,   1159,  -147,  -777, 1483,  -602,  1119,
+    -1590, 644,   -872,  349,   418,   329,   -156,  -75,  817,   1097,  603,
+    610,   1322,  -1285, -1465, 384,   -1215, -136,  1218, -1335, -874,  220,
+    -1187, -1659, -1185, -1530, -1278, 794,   -1510, -854, -870,  478,   -108,
+    -308,  996,   991,   958,   -1460, 1522,  1628,
+};

data/lib/pq_crypto/algorithm_registry.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module AlgorithmRegistry
+    class << self
+      def entries
+        @entries ||= begin
+          {
+            ml_kem_512: {
+              family: :ml_kem,
+              legacy_oid: nil,
+              standard_oid: "2.16.840.1.101.3.4.4.1",
+              public_key_bytes: PQCrypto::ML_KEM_512_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::ML_KEM_512_SECRET_KEY_BYTES,
+              ciphertext_bytes: PQCrypto::ML_KEM_512_CIPHERTEXT_BYTES,
+              shared_secret_bytes: PQCrypto::ML_KEM_512_SHARED_SECRET_BYTES,
+              signature_bytes: nil,
+              description: "Pure ML-KEM-512 primitive (FIPS 203).",
+            }.freeze,
+            ml_kem_768: {
+              family: :ml_kem,
+              legacy_oid: "2.25.186599352125448088867056807454444238446",
+              standard_oid: "2.16.840.1.101.3.4.4.2",
+              public_key_bytes: PQCrypto::ML_KEM_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::ML_KEM_SECRET_KEY_BYTES,
+              ciphertext_bytes: PQCrypto::ML_KEM_CIPHERTEXT_BYTES,
+              shared_secret_bytes: PQCrypto::ML_KEM_SHARED_SECRET_BYTES,
+              signature_bytes: nil,
+              description: "Pure ML-KEM-768 primitive (FIPS 203).",
+            }.freeze,
+            ml_kem_1024: {
+              family: :ml_kem,
+              legacy_oid: nil,
+              standard_oid: "2.16.840.1.101.3.4.4.3",
+              public_key_bytes: PQCrypto::ML_KEM_1024_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::ML_KEM_1024_SECRET_KEY_BYTES,
+              ciphertext_bytes: PQCrypto::ML_KEM_1024_CIPHERTEXT_BYTES,
+              shared_secret_bytes: PQCrypto::ML_KEM_1024_SHARED_SECRET_BYTES,
+              signature_bytes: nil,
+              description: "Pure ML-KEM-1024 primitive (FIPS 203).",
+            }.freeze,
+            ml_kem_768_x25519_xwing: {
+              family: :ml_kem_hybrid,
+              legacy_oid: "1.3.6.1.4.1.62253.25722",
+              standard_oid: nil,
+              public_key_bytes: PQCrypto::HYBRID_KEM_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::HYBRID_KEM_SECRET_KEY_BYTES,
+              ciphertext_bytes: PQCrypto::HYBRID_KEM_CIPHERTEXT_BYTES,
+              shared_secret_bytes: PQCrypto::HYBRID_KEM_SHARED_SECRET_BYTES,
+              signature_bytes: nil,
+              description: "Hybrid KEM: ML-KEM-768 + X25519 combined via X-Wing SHA3-256 combiner (draft-connolly-cfrg-xwing-kem).",
+            }.freeze,
+            ml_dsa_44: {
+              family: :ml_dsa,
+              legacy_oid: nil,
+              standard_oid: "2.16.840.1.101.3.4.3.17",
+              public_key_bytes: PQCrypto::SIGN_44_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::SIGN_44_SECRET_KEY_BYTES,
+              ciphertext_bytes: nil,
+              shared_secret_bytes: nil,
+              signature_bytes: PQCrypto::SIGN_44_BYTES,
+              description: "ML-DSA-44 signature primitive (FIPS 204).",
+            }.freeze,
+            ml_dsa_65: {
+              family: :ml_dsa,
+              legacy_oid: "2.25.305232938483772195555080795650659207792",
+              standard_oid: "2.16.840.1.101.3.4.3.18",
+              public_key_bytes: PQCrypto::SIGN_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::SIGN_SECRET_KEY_BYTES,
+              ciphertext_bytes: nil,
+              shared_secret_bytes: nil,
+              signature_bytes: PQCrypto::SIGN_BYTES,
+              description: "ML-DSA-65 signature primitive (FIPS 204).",
+            }.freeze,
+            ml_dsa_87: {
+              family: :ml_dsa,
+              legacy_oid: nil,
+              standard_oid: "2.16.840.1.101.3.4.3.19",
+              public_key_bytes: PQCrypto::SIGN_87_PUBLIC_KEY_BYTES,
+              secret_key_bytes: PQCrypto::SIGN_87_SECRET_KEY_BYTES,
+              ciphertext_bytes: nil,
+              shared_secret_bytes: nil,
+              signature_bytes: PQCrypto::SIGN_87_BYTES,
+              description: "ML-DSA-87 signature primitive (FIPS 204).",
+            }.freeze,
+          }.freeze
+        end
+      end
+
+      def fetch(symbol)
+        entries.fetch(symbol) do
+          raise UnsupportedAlgorithmError, "Unsupported algorithm: #{symbol.inspect}"
+        end
+      end
+
+      def legacy_oid(symbol)
+        fetch(symbol).fetch(:legacy_oid)
+      end
+
+      def standard_oid(symbol)
+        oid = fetch(symbol).fetch(:standard_oid)
+        raise SerializationError, "No standard OID registered for #{symbol.inspect}" if oid.nil?
+
+        oid
+      end
+
+      def by_legacy_oid(oid)
+        legacy_oid_index.fetch(oid, nil)
+      end
+
+      def by_standard_oid(oid)
+        standard_oid_index.fetch(oid, nil)
+      end
+
+      def supported_kems
+        supported_by_family(:ml_kem)
+      end
+
+      def supported_hybrid_kems
+        supported_by_family(:ml_kem_hybrid)
+      end
+
+      def supported_signatures
+        supported_by_family(:ml_dsa)
+      end
+
+      def legacy_metadata_view
+        @legacy_metadata_view ||= entries.each_with_object({}) do |(algorithm, entry), view|
+          oid = entry.fetch(:legacy_oid)
+          next if oid.nil?
+
+          view[algorithm] = {
+            family: entry.fetch(:family),
+            oid: oid,
+          }.freeze
+        end.freeze
+      end
+
+      def details_for_family(family)
+        @details_for_family ||= {}
+        @details_for_family[family] ||= begin
+          entries.each_with_object({}) do |(algorithm, entry), details|
+            next unless entry.fetch(:family) == family
+
+            details[algorithm] = details_entry(algorithm, entry)
+          end.freeze
+        end
+      end
+
+      private
+
+      def supported_by_family(family)
+        supported_by_family_cache[family] ||= entries.each_with_object([]) do |(algorithm, entry), supported|
+          supported << algorithm if entry.fetch(:family) == family
+        end.freeze
+      end
+
+      def supported_by_family_cache
+        @supported_by_family_cache ||= {}
+      end
+
+      def legacy_oid_index
+        @legacy_oid_index ||= entries.each_with_object({}) do |(algorithm, entry), index|
+          oid = entry.fetch(:legacy_oid)
+          index[oid] = algorithm unless oid.nil?
+        end.freeze
+      end
+
+      def standard_oid_index
+        @standard_oid_index ||= entries.each_with_object({}) do |(algorithm, entry), index|
+          oid = entry.fetch(:standard_oid)
+          index[oid] = algorithm unless oid.nil?
+        end.freeze
+      end
+
+      def details_entry(algorithm, entry)
+        # :oid intentionally remains an alias for the legacy pqc_container_* OID.
+        # Use .standard_oid when an RFC 9935/9881 OID is required.
+        detail = {
+          name: algorithm,
+          family: entry.fetch(:family),
+          oid: entry.fetch(:legacy_oid),
+          public_key_bytes: entry.fetch(:public_key_bytes),
+          secret_key_bytes: entry.fetch(:secret_key_bytes),
+        }
+
+        if entry.fetch(:ciphertext_bytes)
+          detail[:ciphertext_bytes] = entry.fetch(:ciphertext_bytes)
+          detail[:shared_secret_bytes] = entry.fetch(:shared_secret_bytes)
+        end
+
+        detail[:signature_bytes] = entry.fetch(:signature_bytes) if entry.fetch(:signature_bytes)
+        detail[:description] = entry.fetch(:description)
+
+        detail.freeze
+      end
+
+    end
+  end
+end