Skip to content

HTTP Connection Cache Pix

Pix HTTP requests use their own connection cache, separate from the HSM's session cache. Opening a new connection means repeating the TLS handshake, and every complete handshake uses the private key stored in the HSM; reusing the connection avoids both of these costs.

The cache stores HTTP connections that have already been established with the peer. Each request for a handle in standard mode borrows a connection and returns it when it finishes, so that the number of connections reflects the application’s actual concurrency, rather than the number of open handles. Handles created with DN_PIX_NO_CACHE are not included in the cache.

Features of the HTTP connection cache:

  1. Intra-process: Just like the session cache, caching is done on a per-process basis. Two applications on the same machine do not share connections;
  2. One connection per entry: Each cache entry holds exactly one connection, so the number of entries is equal to the number of open connections with the peer;
  3. MRU Selection: Among the available connections, the one used most recently is selected. This keeps a small set of connections active and allows the others to time out due to inactivity, rather than spreading the traffic across all of them.

Reuse

A connection is reused only by an equivalent request. The following are considered:

  • the identity authenticated in the HSM;
  • the identifiers for the private key, the certificate, and the peer's certificate chain;
  • the destination (host:port).

Since the destination is part of the criteria, the same handle used with two different endpoints maintains a separate connection for each one, rather than reconnecting each time it switches between them.

TLS Session Resumption

When opening a new connection, the client attempts to resume the TLS session from another equivalent connection, which avoids a full handshake.Session resumption is performed usinga session ID: session tickets (RFC 5077) are disabled on the HTTP client, so resumption only occurs when the peer maintains a session ID cache on the server side.

A resumed handshake does not send a CertificateVerify request and, as a result, does not use the HSM's private key. This is what makes reconnection efficient, and it is the observable difference between the handshake and signature counters on the HSM.

Idleness and Limits

A connection that has been idle for longer than the idle TTL is closed during the next scan. The time is configured by the HSM_PIX_POOL_IDLE_TTL environment variable.

The maximum number of connections is configured by HSM_PIX_POOL_MAX_HANDLES. Since there is one connection per entry, this is the actual upper limit on the number of simultaneous connections presented to the peer. The default is unlimited, which causes the cache to grow in line with application concurrency; when a configured limit is reached, the request fails rather than opening a connection beyond the limit.

Both variables can also be adjusted at runtime using DPIXSetCacheParam().

Certificate Exchange

The HSM objects (private key, certificate, and chain) are read during the handshake. An already open connection does not re-read them; therefore, a scheduled exchange only takes effect when the connection is reestablished.

To avoid waiting, clear the cache with DPIXSetCacheParam() using PIXCP_CLEAR: idle connections are closed immediately, and those in use are closed at the end of the current request. The next request opens a new connection and re-reads the objects.

Counters

DPIXGetCacheParam() with PIXCP_STATS returns the cache counters, which are useful for setting the limit and tracking the cost of connections: active connections, connections in use, the maximum ever reached, connections closed due to inactivity, TLS handshakes, and signatures generated on the HSM.

For details on configuration, see the "Sessions" topic — Pix.