Client Plugin

Ktor 用戶端中的 SSL

程式碼範例： client-ssl-config

要在 Ktor 用戶端中配置 SSL，您需要自訂用戶端所使用 引擎的配置。 在本主題中，我們將向您展示如何為針對 JVM 和 Android 的引擎加入 SSL 憑證。

若要了解如何使用 Ktor API 產生自我簽署憑證，請參閱 產生自我簽署憑證。

載入 SSL 設定

在本主題中，Ktor 用戶端將使用從為伺服器產生的現有 KeyStore 檔案 (keystore.jks) 載入的憑證。 鑒於不同的引擎使用不同的 JSSE API 來配置 SSL（例如，Apache 使用 SSLContext 或 Jetty 使用 TrustManager），我們需要有能力取得對應的 SSL 配置。下方的程式碼片段建立了 SslSettings 物件，該物件從現有的 KeyStore 檔案 (keystore.jks) 載入憑證，並提供載入 SSL 配置的函式：

object SslSettings {
    fun getKeyStore(): KeyStore {
        val keyStoreFile = FileInputStream("keystore.jks")
        val keyStorePassword = "foobar".toCharArray()
        val keyStore: KeyStore = KeyStore.getInstance(KeyStore.getDefaultType())
        keyStore.load(keyStoreFile, keyStorePassword)
        return keyStore
    }

    fun getTrustManagerFactory(): TrustManagerFactory? {
        val trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm())
        trustManagerFactory.init(getKeyStore())
        return trustManagerFactory
    }

    fun getSslContext(): SSLContext? {
        val sslContext = SSLContext.getInstance("TLS")
        sslContext.init(null, getTrustManagerFactory()?.trustManagers, null)
        return sslContext
    }

    fun getTrustManager(): X509TrustManager {
        return getTrustManagerFactory()?.trustManagers?.first { it is X509TrustManager } as X509TrustManager
    }
}

在 Ktor 中配置 SSL

在本節中，我們將了解如何為不同的引擎配置 SSL。 您可以在這裡找到完整的範例：client-ssl-config。

JVM

Apache

要為 Apache 啟用 SSL，您需要傳遞 SSLContext：

val apacheClient = HttpClient(Apache5) {
    engine {
        sslContext = SslSettings.getSslContext()
    }
}

Java

對於 Java 用戶端，請將 SSLContext 傳遞給 config 區塊內的 sslContext 函式：

val javaClient = HttpClient(Java) {
    engine {
        config {
            sslContext(SslSettings.getSslContext())
        }
    }
}

Jetty

對於 Jetty，您需要建立 SslContextFactory 的執行個體並傳遞 SSLContext：

val jettyClient = HttpClient(Jetty) {
    engine {
        sslContextFactory = SslContextFactory.Client().apply {
            sslContext = SslSettings.getSslContext()
        }
    }
}

JVM 和 Android

所有針對 Android 的引擎都使用 網路安全性配置。

CIO

CIO 引擎允許您在 https 區塊內配置 HTTPS 設定。 在此區塊內，您可以存取由 TLSConfigBuilder 提供的 TLS 參數。 在我們的範例中，使用 TrustManager 執行個體來配置憑證：

val cioClient = HttpClient(CIO) {
    engine {
        https {
            trustManager = SslSettings.getTrustManager()
        }
    }
}

sockets-client-tls 範例展示了如何信任所有憑證。 這種方法應僅用於開發目的。

Android

Android 引擎使用 sslManager 屬性來配置 SSL 設定。 此屬性接受 HttpsURLConnection 作為參數，允許您傳遞 SSLSocketFactory：

val androidClient = HttpClient(Android) {
    engine {
        sslManager = { httpsURLConnection ->
            httpsURLConnection.sslSocketFactory = SslSettings.getSslContext()?.socketFactory
        }
    }
}

OkHttp

要配置 OkHttp 使用 SSL，您需要將 SSLSocketFactory 和 X509TrustManager 傳遞給 sslSocketFactory 函式：

val okHttpClient = HttpClient(OkHttp) {
    engine {
        config {
            sslSocketFactory(SslSettings.getSslContext()!!.socketFactory, SslSettings.getTrustManager())
        }
    }
}

Darwin

要為 Darwin 引擎配置受信任的憑證，請使用 CertificatePinner。