Kotlin: HKDF-SHA256 and AES-256-GCM, against external vectors

Checked against RFC 5869 and NIST CAVP rather than against our JavaScript engine. An implementation validated only against our other implementation inherits our misunderstandings, and finding where the first two quietly agreed on something the spec does not say is the entire reason for writing a third. Three things pinned that a naive version gets wrong: - An empty HKDF salt means HashLen zeros, not "no HMAC key". SecretKeySpec throws on a zero-LENGTH key, so the naive version crashes on exactly the case the app uses -- §12 derives its per-context secrets with an empty salt. - 255 blocks is a hard ceiling. The counter is one byte; a naive loop wraps at 256 and silently returns key material it already returned. - The AEAD box is nonce || ciphertext || tag. CryptoKit's `combined` emits that layout and the JS engine assembles it by hand to match, so a box built any other way decrypts to garbage on the other engines rather than failing loudly. HKDF is hand-written on Mac rather than taken from a provider: Android's providers disagree about whether HKDF exists at all. Kotlin engine: 9 tests -> 27. ⚠️ Still JVM-only. These prove nothing about Android, where crypto goes through Conscrypt rather than the JVM's JCA, and nothing here has ever been compiled against the Android SDK. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-22 11:22:31 -04:00
parent e7862c0d95
commit bff7a4bbdd
4 changed files with 399 additions and 0 deletions
@@ -0,0 +1,66 @@
+package io.flamenet.e2e
+
+import java.security.GeneralSecurityException
+import javax.crypto.Cipher
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.SecretKeySpec
+
+/**
+ * AES-256-GCM, in the layout the protocol uses: `nonce || ciphertext || tag`.
+ *
+ * That layout is not incidental. CryptoKit's `AES.GCM.SealedBox.combined` emits
+ * exactly this, the JavaScript engine assembles it by hand to match, and a box
+ * built any other way decrypts to garbage on the other two engines rather than
+ * failing loudly. So it is pinned here and tested, not left to a convention.
+ *
+ * 12-byte nonces and 16-byte tags throughout — the only sizes the other engines
+ * produce, and the sizes GCM is actually safe at.
+ */
+object Aead {
+
+    const val NONCE_LEN = 12
+    const val TAG_LEN = 16
+
+    class DecryptionFailed(message: String) : GeneralSecurityException(message)
+
+    /**
+     * Seal [plaintext], returning `nonce || ciphertext || tag`.
+     *
+     * The nonce is supplied rather than generated so callers cannot accidentally
+     * reuse one and so this is testable against fixed vectors. **A nonce must
+     * never repeat under one key** — GCM does not degrade gracefully there, it
+     * leaks the authentication subkey and with it the ability to forge.
+     */
+    fun seal(key: ByteArray, nonce: ByteArray, plaintext: ByteArray,
+             aad: ByteArray = ByteArray(0)): ByteArray {
+        require(key.size == 32) { "AES-256-GCM needs a 32-byte key, got ${key.size}" }
+        require(nonce.size == NONCE_LEN) { "GCM nonce must be $NONCE_LEN bytes, got ${nonce.size}" }
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        cipher.init(Cipher.ENCRYPT_MODE, SecretKeySpec(key, "AES"),
+                    GCMParameterSpec(TAG_LEN * 8, nonce))
+        if (aad.isNotEmpty()) cipher.updateAAD(aad)
+        return nonce + cipher.doFinal(plaintext)
+    }
+
+    /** Open a `nonce || ciphertext || tag` box. */
+    fun open(key: ByteArray, box: ByteArray, aad: ByteArray = ByteArray(0)): ByteArray {
+        require(key.size == 32) { "AES-256-GCM needs a 32-byte key, got ${key.size}" }
+        // Refuse a box too short to contain what it claims, rather than letting
+        // the array slicing below throw something unrelated.
+        if (box.size < NONCE_LEN + TAG_LEN) {
+            throw DecryptionFailed("box is ${box.size} bytes, too short to hold a nonce and a tag")
+        }
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        cipher.init(Cipher.DECRYPT_MODE, SecretKeySpec(key, "AES"),
+                    GCMParameterSpec(TAG_LEN * 8, box, 0, NONCE_LEN))
+        if (aad.isNotEmpty()) cipher.updateAAD(aad)
+        return try {
+            cipher.doFinal(box, NONCE_LEN, box.size - NONCE_LEN)
+        } catch (e: GeneralSecurityException) {
+            // Deliberately one message for every failure. Distinguishing "bad
+            // tag" from "wrong key" hands an attacker a decision oracle, and
+            // there is nothing a caller can usefully do differently.
+            throw DecryptionFailed("could not open the box")
+        }
+    }
+}
@@ -0,0 +1,67 @@
+package io.flamenet.e2e
+
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+
+/**
+ * HKDF-SHA256 (RFC 5869).
+ *
+ * Hand-written on top of [Mac] rather than taken from a provider, because
+ * Android's providers disagree about whether HKDF exists at all: it is absent
+ * from the platform on older API levels and available under different names
+ * elsewhere. HMAC-SHA256 is present everywhere this will ever run, and extract
+ * plus expand is twenty lines on top of it.
+ *
+ * Checked against RFC 5869's own test vectors rather than against the
+ * JavaScript engine. That matters: an implementation validated only against our
+ * other implementation inherits our misunderstandings, and the entire reason
+ * this third engine is being written is to find the places where the other two
+ * quietly agreed on something the specification does not say.
+ */
+object Hkdf {
+
+    private const val HASH_LEN = 32
+
+    /**
+     * Extract-then-expand. [salt] may be empty, which RFC 5869 defines as a
+     * string of HashLen zeros — not as "skip the extract step".
+     */
+    fun derive(ikm: ByteArray, salt: ByteArray, info: ByteArray, length: Int): ByteArray {
+        require(length > 0) { "HKDF length must be positive" }
+        // 255 * HashLen is the hard ceiling in the RFC: the counter is one byte
+        // and starts at 1, so asking for more silently wraps in a naive
+        // implementation and returns repeated key material.
+        require(length <= 255 * HASH_LEN) { "HKDF cannot produce more than ${255 * HASH_LEN} bytes" }
+        return expand(extract(ikm, salt), info, length)
+    }
+
+    fun extract(ikm: ByteArray, salt: ByteArray): ByteArray {
+        val effectiveSalt = if (salt.isEmpty()) ByteArray(HASH_LEN) else salt
+        return hmac(effectiveSalt, ikm)
+    }
+
+    fun expand(prk: ByteArray, info: ByteArray, length: Int): ByteArray {
+        val out = ByteArray(length)
+        var previous = ByteArray(0)
+        var offset = 0
+        var counter = 1
+        while (offset < length) {
+            val block = hmac(prk, previous + info + byteArrayOf(counter.toByte()))
+            val take = minOf(block.size, length - offset)
+            block.copyInto(out, offset, 0, take)
+            offset += take
+            previous = block
+            counter++
+        }
+        return out
+    }
+
+    private fun hmac(key: ByteArray, data: ByteArray): ByteArray {
+        val mac = Mac.getInstance("HmacSHA256")
+        // An all-zero key is legal input here (RFC 5869 salt), and
+        // SecretKeySpec rejects a zero-LENGTH key rather than a zero-valued
+        // one — so the empty-salt case must be widened before it reaches here.
+        mac.init(SecretKeySpec(key, "HmacSHA256"))
+        return mac.doFinal(data)
+    }
+}