Cryptographic failure contract

Scope: native-builtins-crypto/ and native-builtins-security/. The same rule governs the JSSE and JCA surface in native-builtins/ (tls.rs, tls_impl.rs, t27_tls.rs, jca/signature.rs, jca/cipher.rs, crypto_impl.rs, keystore.rs, securerandom.rs), where it takes a sharper form: a TLS API never returns a plaintext or no-op object. A socket factory that cannot negotiate TLS must fail, not hand back a cleartext socket. Status: audit complete for those two crates; the JCA/TLS engine surface in native-builtins/ is out of scope for this pass and is listed under Residual gaps.

---

1. The rule

A security API never encodes failure as ordinary output.

An empty byte[] from Signature.sign(), a false from Signature.verify() because the key was rejected, a zero block from a cipher whose key schedule was malformed, a silently truncated private-key scalar — each of these is indistinguishable, at the call site, from a legitimate negative security decision. The caller records "not signed", "did not verify", "no match" when the truth is "we never checked". That is the bug class this document closes.

Three consequences, applied throughout both crates:

1. Unsupported / uninitialised / malformed ⇒ raise. The kernel returns an error naming the JDK-specified exception; the facade throws it. Never a default, never a zero, never Ok(()).
2. Genuine negatives are preserved. verify() returning false for a real digest mismatch is correct and must not become an exception. Corrupt signature bits are what a forgery looks like — that is a false. A wrong signature length is a malformed encoding — that is a SignatureException. The two are distinguished explicitly, and each decision is commented at its site.
3. Failure is catchable. Errors carry a java.* class name and are thrown as real Throwables. Error/panic is not an acceptable failure mode for a condition Java code is expected to handle.

The mechanism

native-builtins-crypto is a pure kernel island with no NativeContext (see its lib.rs): it cannot construct a Java Throwable, so it returns Err(CryptoFailure) carrying the internal-form exception class name, and the facade throws it. native-builtins-security does have a NativeContext and throws directly.

Both mirror the facade's existing helper — copied from native-builtins/src/phases_early.rs:14672 (throw_jca_exc), cross-checked against native-builtins/src/phases_late/bouncycastle.rs:6040 (bc_gost_throw_crypto_exception):

let detail = ctx.create_string(msg);
match ctx.new_object_initialized(class_name, "(Ljava/lang/String;)V",
                                 &[Value::Object(Some(detail))]) {
    Ok(Some(Value::Object(Some(exc)))) => MethodCallFailed::ExceptionThrown(exc),
    _ => RuntimeError::IllegalStateException { .. }.into(),   // still loud
}

The fallback arm is load-bearing: if the exception class itself cannot be constructed (synthetic-JDK mode, class absent from the boot path) an unchecked exception is still raised. There is deliberately no arm that returns a value.

---

2. Audit table

2.1 Sites changed

2.2 Sites inspected and deliberately left unchanged

Count: 13 sites changed, 7 classes of site deliberately left (each with the reasoning above and a matching in-source comment).

---

3. Algorithms: supported vs explicitly rejected

native-builtins-crypto

native-builtins-security

Not present in these crates at all

TLS/SSL, KeyStore, CertificateFactory, MessageDigest, KeyFactory, KeyPairGenerator, SecureRandom, and Provider lookup do not exist in either crate — verified by exhaustive grep over both source trees. Nothing was invented for them here. They live in native-builtins/ and are covered under Residual gaps.

---

4. Trust boundaries

Every site below carries a // TRUST BOUNDARY: comment in source.

4.1 Signature verification is not trust establishment

native-builtins-crypto/src/signature.rs:53

verify_rsa_pkcs1_v15_checked returning true means exactly one thing: these bytes are a valid PKCS#1 v1.5 signature over this message under this public key. It says nothing about whether the key is trusted, whether its certificate chains to an anchor, whether that chain is in date, or whether it has been revoked.

4.2 Signed JARs — must not be used as a trust boundary

native-builtins-crypto/src/signature.rs:137

Signed JARs must not be relied upon as a trust boundary until certification-path validation is complete.

The shared verifier confirms the cryptographic signature. The consumer (classloading/src/jar_signer.rs) performs no PKIXValidator-equivalent certification-path construction, no trust-anchor check, no validity-window check, and no revocation check. A JAR signed by any syntactically valid self-generated key therefore passes signature verification. Treating "the JAR is signed" as "the JAR is from a trusted publisher" is unsound in this build.

Additionally, jar_signer.rs:1516 still calls the ambiguous bool wrapper and maps false to SigVerify::Bad, so an unusable signer key is currently reported as a bad signature. Both outcomes refuse the JAR — the behaviour is safe today, the reporting is not precise. classloading/ already has the right shape for the fix: a distinct SigVerify::Unsupported variant that this call site does not yet use.

4.3 Non-canonical EC scalars are reported as the identity

native-builtins-security/src/sunec_point.rs:448

A scalar >= n yields the neutral element rather than an error. This is required by ECDHKeyAgreement.validate's public-key order check (n·P = O), and no legitimate keygen/sign/ECDH scalar (always in [1, n)) reaches it. The conflation is nonetheless real: a future caller passing a >= n scalar for an actual multiply would receive the identity, and identity is a plausible answer. Narrowing it requires the group order per curve plus end-to-end ECDH validation.

---

5. Residual gaps

Ordered by exposure. Items 1–3 are outside the two crates audited here.

1. TLS is entirely in native-builtins/ and was not audited. tls.rs (4344 lines), tls_impl.rs (2774), t27_tls.rs (10248). One structural hazard is visible from the source comments and should be the first thing a follow-up pass looks at: native-builtins/src/t27_tls.rs:4350 states that an SSLServerSocketFactory.createServerSocket overload without an explicit native bridge "reaches ServerSocketFactory's plaintext implementation" — i.e. a plaintext ServerSocket returned where an SSLServerSocket was requested. The doc comment at :4167–:4170 says the same thing from the other side ("so callers cannot accidentally fall through to ServerSocketFactory's plaintext implementation"). Known-affected overloads were bridged individually as they were found; the structural point is that any unbridged overload still degrades silently to plaintext. This is the P1 "unsupported TLS must be impossible to mistake for transport security" item and it needs an explicit deny-by-default at the factory, not per-overload patches.

2. The JCA engine surface is in native-builtins/ and was not audited. jca/signature.rs, jca/cipher.rs, jca/key_factory.rs, jca/message_digest.rs, jca/provider_chain.rs, crypto_impl.rs, keystore.rs, x509_manager.rs, securerandom.rs. Two degradations are already visible in that tree without a full audit: phases_early.rs:14701 returns Ok(Some(Value::Object(None))) — a null — from Cipher.doFinal on an uninitialised Cipher, explicitly instead of IllegalStateException; and phases_early.rs:14706/:14714 read the algorithm name and key bytes with unwrap_or_default() / Vec::new(), so a missing key becomes an empty key rather than an InvalidKeyException. The crate does have the right mechanism (throw_jca_exc) and uses it correctly elsewhere (e.g. jca/cipher.rs:637 for AES/CCM) — the gap is coverage, not capability.

3. Certification-path validation for signed JARs — see §4.2. Until it exists, signed JARs are not a trust boundary.

4. Migrate the infallible kernels to their try_* forms. Four AES call sites (native-builtins/src/phases_late/bouncycastle.rs:6098, :6110, :6208/:6210, :6585/:6592) and three ChaCha/Salsa call sites (:7237, :7264, :7287). The ChaCha ones are a pure consolidation — each already performs the identical parity check by hand. The AES ones are not: all four validate with kw.len() < 2, a lower bound that still admits a 2- or 4-entry schedule, which the round structure indexes past the end of. try_encrypt_block/try_decrypt_block check the length exactly (11/13/15). Only BouncyCastle's own generateWorkingKey currently feeds these call sites, so no live path reaches the hole — but the callers' guard is weaker than it reads.

5. Migrate classloading/src/jar_signer.rs:1516 to verify_rsa_pkcs1_v15_checked and map Err to SigVerify::Unsupported (the variant already exists) rather than SigVerify::Bad.

6. Narrow the non-canonical-scalar identity branch — see §4.3.

7. sunec_point.rs leaks GC pins on the error paths. The unsupported-curve arms call unpin_native_roots(pin_base) before returning, but the ? early-returns after it (getX/getY/asBigInteger/read_bigint_be, and the new scalar-read refusal is before any pin is taken) do not. This is a root-set leak, not a cryptographic degradation, and was left alone to keep this pass to failure semantics — but it should be fixed with a scope guard.

---

6. Test coverage for this contract

All tests are #[cfg(test)] inside the two crates.

Provider-lookup miss has no test here because no provider-lookup path exists in either crate (§3); the constant NO_SUCH_PROVIDER_EXCEPTION is provided for the facade and is covered by the internal-form test.