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
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).
Raw AES block encryption (16-byte blocks) with a 128, 192 or 256-bit key.
A digest of HashAlgorithm.outputLength bytes.
A fresh key pair. Used for EDHOC ephemeral keys and for provisioning static keys.
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.
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.
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.
Whether aead runs algorithm. The default asks by building it under an all-zero key and encrypting an empty message.
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.
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.
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.
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.