BouncyCastleCryptoBackend

class BouncyCastleCryptoBackend(classical: CryptoBackend, isSigningDeterministic: Boolean = false) : CryptoBackend(source)

CryptoBackend with the post-quantum algorithms of the EDHOC PQ cipher suites (draft-ietf-lake-pqsuites): ML-KEM-512/768/1024 (FIPS 203) for the ephemeral key exchange and ML-DSA-44/65/87 (FIPS 204) for signatures, on Bouncy Castle's lightweight API. libedhoc's private suite -24 uses ML-KEM-512 and ML-DSA-44. JVM and Android only.

Everything else (hashes, HMAC, AEADs, ECDH, EdDSA, ECDSA, randomness) is delegated to classical. The ML-KEM and ML-DSA randomness also comes from classical.randomBytes, so a backend with fixed random bytes replays NIST's known-answer vectors through this class.

Encodings, chosen so keys move unchanged to and from other implementations such as libedhoc:

  • Public keys are the FIPS 203 encapsulation key ek and the FIPS 204 public key pk.

  • Generated private keys are SoftwarePrivateKeys holding the seed: the 64 bytes d || z of ML-KEM.KeyGen (FIPS 203 Algorithm 19) or the 32 bytes ξ of ML-DSA.KeyGen (FIPS 204 Algorithm 1). Seeds are small and determine the whole key; the expanded key is re-derived from the seed for every operation.

  • importKeyPair accepts the seed or the expanded FIPS encoding (dk of 768k + 96 bytes, sk of 2560, 4032 or 4896 bytes), told apart by length, and keeps the private key in the encoding it was given.

ML-DSA is pure ML-DSA (not HashML-DSA) with an empty context string, as COSE uses it (draft-ietf-cose-dilithium).

The supports members answer for ML-KEM and ML-DSA without probing, since Bouncy Castle always has them, and ask classical about everything else (docs/adr/0001-crypto-capabilities.md).

This module does not choose the classical backend: the application passes one, usually BouncyCastleCryptoBackend(DefaultCryptoBackend()) with kcoap-crypto-default, or its own (a secure element, the Android KeyStore), in which case cryptography-kotlin is not needed at all.

Parameters

classical

the backend for every algorithm that is not ML-KEM or ML-DSA, and for randomness.

isSigningDeterministic

whether ML-DSA signs with the deterministic variant (rnd = {0}^32, FIPS 204 §3.4) instead of the default hedged one. Deterministic signatures are reproducible, which known-answer tests need; hedged ones resist fault and side-channel attacks better.

Constructors

Link copied to clipboard
constructor(classical: CryptoBackend, isSigningDeterministic: Boolean = false)

Functions

Link copied to clipboard
open suspend override fun aead(algorithm: AeadAlgorithm, key: ByteArray): Aead
Link copied to clipboard
open suspend override fun aesBlockCipher(key: ByteArray): AesBlockCipher
Link copied to clipboard
open suspend override fun decapsulate(privateKey: PrivateKey, ciphertext: ByteArray): ByteArray

ML-KEM.Decaps (FIPS 203 Algorithm 21). A ciphertext that was tampered with yields a different, pseudorandom secret rather than an error (implicit rejection), so the failure surfaces when the derived keys are used.

Link copied to clipboard
open suspend override fun digest(algorithm: HashAlgorithm, data: ByteArray): ByteArray
Link copied to clipboard
open suspend override fun encapsulate(algorithm: KemAlgorithm, publicKey: ByteArray): KemEncapsulation

ML-KEM.Encaps (FIPS 203 Algorithm 20).

Link copied to clipboard
open suspend override fun generateKeyPair(type: KeyType): KeyPair

ML-KEM.KeyGen (FIPS 203 Algorithm 19) or ML-DSA.KeyGen (FIPS 204 Algorithm 1), with the seed as private key.

Link copied to clipboard
open suspend override fun hmac(algorithm: HashAlgorithm, key: ByteArray, data: ByteArray): ByteArray
Link copied to clipboard
open suspend override fun importKeyPair(type: KeyType, privateKey: ByteArray, publicKey: ByteArray): KeyPair

For ML-KEM and ML-DSA, privateKey is either the seed or the expanded FIPS encoding (see the class documentation), and must belong to publicKey.

Link copied to clipboard
open suspend override fun keyAgreement(privateKey: PrivateKey, peerPublicKey: ByteArray): ByteArray
Link copied to clipboard
open suspend override fun randomBytes(size: Int): ByteArray
Link copied to clipboard
open suspend override fun sign(algorithm: SignatureAlgorithm, privateKey: PrivateKey, data: ByteArray): ByteArray

ML-DSA.Sign (FIPS 204 Algorithm 2), hedged unless the backend was built with isSigningDeterministic.

Link copied to clipboard
open suspend override fun supports(algorithm: AeadAlgorithm): Boolean
open suspend override fun supports(algorithm: HashAlgorithm): Boolean

open suspend override fun supports(algorithm: KemAlgorithm): Boolean

True for ML-KEM-512/768/1024; classical's answer for any other KEM.

open suspend override fun supports(type: KeyType): Boolean

True for the ML-KEM and ML-DSA key types; classical's answer for the others.

open suspend override fun supports(algorithm: SignatureAlgorithm): Boolean

True for ML-DSA-44/65/87; classical's answer for the others.

Link copied to clipboard
open suspend override fun verify(algorithm: SignatureAlgorithm, publicKey: ByteArray, data: ByteArray, signature: ByteArray): Boolean

ML-DSA.Verify (FIPS 204 Algorithm 3). Returns false for a wrong or malformed signature.