kmp-tls-pinning

KMP TLS / SPKI pinning for a shared Ktor client

Pin the server's public key (SPKI SHA-256) for a Ktor client shared in commonMain. Grounded in Ktor 3.5.x (ktor-client-okhttp, ktor-client-darwin), OkHttp's CertificatePinner, and Apple's Security framework.

• The client is shared, the trust mechanism is not. A KMP Ktor client uses a different engine per target — OkHttp on Android, Darwin (NSURLSession) on iOS — so pinning is applied per engine. Same pin set, two mechanisms, joined with expect/actual (see expect-actual).
• Builds on kmp-networking (the shared HttpClient factory). iOS SecTrust/SPKI details live in swift-security; the Android declarative alternative in mobile-security.

Contents

• Why per-platform
• The pin set (commonMain)
• expect/actual boundary
• Android — OkHttp engine
• iOS — Darwin engine
• Pin hygiene & rotation
• Testing pinning
• Checklist
• References: references/pin-extraction.md (openssl, custom Darwin handler, Android NSC XML)

Why per-platform

HttpClient(engine) { engine { … } } exposes an engine-specific config type (OkHttpConfig, DarwinClientEngineConfig). From a HttpClientConfig<*> you can only reach the base HttpClientEngineConfig — not config { certificatePinner() } or handleChallenge { }. So an HttpClientConfig<*>.installPinning() extension cannot reach the pinning APIs; the boundary must sit where the concrete engine type is known. Use an expect/actual factory instead.

The pin set (commonMain)

One host → its pins, expressed once in shared code. A pin is sha256/ + base64 of SHA-256(DER SubjectPublicKeyInfo); both engines accept exactly this string form.

// commonMain/kotlin/network/pinning/PinSet.kt
data class PinSet(
    /** host pattern (e.g. "api.example.com" or "*.example.com") -> pins ("sha256/…") */
    val pins: Map<String, List<String>>,
) {
    init {
        require(pins.values.all { it.size >= 2 }) { "Keep >=2 pins per host (current + backup)." }
        require(pins.values.flatten().all { it.startsWith("sha256/") || it.startsWith("sha1/") }) {
            "Pins must start with 'sha256/' or 'sha1/'."
        }
    }
}

val ProductionPins = PinSet(
    mapOf(
        "api.example.com" to listOf(
            "sha256/47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=", // current leaf/intermediate SPKI
            "sha256/633lt352PKRXbOwf4xSEa1M517scpD3l+2VknLXvGWk=", // OFFLINE backup key SPKI
        ),
    ),
)