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)的服务器是必需的:
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:
val apacheClient = HttpClient(Apache5) {
engine {
sslContext = SslSettings.getSslContext()
}
}Java
对于 Java 客户端,请在 config {} 块中使用 sslContext() 函数配置 SSLContext:
val javaClient = HttpClient(Java) {
engine {
config {
sslContext(SslSettings.getSslContext())
}
}
}Jetty
对于 Jetty 客户端,请使用 sslContextFactory 形参创建 SslContextFactory 实例并传入 SSLContext:
val jettyClient = HttpClient(Jetty) {
engine {
sslContextFactory = SslContextFactory.Client().apply {
sslContext = SslSettings.getSslContext()
}
}
}JVM 与 Android
所有面向 Android 的引擎均使用网络安全配置。
CIO
CIO 引擎允许你在 https {} 块内配置 HTTPS 设置。在该块内,你可以访问 TLSConfigBuilder 提供的 TLS 形参。
在以下示例中,使用 TrustManager 实例来信任服务器证书,并通过 addKeyStore() 函数添加客户端证书:
val cioClient = HttpClient(CIO) {
engine {
https {
trustManager = SslSettings.getTrustManager()
addKeyStore(SslSettings.getKeyStore(), "foobar".toCharArray())
}
}
}sockets-client-tls 示例展示了如何信任所有证书。该方法应仅用于开发目的。
Android
Android 引擎使用 sslManager 属性来配置 SSL 设置。该属性接受 HttpsURLConnection 作为形参,允许你传入 SSLSocketFactory:
val androidClient = HttpClient(Android) {
engine {
sslManager = { httpsURLConnection ->
httpsURLConnection.sslSocketFactory = SslSettings.getSslContext()?.socketFactory
}
}
}OkHttp
要为 OkHttp 客户端引擎配置 SSL,请在 config {} 块内将 SSLSocketFactory 和 X509TrustManager 传递给 sslSocketFactory() 函数:
val okHttpClient = HttpClient(OkHttp) {
engine {
config {
sslSocketFactory(SslSettings.getSslContext()!!.socketFactory, SslSettings.getTrustManager())
}
}
}Darwin
要为 Darwin 引擎配置受信任的证书,请使用 CertificatePinner。
