Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion kt/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,22 @@ dependencies {
}
```

## Certificate verification

Without `serverCertificateHashes` or `noCertVerification`, clients verify servers with
the operating system's trust store through
[rustls-platform-verifier](https://github.com/rustls/rustls-platform-verifier),
including user-installed and enterprise roots where the OS allows them.

On Android the verifier needs the application `Context`. The AAR handles this with no
app code: a manifest-merged `ContentProvider` loads the native library with
`System.loadLibrary` during app startup, and the library's `JNI_OnLoad` initializes
the verifier from the Application. The AAR also bundles the verifier's Kotlin
component and ships its R8/ProGuard keep rule. If initialization has not succeeded,
for example because the provider was removed from the merged manifest and the
library was first loaded by JNA, each new client retries it; a client built before
it succeeds trusts the bundled Mozilla roots from webpki-roots instead and keeps them.

## Session lifetime

Keep the Session object alive while using its streams. Streams do not retain the Session: releasing the final Session reference closes the connection, even if stream objects remain. A helper that returns streams must also return or retain their Session. An explicit close already underway keeps its bounded graceful close after the Session is released; awaiting closure lets it finish, but timeout or cancellation can prevent capsule delivery.
Expand Down Expand Up @@ -77,11 +93,13 @@ kt/
gradle.properties Defaults: version, android.useAndroidX, etc.
web-transport/
build.gradle.kts KMP plugin, jvm() always, androidTarget() conditional
consumer-rules.pro Android keep rule for the bundled verifier component
src/
commonMain/ Public Kotlin facade (reserved for future K/N)
jvmAndAndroidMain/ UniFFI-generated kotlin (populated, gitignored)
jvmMain/resources/ Native libs at JNA paths (populated, gitignored)
androidMain/jniLibs/ JNI .so per ABI (populated, gitignored)
androidMain/ Startup provider that loads the library via System.loadLibrary
jniLibs/ JNI .so per ABI (populated, gitignored)
jvmArtifactTest/ Opt-in packaged-artifact lifecycle smoke
scripts/ check.sh, package.sh
```
Expand Down
5 changes: 5 additions & 0 deletions kt/gradle.properties
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,8 @@ publishing.enabled=false
# still builds the JVM variant.
android.useAndroidX=true
android.nonTransitiveRClass=true

# Android component of rustls-platform-verifier, bundled into the AAR. The version
# must equal the rustls-platform-verifier-android pin in rs/web-transport-ffi/Cargo.toml.
rustlsPlatformVerifier.version=0.2.0
rustlsPlatformVerifier.sha256=aa021794230fbc2f0be355999e2cf67398dd563de066a2e17001ffbd0b69101b
8 changes: 8 additions & 0 deletions kt/settings.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,14 @@ dependencyResolutionManagement {
repositories {
google()
mavenCentral()
// rustls-platform-verifier publishes its Android component only here;
// web-transport/build.gradle.kts bundles it into the AAR.
exclusiveContent {
forRepository {
maven("https://github.com/rustls/rustls-platform-verifier/raw/maven-archive/android-release-support/maven/")
}
filter { includeGroup("org.rustls") }
}
}
}

Expand Down
36 changes: 35 additions & 1 deletion kt/web-transport/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
// commonMain (empty today; reserved for future K/N targets)
// └─ jvmAndAndroidMain Wrappers + UniFFI-generated kotlin (uses JNA)
// ├─ jvmMain JVM-specific: native libs as JAR resources
// └─ androidMain Android-specific: native libs in jniLibs
// └─ androidMain Android-specific: native libs in jniLibs, and a
// startup provider that loads them via System.loadLibrary
//
// Native libraries are populated by `kt/scripts/package.sh`:
// src/jvmMain/resources/<os>-<arch>/<libname> (JNA classpath layout)
Expand Down Expand Up @@ -36,6 +37,7 @@
// the signing key) don't trip on "no configured signatory".

import com.vanniktech.maven.publish.SonatypeHost
import java.security.MessageDigest
import java.time.Duration
import org.gradle.api.tasks.testing.logging.TestExceptionFormat
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
Expand All @@ -61,6 +63,36 @@ if (androidEnabled) {
apply(plugin = "com.android.library")
}

// rustls-platform-verifier verifies on Android through a small Kotlin component
// that is not on Maven Central. Bundle its classes into the AAR so consumers need
// no extra repository. Only the classes are taken: its manifest would impose an
// app-wide network security config, which only aids best-effort revocation fetches.
val rustlsPlatformVerifierJar: FileCollection? = if (androidEnabled) {
val aar = configurations.create("rustlsPlatformVerifier") {
isCanBeConsumed = false
isTransitive = false
}
val version = providers.gradleProperty("rustlsPlatformVerifier.version").get()
dependencies.add(aar.name, "org.rustls:rustls-platform-verifier:$version@aar")
val expectedSha256 = providers.gradleProperty("rustlsPlatformVerifier.sha256").get()
val extract = tasks.register<Copy>("extractRustlsPlatformVerifier") {
val aarFiles: FileCollection = aar
inputs.property("sha256", expectedSha256)
from({ zipTree(aarFiles.singleFile) }) { include("classes.jar") }
into(layout.buildDirectory.dir("rustls-platform-verifier"))
doFirst {
val digest = MessageDigest.getInstance("SHA-256").digest(aarFiles.singleFile.readBytes())
val actual = digest.joinToString("") { "%02x".format(it) }
check(actual == expectedSha256) {
"rustls-platform-verifier AAR SHA-256 is $actual, expected $expectedSha256"
}
}
}
files(layout.buildDirectory.file("rustls-platform-verifier/classes.jar")).builtBy(extract)
} else {
null
}

kotlin {
jvm()

Expand Down Expand Up @@ -114,6 +146,7 @@ kotlin {
dependsOn(jvmAndAndroidMain)
dependencies {
implementation("net.java.dev.jna:jna:5.15.0@aar")
implementation(rustlsPlatformVerifierJar!!)
}
}
val androidUnitTest by getting {
Expand All @@ -132,6 +165,7 @@ if (androidEnabled) {
ndk {
abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64")
}
consumerProguardFiles("consumer-rules.pro")
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
Expand Down
3 changes: 3 additions & 0 deletions kt/web-transport/consumer-rules.pro
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# rustls-platform-verifier calls its bundled Kotlin component through JNI,
# which shrinkers cannot see.
-keep, includedescriptorclasses class org.rustls.platformverifier.** { *; }
10 changes: 10 additions & 0 deletions kt/web-transport/src/androidMain/AndroidManifest.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application>
<!-- Loads the native library at startup; see NativeLibraryInitializer. -->
<provider
android:name="dev.moq.webtransport.NativeLibraryInitializer"
android:authorities="${applicationId}.dev.moq.webtransport.initializer"
android:exported="false" />
</application>
</manifest>
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
package dev.moq.webtransport

import android.content.ContentProvider
import android.content.ContentValues
import android.database.Cursor
import android.net.Uri
import android.util.Log

/**
* Loads the native library while the app starts, after its Application exists.
*
* `System.loadLibrary` runs the library's `JNI_OnLoad`, which initializes the
* OS platform certificate verifier from the application Context. JNA, which the
* generated bindings use, loads the library without running `JNI_OnLoad`.
*/
internal class NativeLibraryInitializer : ContentProvider() {
override fun onCreate(): Boolean {
try {
System.loadLibrary("web_transport_ffi")
} catch (e: UnsatisfiedLinkError) {
// Not fatal at startup: JNA reports the load failure when the bindings are first used.
Log.w("WebTransport", "failed to load web_transport_ffi", e)
}
return true
}

override fun query(
uri: Uri,
projection: Array<out String>?,
selection: String?,
selectionArgs: Array<out String>?,
sortOrder: String?,
): Cursor? = null

override fun getType(uri: Uri): String? = null

override fun insert(uri: Uri, values: ContentValues?): Uri? = null

override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0

override fun update(
uri: Uri,
values: ContentValues?,
selection: String?,
selectionArgs: Array<out String>?,
): Int = 0
}
8 changes: 8 additions & 0 deletions py/web-transport/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,14 @@ async def main():
asyncio.run(main())
```

## Certificate verification

Without `server_certificate_hashes` or `no_cert_verification`, `Client()` verifies
servers with the operating system's trust store through
[rustls-platform-verifier](https://github.com/rustls/rustls-platform-verifier):
the Security framework on macOS, CryptoAPI on Windows, and the system CA bundle on
Linux. Construction fails on Linux when no system CA certificate can be loaded.

## Session lifetime

Keep the Session object alive while using its streams. Streams do not retain the Session: releasing the final Session reference closes the connection, even if stream objects remain. A helper that returns streams must also return or retain their Session. An explicit close already underway keeps its bounded graceful close after the Session is released; awaiting closure lets it finish, but timeout or cancellation can prevent capsule delivery.
Expand Down
1 change: 0 additions & 1 deletion quest/a1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,3 @@ The Required list is ordered by priority. Independent children may proceed concu
- [Rust crates on rind](/quest/a1/rind/README.md) - no C crypto outside Quiche
- [Binding runtime coverage](/quest/a1/bindings/README.md) - independent language jobs
- [Rust platform verifier](/quest/a1/platform-verifier.md) - `with_system_roots()` verifies with the OS trust store
- [FFI platform verifier](/quest/a1/ffi-platform-verifier.md) - bindings verify on iOS and Android
25 changes: 0 additions & 25 deletions quest/a1/ffi-platform-verifier.md

This file was deleted.

5 changes: 2 additions & 3 deletions quest/a1/platform-verifier.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,10 @@

Follow moq-dev/moq#1968, which made the same switch in moq-native. Replace the `rustls_native_certs` root loading in both builders with the platform verifier on the crate's existing provider (`crypto::default_provider()`), so rind stays the default provider. Drop the `rustls-native-certs` dependency from both crates. Also drop quinn's and noq's `platform-verifier` feature, which nothing uses: it only enables `ClientConfig::try_with_platform_verifier`, which bypasses this crate's provider-neutral crypto adapter.

The FFI client does not use these builders and is handled in [FFI platform verifier](/quest/a1/ffi-platform-verifier.md). Android needs JNI initialization that only that quest provides. Here, document in the builders that on Android the platform verifier requires app initialization.
The FFI client does not use these builders; it already verifies with the platform verifier and initializes it on Android from its own `JNI_OnLoad` (see `rs/web-transport-ffi/README.md`). Here, document in the builders that on Android the platform verifier requires app initialization.

Coordinate with [Noq on rind](/quest/a1/rind/noq.md), which rewrites the noq client builder; whichever lands second resolves the conflict. Update the crate READMEs and doc comments that describe `with_system_roots()`.

## Related

- [Issue #506](https://github.com/moq-dev/web-transport/issues/506) - platform verifier support; closed by the FFI quest
- [FFI platform verifier](/quest/a1/ffi-platform-verifier.md) - same switch for the language bindings
- [Issue #506](https://github.com/moq-dev/web-transport/issues/506) - platform verifier support; closed by the FFI platform verifier PR
16 changes: 15 additions & 1 deletion rs/web-transport-ffi/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ edition = "2021"
keywords = ["webtransport", "quic", "http3", "uniffi"]
categories = ["network-programming", "web-programming"]

[package.metadata.cargo-shear]
# A version pin only; see the Android dependencies below.
ignored = ["rustls-platform-verifier-android"]

[lib]
name = "web_transport_ffi"
crate-type = ["staticlib", "cdylib"]
Expand All @@ -23,14 +27,24 @@ bytes = "1"
http = "1"
quinn = { version = "0.11", default-features = false, features = ["runtime-tokio"] }
rustls = { version = "0.23", default-features = false, features = ["std"] }
rustls-native-certs = "0.8"
rustls-platform-verifier = "0.7"
thiserror = "2"
tokio = { version = "1", features = ["rt-multi-thread", "sync", "time", "macros"] }
tokio-util = "0.7"
uniffi = { version = "0.32", features = ["cli"] }
url = "2"
web-transport-quinn = { workspace = true }

[target.'cfg(target_os = "android")'.dependencies]
# The platform verifier reaches Android's trust store through JNI (see `android.rs`).
jni = "0.22"
# Pins the Kotlin component that kt/ bundles (`rustlsPlatformVerifier.version` in
# kt/gradle.properties); both must change together.
rustls-platform-verifier-android = "=0.2.0"
tracing = "0.1"
# Trusted until the platform verifier is initialized.
webpki-roots = "1"

[build-dependencies]
uniffi = { version = "0.32", features = ["build"] }

Expand Down
24 changes: 24 additions & 0 deletions rs/web-transport-ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,30 @@ Socket setup errors are returned by `connect`. `close` and final client drop
close both sockets, including pending connections. Call `close` before awaiting
`wait_closed` to prevent new connections while both sockets drain.

## Certificate verification

With neither `server_certificate_hashes` nor `no_cert_verification`, clients verify
with [rustls-platform-verifier](https://github.com/rustls/rustls-platform-verifier)
on the crate's crypto provider, so the operating system's trust store decides on
every platform. On Linux, building such a client fails when no system CA
certificate can be loaded.

Android needs the application `Context`. The library exports `JNI_OnLoad`, which
initializes the verifier from `ActivityThread.currentApplication()` when the JVM
loads it with `System.loadLibrary`; a failure is logged and never fails the load.
Each new client retries until initialization succeeds, and a client built before
then trusts the bundled webpki-roots and keeps them. The Kotlin AAR in `kt/`
handles this. If you package the Android library yourself:

- Load it with `System.loadLibrary("web_transport_ffi")` after the `Application`
exists and before building the first client. JNA alone does not run `JNI_OnLoad`.
- Add rustls-platform-verifier's Kotlin component,
`org.rustls:rustls-platform-verifier`, at the version of the
`rustls-platform-verifier-android` crate pinned in `Cargo.toml`, as described in
[its Android setup](https://github.com/rustls/rustls-platform-verifier#android).
- Keep it from shrinking with
`-keep, includedescriptorclasses class org.rustls.platformverifier.** { *; }`.

## Session lifetime

Keep the Session object alive while using its streams. Streams do not retain the Session: releasing the final Session reference closes the connection, even if stream objects remain. A helper that returns streams must also return or retain their Session. An explicit close already underway keeps its bounded graceful close after the Session is released; awaiting closure lets it finish, but timeout or cancellation can prevent capsule delivery.
Expand Down
Loading
Loading