CryptoBackend

The single seam between protocol code and cryptography, in the spirit of libedhoc's crypto vtable: protocol modules never call a platform API directly, so a backend can be replaced by one for a secure element, Android KeyStore / Secure Enclave keys, a post-quantum provider, or a deterministic test double.

All operations suspend, because some platforms (WebCrypto) only offer asynchronous cryptography.

Only the symmetric primitives are required. Asymmetric operations default to throwing UnsupportedAlgorithmException, so an OSCORE-only deployment can use a minimal backend. Backends override what they support; see DefaultCryptoBackend and BouncyCastleCryptoBackend.

Capabilities

Platforms differ in what their cryptography offers (WebCrypto has no ChaCha20/Poly1305, a secure element may have only P-256), so protocol code asks before it commits: the supports members say whether an operation would run, and EDHOC offers only the cipher suites they allow. The contract (docs/adr/0001-crypto-capabilities.md): supports(x) is false exactly when the operations on x would throw UnsupportedAlgorithmException. Other failures, such as malformed input, are not a missing capability.

The defaults find out by trying: they run each operation once on throwaway keys and count only UnsupportedAlgorithmException as a no. They remember nothing, so every call probes again and costs key pairs. A software backend therefore memoizes the answers per instance, as DefaultCryptoBackend does, and a hardware or secure-element backend overrides the members with static answers, because a probe there could create a persistent key or prompt for a biometric. An answer must not change during the backend's lifetime. Callers cannot rely on the memo: they ask once and keep the answers, as EDHOC keeps them per configuration and backend instead of asking per session.

A decorator (CryptoBackend by delegate) forwards supports to its delegate, so one that adds algorithms, as BouncyCastleCryptoBackend adds ML-KEM and ML-DSA, must also override the matching supports members.

Functions

Link copied to clipboard
open suspend fun aead(algorithm: AeadAlgorithm, key: ByteArray): Aead

An AEAD for algorithm. AES-CCM is implemented in common code on top of aesBlockCipher because CryptoKit, CommonCrypto, WebCrypto and the stock JDK do not offer it. Backends override this for what their platform provides natively (AES-GCM, ChaCha20/Poly1305).

Link copied to clipboard
abstract suspend fun aesBlockCipher(key: ByteArray): AesBlockCipher

Raw AES block encryption (16-byte blocks) with a 128, 192 or 256-bit key.

Link copied to clipboard
open suspend fun decapsulate(privateKey: PrivateKey, ciphertext: ByteArray): ByteArray
Link copied to clipboard
abstract suspend fun digest(algorithm: HashAlgorithm, data: ByteArray): ByteArray

A digest of HashAlgorithm.outputLength bytes.

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

Encapsulates a fresh shared secret to the encapsulation key publicKey (FIPS 203 §7.2). The caller owns the result and destroys it once it has the secret.

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

A fresh key pair. Used for EDHOC ephemeral keys and for provisioning static keys.

Link copied to clipboard
abstract suspend fun hmac(algorithm: HashAlgorithm, key: ByteArray, data: ByteArray): ByteArray

HMAC with a SHA-2 hash. Not defined for SHAKE256, which uses KMAC instead.

Link copied to clipboard
open suspend fun importKeyPair(type: KeyType, privateKey: ByteArray, publicKey: ByteArray): KeyPair

Wraps existing key material, for static keys from configuration and fixed keys in test vectors. The default keeps the key in memory as a SoftwarePrivateKey.

Link copied to clipboard
open suspend fun keyAgreement(privateKey: PrivateKey, peerPublicKey: ByteArray): ByteArray

Diffie-Hellman: the shared secret of privateKey and peerPublicKey, in the raw encoding of the key's KeyType. For P-256 and P-384 that is an uncompressed SEC1 point 04 || x || y of KeyType.publicKeyLength bytes, and the result is the x-coordinate of the shared point (SEC 1 v2 §3.3.1). Callers expand compressed points with Sec1 first; a backend may accept them too, as DefaultCryptoBackend does, but need not.

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

A signature over data with privateKey, whose type must be SignatureAlgorithm.keyType. ECDSA signatures are raw r || s of SignatureAlgorithm.signatureLength bytes, as COSE uses them (RFC 9053 §2.1); EcdsaSignatureCodec converts them to DER for X.509 and DTLS.

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

Whether aead runs algorithm. The default asks by building it under an all-zero key and encrypting an empty message.

open suspend fun supports(algorithm: HashAlgorithm): Boolean

Whether this backend computes the digest of algorithm, and for a SHA-2 hash also its hmac, which HKDF (RFC 5869) needs. The default asks by hashing and authenticating an empty message.

open suspend fun supports(algorithm: KemAlgorithm): Boolean

Whether this backend encapsulates and decapsulates with algorithm (FIPS 203). The default asks by generating a key pair, encapsulating to it and decapsulating the ciphertext.

open suspend fun supports(type: KeyType): Boolean

Whether this backend generates and uses key pairs of type: generateKeyPair, and for the Diffie-Hellman types (X25519, X448, P-256, P-384) also keyAgreement. Signing is asked for separately, with supports(SignatureAlgorithm). The default asks by generating a key pair and, for a Diffie-Hellman type, agreeing on a secret with the pair's own public key.

open suspend fun supports(algorithm: SignatureAlgorithm): Boolean

Whether this backend signs and verifys with algorithm. The default asks by generating a key pair, signing an empty message and verifying the signature.

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

Whether signature over data verifies under publicKey, in the raw encoding of SignatureAlgorithm.keyType: an uncompressed SEC1 point for ES256 and ES384, as for keyAgreement. ECDSA signatures are raw r || s (EcdsaSignatureCodec converts DER). Returns false for a wrong signature; throws only for unusable input such as a malformed key.