DefaultCryptoBackend

CryptoBackend on cryptography-kotlin: JCA on JVM/Android, CryptoKit and CommonCrypto on Apple, OpenSSL on Linux, WebCrypto in browsers and Node.js.

Offers everything the classical EDHOC suites and OSCORE need: SHA-2, SHAKE256 (common code), HMAC, AES-CCM (common code on the platform AES block), AES-GCM, ChaCha20/Poly1305, X25519, Ed25519, and P-256/P-384 for ECDH and ECDSA, as far as the platform has them. Post-quantum algorithms come from BouncyCastleCryptoBackend.

The code is the same on every platform; what differs is only what the provider offers, and the backend adapts by capability, never by platform:

  • The AES block under CCM comes from AES-ECB when the provider has it and from AES-CTR otherwise (WebCrypto has no ECB); see PlatformAesBlock.

  • P-256 and P-384 keys arrive uncompressed, as the CryptoBackend contract has them; protocol code expands compressed points with Sec1. This backend also accepts compressed ones, which it expands with Sec1 before any provider sees them, since not every platform takes them.

  • What the platform lacks is reported as UnsupportedAlgorithmException when it is asked for, and the supports members ask in advance: ChaCha20/Poly1305 on WebCrypto, 192-bit AES keys in Chromium, X25519 and Ed25519 in browsers that predate them.

  • Other platform failures leave as exceptions, also where the platform's own are not Kotlin exceptions (WebCrypto), so protocol code can turn them into protocol errors.

The supports members probe once per instance and memoize the answer (docs/adr/0001-crypto-capabilities.md): the first question about an algorithm runs its operations on throwaway keys, and every later one is a lookup, however many callers ask at once.

Private keys are SoftwarePrivateKeys holding raw key material in memory. The copies of it that the platform takes or hands out are wiped once the platform is done with them; the platform's own key objects cannot be wiped.

The class is final (docs/adr/0002-delegation-not-subclassing.md). To change or add operations, wrap it in a decorator, class MyBackend(d: CryptoBackend) : CryptoBackend by d, as BouncyCastleCryptoBackend adds ML-KEM and ML-DSA. A decorator overrides the supports members of what it changes or adds: the delegate answers them by probing its own operations, never the decorator's.

No cryptography-kotlin type is part of this module's public API, so the API does not follow cryptography-kotlin's releases. The provider is always the platform's default one.

Constructors

Link copied to clipboard
constructor()

A backend on the platform's default provider: JCA, CryptoKit and CommonCrypto, OpenSSL or WebCrypto.

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

AES-ECB on single blocks where the provider has it, otherwise AES-CTR; see PlatformAesBlock.

Link copied to clipboard
open suspend fun decapsulate(privateKey: PrivateKey, ciphertext: ByteArray): ByteArray
Link copied to clipboard
open suspend override fun digest(algorithm: HashAlgorithm, data: ByteArray): ByteArray
Link copied to clipboard
open suspend fun encapsulate(algorithm: KemAlgorithm, publicKey: ByteArray): KemEncapsulation
Link copied to clipboard
open suspend override fun generateKeyPair(type: KeyType): KeyPair
Link copied to clipboard
open suspend override fun hmac(algorithm: HashAlgorithm, key: ByteArray, data: ByteArray): ByteArray
Link copied to clipboard
open suspend fun importKeyPair(type: KeyType, privateKey: ByteArray, publicKey: ByteArray): KeyPair
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
Link copied to clipboard
open suspend override fun supports(algorithm: AeadAlgorithm): Boolean

Probed once per instance: an AEAD built under a zero key encrypts an empty message.

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

Probed once per instance: the digest, and the HMAC of a SHA-2 hash.

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

Probed once per instance; this backend has no KEM, so the answer is false (a decorator may add one).

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

Probed once per instance: a generated key pair, and key agreement for the Diffie-Hellman types.

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

Probed once per instance: a generated key pair signs and verifies an empty message.

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