Identity/authentication options. Missing fields fall back to HsmClientConfig.
mTLS options, if applicable.
One-time override of HSM_SESSION_POOL_QUEUE_TIMEOUT_MS
for this specific call.
An internal reconnection also invalidates the handle, just as if a
business call had failed—even if the operation itself was
successful and returned the correct result. Currently, this happens in
every symmetric operation whose payload exceeds MAX_FAST_SYM_OP_SEG
(1200 bytes): cryptography.encrypt/decrypt/cipher falls into
streaming mode, which terminates the connection and causes the internal HSM to open another one
behind the scenes—a connection that the pool does not control. Returning the original connection
(which has already been abandoned) to the pool would poison the next consumer, so the handle is
terminated on the spot and the session discarded. In practice: treat large
symmetric operations on a pooled handle as potentially single-use—
the next call on this handle will result inan
`exceptions.SessionInvalidatedError`; open a new handle. For
large, repeated symmetric loads, `hsm.connect() ` (dedicated
connection) remains the appropriate approach.
exceptions.HsmOptionError - Host missing or invalid, or no
authentication mode resolved (same validation as hsm.connect()).
exceptions.SessionPoolQueueFullError - The pool queue has reached its limit.
exceptions.SessionPoolQueueTimeoutError - Waited in the queue beyond the timeout limit.
exceptions.SessionPoolShutdownError - The pool for this identity is being drained.
Sample Code: Connecting to the HSM Using a Session Pool
Obtains a handle with a session borrowed from the identity key pool (host, port, authentication identity, content hash of the mTLS material, if present). The pool is created on demand, with eager warm-up to the configured minimum.
The handle has the same public form as
Hsm—it is not a new type. It represents one session that is borrowed for the entire lifetime of the handle. There is no internal concurrency within a handle; concurrency is achieved by opening multiple handles.The handle is permanently invalidated upon the first business call error: the underlying session is immediately discarded (never returned to the pool), and subsequent calls on this handle result in exceptions.SessionInvalidatedError (it never silently attempts to obtain a new session).
.disconnect()remains idempotent and safe to call on a handle that has already been invalidated.