Package org.apache.hc.client5.http.ssl

Class SpkiPinningClientTlsStrategy

java.lang.Object

org.apache.hc.client5.http.ssl.DefaultClientTlsStrategy

org.apache.hc.client5.http.ssl.SpkiPinningClientTlsStrategy

All Implemented Interfaces:

TlsSocketStrategy, org.apache.hc.core5.http.nio.ssl.TlsStrategy

@Contract(threading=IMMUTABLE)
public final class SpkiPinningClientTlsStrategy
extends DefaultClientTlsStrategy

SPKI pinning decorator for client-side TLS.

This strategy enforces one or more sha256/<base64(SPKI)> pins for a given host or single-label wildcard (e.g. *.example.com) after the standard trust manager and hostname verification succeed. Pins are matched against the SubjectPublicKeyInfo (SPKI) of any certificate in the peer chain.

Host matching is performed on the IDNA ASCII (Punycode) lowercase form. Wildcards are single-label only (e.g. *.example.com matches a.example.com but not a.b.example.com).

Warning: Certificate pinning increases operational risk. Always ship at least two pins (active + backup) and keep normal PKI + hostname verification enabled.

Thread-safety: immutable and thread-safe.

Since:

5.6

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	SpkiPinningClientTlsStrategy.Builder	Builder for SpkiPinningClientTlsStrategy.

Method Summary

Modifier and Type	Method	Description
protected void	initializeEngine(SSLEngine sslEngine)
protected void	initializeSocket(SSLSocket socket)
static SpkiPinningClientTlsStrategy.Builder	newBuilder(SSLContext sslContext)	Create a new builder.
SSLSocket	upgrade(Socket socket, String target, int port, Object attachment, org.apache.hc.core5.http.protocol.HttpContext context)	Upgrades the given plain socket and executes the TLS handshake over it.
boolean	upgrade(org.apache.hc.core5.reactor.ssl.TransportSecurityLayer tlsSession, org.apache.hc.core5.http.HttpHost host, SocketAddress localAddress, SocketAddress remoteAddress, Object attachment, org.apache.hc.core5.util.Timeout handshakeTimeout)	Deprecated. use TlsStrategy.upgrade(TransportSecurityLayer, NamedEndpoint, Object, Timeout, FutureCallback)
void	upgrade(org.apache.hc.core5.reactor.ssl.TransportSecurityLayer tlsSession, org.apache.hc.core5.net.NamedEndpoint endpoint, Object attachment, org.apache.hc.core5.util.Timeout handshakeTimeout, org.apache.hc.core5.concurrent.FutureCallback<org.apache.hc.core5.reactor.ssl.TransportSecurityLayer> callback)
protected void	verifySession(String hostname, SSLSession sslSession)	Invoked after the default trust and hostname checks.

Methods inherited from class org.apache.hc.client5.http.ssl.DefaultClientTlsStrategy

createDefault, createSystemDefault, getDefault, getSystemDefault

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

verifySession

protected void verifySession(String hostname,
 SSLSession sslSession)
                      throws SSLException

Invoked after the default trust and hostname checks. If one or more rules match the hostname, at least one pin must match any SPKI in the peer chain.

Throws:

SSLException

newBuilder

public static SpkiPinningClientTlsStrategy.Builder newBuilder(SSLContext sslContext)

Create a new builder.

Parameters:

sslContext - SSL context used for handshakes (trust + keys).

Returns:

builder

upgrade

@Deprecated
public boolean upgrade(org.apache.hc.core5.reactor.ssl.TransportSecurityLayer tlsSession,
 org.apache.hc.core5.http.HttpHost host,
 SocketAddress localAddress,
 SocketAddress remoteAddress,
 Object attachment,
 org.apache.hc.core5.util.Timeout handshakeTimeout)

Deprecated.

use TlsStrategy.upgrade(TransportSecurityLayer, NamedEndpoint, Object, Timeout, FutureCallback)

Specified by:

upgrade in interface org.apache.hc.core5.http.nio.ssl.TlsStrategy

upgrade

public void upgrade(org.apache.hc.core5.reactor.ssl.TransportSecurityLayer tlsSession,
 org.apache.hc.core5.net.NamedEndpoint endpoint,
 Object attachment,
 org.apache.hc.core5.util.Timeout handshakeTimeout,
 org.apache.hc.core5.concurrent.FutureCallback<org.apache.hc.core5.reactor.ssl.TransportSecurityLayer> callback)

Specified by:

upgrade in interface org.apache.hc.core5.http.nio.ssl.TlsStrategy

initializeEngine

protected void initializeEngine(SSLEngine sslEngine)

initializeSocket

protected void initializeSocket(SSLSocket socket)

upgrade

public SSLSocket upgrade(Socket socket,
 String target,
 int port,
 Object attachment,
 org.apache.hc.core5.http.protocol.HttpContext context)
                  throws IOException

Description copied from interface: TlsSocketStrategy

Upgrades the given plain socket and executes the TLS handshake over it.

Specified by:

upgrade in interface TlsSocketStrategy

Parameters:

socket - the existing plain socket

target - the name of the target host.

port - the port to connect to on the target host.

attachment - connect request attachment.

context - the actual HTTP context.

Returns:

socket upgraded to TLS.

Throws:

IOException