0
# Security and TLS
1

2
TLS configuration, certificate management, and authentication handling in OkHttp.
3

4
## CertificatePinner
5

6
Constrains SSL connections to trusted certificates.
7

8
```kotlin { .api }
9
class CertificatePinner private constructor() {
10
    fun check(hostname: String, peerCertificates: List<Certificate>)
11
    fun findMatchingPins(hostname: String): List<Pin>
12
    
13
    class Builder {
14
        fun add(hostname: String, vararg pins: String): Builder
15
        fun build(): CertificatePinner
16
    }
17
    
18
    data class Pin(val hostname: String, val hashAlgorithm: String, val hash: ByteString)
19
    
20
    companion object {
21
        val DEFAULT: CertificatePinner
22
        fun pin(certificate: Certificate): String
23
        fun sha1Hash(certificate: Certificate): String  
24
        fun sha256Hash(certificate: Certificate): String
25
    }
26
}
27
```
28

29
## ConnectionSpec
30

31
Specifies configuration for HTTPS connections.
32

33
```kotlin { .api }
34
class ConnectionSpec private constructor() {
35
    val isTls: Boolean
36
    val tlsVersions: List<TlsVersion>?
37
    val cipherSuites: List<CipherSuite>?
38
    val supportsTlsExtensions: Boolean
39
    
40
    fun isCompatible(socket: SSLSocket): Boolean
41
    fun apply(sslSocket: SSLSocket, isFallback: Boolean)
42
    
43
    class Builder(modern: Boolean) {
44
        constructor(connectionSpec: ConnectionSpec)
45
        
46
        fun allEnabledTlsVersions(): Builder
47
        fun tlsVersions(vararg tlsVersions: TlsVersion): Builder  
48
        fun tlsVersions(tlsVersions: List<TlsVersion>): Builder
49
        fun allEnabledCipherSuites(): Builder
50
        fun cipherSuites(vararg cipherSuites: CipherSuite): Builder
51
        fun cipherSuites(cipherSuites: List<CipherSuite>): Builder
52
        fun supportsTlsExtensions(supportsTlsExtensions: Boolean): Builder
53
        fun build(): ConnectionSpec
54
    }
55
    
56
    companion object {
57
        val MODERN_TLS: ConnectionSpec
58
        val COMPATIBLE_TLS: ConnectionSpec  
59
        val CLEARTEXT: ConnectionSpec
60
    }
61
}
62
```
63

64
## Authenticator
65

66
Handles authentication challenges from web servers and proxies.
67

68
```kotlin { .api }
69
interface Authenticator {
70
    fun authenticate(route: Route?, response: Response): Request?
71
    
72
    companion object {
73
        val NONE: Authenticator
74
        val JAVA_NET_AUTHENTICATOR: Authenticator
75
    }
76
}
77
```
78

79
### Basic Authentication Example
80

81
```kotlin
82
val authenticator = Authenticator { route, response ->
83
    if (response.request.header("Authorization") != null) {
84
        null // Give up, we've already attempted to authenticate
85
    } else {
86
        val credential = Credentials.basic("username", "password")
87
        response.request.newBuilder()
88
            .header("Authorization", credential)
89
            .build()
90
    }
91
}
92

93
val client = OkHttpClient.Builder()
94
    .authenticator(authenticator)
95
    .build()
96
```