Class SpkiPinningClientTlsStrategy

java.lang.Object

org.apache.hc.client5.http.ssl.AbstractClientTlsStrategy

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.
private static final class	SpkiPinningClientTlsStrategy.ByteArrayKey	Byte-array key with constant-time equality for use in sets/maps.
private static final class	SpkiPinningClientTlsStrategy.Rule	Match rule for a host or single-label wildcard.

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	PIN_PREFIX
private final List<SpkiPinningClientTlsStrategy.Rule>	rules
private static final int	SHA256_LEN

Constructor Summary

Constructors

Modifier	Constructor	Description
private	SpkiPinningClientTlsStrategy(SSLContext sslContext, List<SpkiPinningClientTlsStrategy.Rule> rules)

Method Summary

Modifier and Type	Method	Description
private static byte[][]	chainSpkiSha256(SSLSession session)
private static String	configuredPinsFor(List<SpkiPinningClientTlsStrategy.Rule> rules)
(package private) void	enforcePins(String hostname, SSLSession sslSession)	Enforce SPKI pins for the given hostname and session.
private List<SpkiPinningClientTlsStrategy.Rule>	matchedRules(String host)
static SpkiPinningClientTlsStrategy.Builder	newBuilder(SSLContext sslContext)	Create a new builder.
private static String	peerPinsForLog(byte[][] hashes)
protected void	verifySession(String hostname, SSLSession sslSession)	Invoked after the default trust and hostname checks.

Methods inherited from class DefaultClientTlsStrategy

applyParameters, createDefault, createSystemDefault, createTlsDetails, getDefault, getSystemDefault

Methods inherited from class AbstractClientTlsStrategy

initializeEngine, initializeSocket, toEscapedString, upgrade, upgrade, upgrade, verifySession

Methods inherited from class Object

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

Field Details

PIN_PREFIX

private static final String PIN_PREFIX

See Also:

• Constant Field Values

SHA256_LEN

private static final int SHA256_LEN

See Also:

• Constant Field Values

rules

private final List<SpkiPinningClientTlsStrategy.Rule> rules

Constructor Details

SpkiPinningClientTlsStrategy

private SpkiPinningClientTlsStrategy(SSLContext sslContext,
 List<SpkiPinningClientTlsStrategy.Rule> rules)

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.

Overrides:

verifySession in class AbstractClientTlsStrategy

Throws:

SSLException

enforcePins

void enforcePins(String hostname,
 SSLSession sslSession)
          throws SSLException

Enforce SPKI pins for the given hostname and session. Package-private for testing.

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

matchedRules

private List<SpkiPinningClientTlsStrategy.Rule> matchedRules(String host)

chainSpkiSha256

private static byte[][] chainSpkiSha256(SSLSession session)
                                 throws SSLException

Throws:

SSLException

configuredPinsFor

private static String configuredPinsFor(List<SpkiPinningClientTlsStrategy.Rule> rules)

peerPinsForLog

private static String peerPinsForLog(byte[][] hashes)