Skip to content
Client Plugin

Ktor Client 中的 SSL

程式碼範例: client-ssl-config

若要在 Ktor 用戶端中設定 SSL,你需要自訂用戶端所使用引擎的配置。

在本文中,你將學習如何為以 JVM 和 Android 為目標的引擎新增 SSL 憑證。

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

載入 SSL 設定 ​

在本文中,Ktor 用戶端使用從為伺服器產生的現有 KeyStore 檔案 (keystore.jks) 載入的憑證。

鑑於每個引擎使用不同的 JSSE API 來設定 SSL(例如,Apache 使用 SSLContext,Jetty 使用 TrustManager),你需要具備取得相應 SSL 配置的能力。

下方的程式碼片段建立了 SslSettings 物件,該物件從現有的 KeyStore 檔案 (keystore.jks) 載入憑證,並提供用於載入 SSL 配置的函式。

同一個 KeyStore 用於信任伺服器憑證,並透過 KeyManagerFactory 提供用戶端憑證,這在設定了信任存放區(trust store)的伺服器中是必要的:

kotlin
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 getKeyManagerFactory(): KeyManagerFactory? {
        val keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm())
        keyManagerFactory.init(getKeyStore(), "foobar".toCharArray())
        return keyManagerFactory
    }

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

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

在 Ktor 中設定 SSL ​

SSL 配置因引擎而異。以下各節將介紹如何為各個引擎設定 SSL。

JVM ​

Apache 與 Apache5 ​

若要為 Apache 和 Apache 5 用戶端啟用 SSL,請使用 sslContext 參數來配置 SSLContext:

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

Java ​

對於 Java 用戶端,請在 config {} 區塊內使用 sslContext() 函式來配置 SSLContext:

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

Jetty ​

對於 Jetty 用戶端,請使用 sslContextFactory 參數建立 SslContextFactory 的執行個體並傳入 SSLContext:

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

JVM 與 Android ​

所有以 Android 為目標的引擎皆使用網路安全性設定。

CIO ​

CIO 引擎允許你在 https {} 區塊內設定 HTTPS 設定。 在此區塊內,你可以存取 TLSConfigBuilder 提供的 TLS 參數。

在以下範例中,使用 TrustManager 執行個體來信任伺服器憑證,並透過 addKeyStore() 函式新增用戶端憑證:

kotlin
val cioClient = HttpClient(CIO) {
    engine {
        https {
            trustManager = SslSettings.getTrustManager()
            addKeyStore(SslSettings.getKeyStore(), "foobar".toCharArray())
        }
    }
}

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

Android ​

Android 引擎使用 sslManager 屬性來配置 SSL 設定。 此屬性接受 HttpsURLConnection 作為參數,讓你可以傳入 SSLSocketFactory:

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

OkHttp ​

若要為 OkHttp 用戶端引擎配置 SSL,請在 config {} 區塊內的 sslSocketFactory() 函式中傳入 SSLSocketFactory 與 X509TrustManager:

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

Darwin ​

若要為 Darwin 引擎設定信任的憑證,請使用 CertificatePinner。