kcoap-crypto-bc

Post-quantum CryptoBackend for the JVM and Android: ML-KEM (FIPS 203) and ML-DSA (FIPS 204) on Bouncy Castle's lightweight API (bcprov-jdk18on), for the EDHOC PQ cipher suites of draft-ietf-lake-pqsuites. libedhoc's private suite -24 uses ML-KEM-512 for the ephemeral key exchange and ML-DSA-44 for signatures.

val crypto = BouncyCastleCryptoBackend(classical = DefaultCryptoBackend())   // kcoap-crypto-default
val responder = crypto.generateKeyPair(KeyType.ML_KEM_512)
val sent = crypto.encapsulate(KemAlgorithm.ML_KEM_512, responder.publicKey)
val received = crypto.decapsulate(responder.privateKey, sent.ciphertext) // same bytes as sent.sharedSecret()
sent.destroy() // overwrites the sender's copy

What it does

------------

BouncyCastleCryptoBackend(classical, isSigningDeterministic = false) implements generateKeyPair, importKeyPair, sign, verify, encapsulate and decapsulate for the ML-KEM and ML-DSA key types and delegates everything else (hashes, HMAC, AEADs, X25519, P-256/384, Ed25519, ECDSA) to classical. Its supports members answer yes for ML-KEM and ML-DSA without probing and pass every other question to classical (../docs/adr/0001-crypto-capabilities.md), so EDHOC offers suite -24 with it.

The module does not choose the classical backend, and depends only on kcoap-crypto (with kcoap-common) and Bouncy Castle. Most applications pass DefaultCryptoBackend() and declare both modules:

dependencies {
val kcoap = "0.1.0" // one version for every kcoap module
implementation("dev.kcoap:kcoap-crypto-default:$kcoap") // the classical algorithms, on cryptography-kotlin
implementation("dev.kcoap:kcoap-crypto-bc:$kcoap") // ML-KEM and ML-DSA
}

An application with a classical backend of its own (a secure element, the Android KeyStore, a decorator of another backend) passes that one instead and leaves out kcoap-crypto-default, and with it cryptography-kotlin.

AlgorithmParameter setsSpec
ML-KEM: KeyGen, Encaps, Decaps with implicit rejection512, 768, 1024FIPS 203 Algorithms 19-21
ML-DSA: KeyGen, Sign (hedged by default, deterministic on request), Verify44, 65, 87FIPS 204 Algorithms 1-3
  • ML-DSA is pure ML-DSA (not HashML-DSA) with an empty context string, as COSE uses it (draft-ietf-cose-dilithium, ids -48/-49/-50).

  • Input checks: the modulus check of encapsulation keys (FIPS 203 §7.2), the length and hash checks of ciphertexts and decapsulation keys (FIPS 203 §7.3). A tampered ciphertext of the right length is not an error: it decapsulates to the implicit-rejection secret J(z || c), so the failure shows up when the derived keys are used.

  • verify returns false for a wrong or malformed signature and throws only for a public key of the wrong length.

  • All randomness (d || z, m, ξ, rnd) is drawn from classical.randomBytes and wiped after use, so a backend with fixed random bytes replays known-answer vectors. A random source that returns the wrong number of bytes is rejected.

Key encodings

-------------

The encodings are the standard ones, so keys move unchanged between kcoap and other implementations such as libedhoc.

Public keyGenerated private keyAccepted by importKeyPair
ML-KEM-512 / 768 / 1024encapsulation key ek, 800 / 1184 / 1568 bytesseed d \|\| z, 64 bytesseed, or expanded dk of 1632 / 2400 / 3168 bytes
ML-DSA-44 / 65 / 87pk, 1312 / 1952 / 2592 bytesseed ξ, 32 bytesseed, or expanded sk of 2560 / 4032 / 4896 bytes

Private keys are SoftwarePrivateKeys. Generated keys hold the seed: it is small and determines the whole key, and the expanded key is derived again for each operation. Imported keys stay in the encoding they were given; the seed and expanded forms are told apart by length. Import checks that the private key belongs to the public key (for ML-DSA also that tr = H(pk, 64), which Bouncy Castle does not check), and rejects an ML-KEM key pair that fails the FIPS 203 input checks.

The lengths come from kcoap-crypto, where every backend and key format reads them: KeyType.seedLength and KeyType.expandedPrivateKeyLength, and SignatureAlgorithm.trLength for ML-DSA's tr.

Verified by

-----------

The conformance suites of ../kcoap-crypto-testsuite/README.md, which the tests extend:

  • the capability contract (BouncyCastleConformanceTest): every supports answer holds, the ML-KEM and ML-DSA ones and those passed to the classical backend. Without the supports overrides the backend fails it for exactly the algorithms it adds (SupportsOverridesTest, with a test-only wrapper that forwards the questions to the classical backend);

  • NIST ACVP known-answer vectors (MlKemKnownAnswerTest, MlDsaKnownAnswerTest; github.com/usnistgov/ACVP-Server, gen-val/json-files, commit 975de31e), a few cases per parameter set, which the suite holds and replays through the public backend with scripted randomness:

FiletcIdsWhat is checked
ML-KEM-keyGen-FIPS2031, 26, 51ek from d, z; seed and expanded dk decapsulate alike
ML-KEM-encapDecap-FIPS2031, 26, 51c and k from ek, m; dk decapsulates c to k
ML-KEM-encapDecap-FIPS20376implicit rejection: modified c gives NIST's k
ML-KEM-encapDecap-FIPS203117, 106modulus check rejects ek; hash check rejects dk
ML-DSA-keyGen-FIPS2041, 26, 51pk from ξ; seed and expanded sk sign alike
ML-DSA-sigGen-FIPS2045, 44, 70 (deterministic), 189 (hedged)signatures byte for byte, and they verify
ML-DSA-sigVer-FIPS20410NIST's rejection of a modified message

ML-DSA cases are all external-interface, pure, empty-context ones, the only variant the backend exposes. The suite signs NIST's deterministic vectors with the default hedged signer and rnd = {0}^32. Besides the vectors, the tests cover round trips for every parameter set, implicit rejection against kcoap's own SHAKE256, tampered, truncated and malformed signatures, every input check (with the IllegalArgumentException this backend documents, on keys expanded by Bouncy Castle itself), delegation of the classical algorithms (to DefaultCryptoBackend, a test-only dependency here, and to a minimal backend with only the required primitives), and the wiping of drawn randomness.

./gradlew :kcoap-crypto-bc:jvmTest :kcoap-crypto-bc:koverXmlReport

Packages

Link copied to clipboard