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

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

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor	Description
private	SpkiPinningClientTlsStrategy(javax.net.ssl.SSLContext sslContext, java.util.List<SpkiPinningClientTlsStrategy.Rule> rules)

Method Summary

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

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

applyParameters, createDefault, createSystemDefault, createTlsDetails, getDefault, getSystemDefault

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

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

Methods inherited from class java.lang.Object

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

Field Detail

PIN_PREFIX

private static final java.lang.String PIN_PREFIX

See Also:

Constant Field Values

SHA256_LEN

private static final int SHA256_LEN

See Also:

Constant Field Values

rules

private final java.util.List<SpkiPinningClientTlsStrategy.Rule> rules

Constructor Detail

SpkiPinningClientTlsStrategy

private SpkiPinningClientTlsStrategy(javax.net.ssl.SSLContext sslContext,
                                     java.util.List<SpkiPinningClientTlsStrategy.Rule> rules)

Method Detail

verifySession

protected void verifySession(java.lang.String hostname,
                             javax.net.ssl.SSLSession sslSession)
                      throws javax.net.ssl.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:

javax.net.ssl.SSLException

enforcePins

void enforcePins(java.lang.String hostname,
                 javax.net.ssl.SSLSession sslSession)
          throws javax.net.ssl.SSLException

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

Throws:

javax.net.ssl.SSLException

newBuilder

public static SpkiPinningClientTlsStrategy.Builder newBuilder(javax.net.ssl.SSLContext sslContext)

Create a new builder.

Parameters:

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

Returns:

builder

matchedRules

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

chainSpkiSha256

private static byte[][] chainSpkiSha256(javax.net.ssl.SSLSession session)
                                 throws javax.net.ssl.SSLException

Throws:

javax.net.ssl.SSLException

configuredPinsFor

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

peerPinsForLog

private static java.lang.String peerPinsForLog(byte[][] hashes)