OkHttp TLS

Approachable APIs for using TLS.

A HeldCertificate is a certificate and its private key. Use the builder to create a self-signed certificate that a test server can use for HTTPS:

HeldCertificate localhostCertificate = new HeldCertificate.Builder()
    .addSubjectAlternativeName("localhost")
    .build();

HandshakeCertificates keeps the certificates for a TLS handshake. Use its builder to define which certificates the HTTPS server returns to its clients. The returned instance can create an SSLSocketFactory that implements this policy:

HandshakeCertificates serverCertificates = new HandshakeCertificates.Builder()
    .heldCertificate(localhostCertificate)
    .build();
MockWebServer server = new MockWebServer();
server.useHttps(serverCertificates.sslSocketFactory(), false);

HandshakeCertificates also works for clients where its job is to define which root certificates to trust. In this simplified example we trust the server's self-signed certificate:

HandshakeCertificates clientCertificates = new HandshakeCertificates.Builder()
    .addTrustedCertificate(localhostCertificate.certificate())
    .build();
OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(clientCertificates.sslSocketFactory(), clientCertificates.trustManager())
    .build();

With a server that holds a certificate and a client that trusts it we have enough for an HTTPS handshake. The best part of this example is that we don't need to make our test code insecure with a a fake HostnameVerifier or X509TrustManager.

Certificate Authorities

The above example uses a self-signed certificate. This is convenient for testing but not representative of real-world HTTPS deployment. To get closer to that we can use HeldCertificate to generate a trusted root certificate, an intermediate certificate, and a server certificate. We use certificateAuthority(int) to create certificates that can sign other certificates. The int specifies how many intermediate certificates are allowed beneath it in the chain.

HeldCertificate rootCertificate = new HeldCertificate.Builder()
    .certificateAuthority(1)
    .build();

HeldCertificate intermediateCertificate = new HeldCertificate.Builder()
    .certificateAuthority(0)
    .signedBy(rootCertificate)
    .build();

HeldCertificate serverCertificate = new HeldCertificate.Builder()
    .addSubjectAlternativeName("localhost")
    .signedBy(intermediateCertificate)
    .build();

To serve this configuration the server needs to provide its clients with a chain of certificates starting with its own and including everything up-to but not including the root. We don't need to include root certificates because the client already has them.

HandshakeCertificates serverHandshakeCertificates = new HandshakeCertificates.Builder()
    .heldCertificate(serverCertificate, intermediateCertificate.certificate())
    .build();

The client only needs to know the trusted root certificate. It checks the server's certificate by validating the signatures within the chain.

HandshakeCertificates clientCertificates = new HandshakeCertificates.Builder()
    .addTrustedCertificate(rootCertificate.certificate())
    .build();
OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(clientCertificates.sslSocketFactory(), clientCertificates.trustManager())
    .build();

Client Authentication

The above scenario is representative of most TLS set ups: the client uses certificates to validate the identity of a server. The converse is also possible. Here we create a server that authenticates a client and a client that authenticates a server.

// Create the root for client and server to trust. We could also use different roots for each!
HeldCertificate rootCertificate = new HeldCertificate.Builder()
    .certificateAuthority(0)
    .build();

// Create a server certificate and a server that uses it.
HeldCertificate serverCertificate = new HeldCertificate.Builder()
    .commonName("ingen")
    .addSubjectAlternativeName(server.getHostName())
    .signedBy(rootCertificate)
    .build();
HandshakeCertificates serverCertificates = new HandshakeCertificates.Builder()
    .addTrustedCertificate(rootCertificate.certificate())
    .heldCertificate(serverCertificate)
    .build();
MockWebServer server = new MockWebServer();
server.useHttps(serverCertificates.sslSocketFactory(), false);
server.requestClientAuth();
server.enqueue(new MockResponse());

// Create a client certificate and a client that uses it.
HeldCertificate clientCertificate = new HeldCertificate.Builder()
    .commonName("ianmalcolm")
    .signedBy(rootCertificate)
    .build();
HandshakeCertificates clientCertificates = new HandshakeCertificates.Builder()
    .addTrustedCertificate(rootCertificate.certificate())
    .heldCertificate(clientCertificate)
    .build();
OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(clientCertificates.sslSocketFactory(), clientCertificates.trustManager())
    .build();

// Connect 'em all together. Certificates are exchanged in the handshake.
Call call = client.newCall(new Request.Builder()
    .url(server.url("/"))
    .build());
Response response = call.execute();
System.out.println(response.handshake().peerPrincipal());
RecordedRequest recordedRequest = server.takeRequest();
System.out.println(recordedRequest.getHandshake().peerPrincipal());

This handshake is successful because each party has prearranged to trust the root certificate that signs the other party's chain.

Well-Known Certificate Authorities

In these examples we've prearranged which root certificates to trust. But for regular HTTPS on the Internet this set of trusted root certificates is usually provided by default by the host platform. Such a set typically includes many root certificates from well-known certificate authorities like Entrust and Verisign.

This is the behavior you'll get with your OkHttpClient if you don't specifically configure HandshakeCertificates. Or you can do it explicitly with addPlatformTrustedCertificates():

HandshakeCertificates clientCertificates = new HandshakeCertificates.Builder()
    .addPlatformTrustedCertificates()
    .build();
OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(clientCertificates.sslSocketFactory(), clientCertificates.trustManager())
    .build();

PEM files

You can encode a HeldCertificate in PEM format:

HeldCertificate heldCertificate = ...
System.out.println(heldCertificate.certificatePem())

You can also do so with the private key. Be careful with these!

HeldCertificate heldCertificate = ...
System.out.println(heldCertificate.privateKeyPkcs8Pem())

Recommendations

Typically servers need a held certificate plus a chain of intermediates. Servers only need the private key for their own certificate. The chain served by a server doesn't need the root certificate.

The trusted roots don't need to be the same for client and server when using client authentication. Clients might rely on the platform certificates and servers might use a private organization-specific certificate authority.

By default HeldCertificate instances expire after 24 hours. Use duration() to adjust.

By default server certificates need to identify which hostnames they're trusted for. You may add as many as necessary with addSubjectAlternativeName(). This mechanism also supports a very limited form of wildcards *.example.com where the * must be first and doesn't match nested subdomains.

By default certificates use fast and secure 256-bit ECDSA keys. For interoperability with very old clients use HeldCertificate.Builder.rsa2048().

Download

implementation("com.squareup.okhttp3:okhttp-tls:4.12.0")

okhttp

Rrenovate[bot]Update junit5 monorepo (#8464)4 месяца назадc85c3d