0
# Authentication and Security
1

2
Authentication handling, certificate pinning, TLS handshake management, and credential utilities.
3

4
## Capabilities
5

6
### Authenticator
7

8
Responds to HTTP authentication challenges (401/407 responses).
9

10
```java { .api }
11
public interface Authenticator {
12
    Request authenticate(Proxy proxy, Response response) throws IOException;
13
    Request authenticateProxy(Proxy proxy, Response response) throws IOException;
14
}
15
```
16

17
### CertificatePinner
18

19
Constrains trusted certificates by pinning specific certificate hashes.
20

21
```java { .api }
22
public final class CertificatePinner {
23
    public static final CertificatePinner DEFAULT;
24
    public static String pin(Certificate certificate);
25
    public void check(String hostname, List<Certificate> peerCertificates) throws SSLPeerUnverifiedException;
26
    public void check(String hostname, Certificate... peerCertificates) throws SSLPeerUnverifiedException;
27
}
28
```
29

30
### Credentials
31

32
Factory for HTTP authorization credentials.
33

34
```java { .api }
35
public final class Credentials {
36
    public static String basic(String userName, String password);
37
}
38
```
39

40
### Challenge
41

42
RFC 2617 authentication challenge from HTTP response.
43

44
```java { .api }
45
public final class Challenge {
46
    public Challenge(String scheme, String realm);
47
    public String getScheme();
48
    public String getRealm();
49
}
50
```
51

52
### Handshake
53

54
Record of TLS handshake with certificate chain information.
55

56
```java { .api }
57
public final class Handshake {
58
    public static Handshake get(SSLSession session);
59
    public static Handshake get(String cipherSuite, List<Certificate> peerCertificates, List<Certificate> localCertificates);
60
    public String cipherSuite();
61
    public List<Certificate> peerCertificates();
62
    public Principal peerPrincipal();
63
    public List<Certificate> localCertificates();
64
    public Principal localPrincipal();
65
}
66
```
67

68
**Usage Examples:**
69

70
```java
71
// Basic authentication
72
client.setAuthenticator(new Authenticator() {
73
    @Override
74
    public Request authenticate(Proxy proxy, Response response) {
75
        String credential = Credentials.basic("username", "password");
76
        return response.request().newBuilder()
77
            .header("Authorization", credential)
78
            .build();
79
    }
80
    
81
    @Override
82
    public Request authenticateProxy(Proxy proxy, Response response) {
83
        return null; // No proxy auth
84
    }
85
});
86

87
// Certificate pinning
88
CertificatePinner pinner = new CertificatePinner.Builder()
89
    .add("api.example.com", "sha1/ABC123...")
90
    .build();
91
client.setCertificatePinner(pinner);
92
```