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, 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
`static class` `SpkiPinningClientTlsStrategy.Builder` Builder for `SpkiPinningClientTlsStrategy`.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
`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, HttpContext context)` Upgrades the given plain socket and executes the TLS handshake over it.
`boolean` `upgrade(TransportSecurityLayer tlsSession, HttpHost host, SocketAddress localAddress, SocketAddress remoteAddress, Object attachment, Timeout handshakeTimeout)` Deprecated. use `upgrade(TransportSecurityLayer, NamedEndpoint, Object, Timeout, FutureCallback)`
`void` `upgrade(TransportSecurityLayer tlsSession, NamedEndpoint endpoint, Object attachment, Timeout handshakeTimeout, FutureCallback<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 Detail

#### 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(TransportSecurityLayer tlsSession,
                                       HttpHost host,
                                       SocketAddress localAddress,
                                       SocketAddress remoteAddress,
                                       Object attachment,
                                       Timeout handshakeTimeout)

Deprecated. use `upgrade(TransportSecurityLayer, NamedEndpoint, Object, Timeout, FutureCallback)`

Specified by:
  `upgrade` in interface `TlsStrategy`

#### upgrade

    public void upgrade(TransportSecurityLayer tlsSession,
                        NamedEndpoint endpoint,
                        Object attachment,
                        Timeout handshakeTimeout,
                        FutureCallback<TransportSecurityLayer> callback)

Specified by:
  `upgrade` in interface `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,
                             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`