System OpenSSL: A Hard Prerequisite
Post-quantum TLS on a gateway node depends on the system OpenSSL. On every gateway node:
openssl version # expect OpenSSL 3.5.x or later
OpenSSL earlier than 3.5 does not support ML-DSA. Classic RSA/ECDSA certificates
are unaffected, but post-quantum ML-DSA certificates require system OpenSSL 3.5 or later on the node. In domestic-stack or offline environments, verify the OpenSSL version of the base image and ship it with the deployment package if necessary.
The client side likewise needs OpenSSL 3.5 or later (or another ML-DSA implementation) to complete a post-quantum handshake. See Verifying the Post Quantum TLS Handshake.
Placing the PKCS#11 Client Library
Required only for the HSM-managed path. Skip for the software key path.
Option 1 — pre-install on the node (common for domestic-stack and offline images): place
libcs_pkcs11_R3.so and cs_pkcs11_R3.cfg on the node or in the image, and set pkcs11_module_path in the HSM connection settings to the absolute path of that .so, for example /opt/utimaco/lib/libcs_pkcs11_R3.so.
Option 2 — upload once and let the product deliver it (recommended for multiple nodes):
upload the .so through the management console (Delivering PKCS11 Client Library). Each gateway node then downloads it, verifies its SHA-256 and writes it atomically to pkcs11_module_path, with no per-node manual work.
With either option, cs_pkcs11_R3.cfg and the CS_PKCS11_R3_CFG environment variable must be provided by the node side (pre-installed or injected by the deployment system). Delivery covers only the .so itself; see item 2 in Known Limitations and Considerations.
Client library delivery currently assumes the target architecture linux-x86-64.
Enabling the HTTPS Listener
In the gateway node configuration file (stoa.yaml), make sure the HTTPS listener is enabled and the node is bound to the right cluster.
gateway:
listen_addr: "0.0.0.0:6188" # plaintext port
tls_listen_addr: "0.0.0.0:8443" # HTTPS port — setting this enables dynamic-certificate T
LS
control_plane:
cluster_id: "<UUID of the cluster this node belongs to>"
node_name: "<node name>"
-
Setting tls_listen_addr enables HTTPS; certificates may arrive afterwards. While no certificate is present, handshakes for that SNI fail, but the node does not crash and the plaintext port is unaffected.
-
Certificates are hot-applied: once delivered, new connections use them immediately and in-flight connections are not interrupted. Changing tls_listen_addr itself requires restarting the node.
-
cluster_id determines which certificates and HSM settings the node receives — it must match the cluster you bind certificates to in Issuing Post-Quantum ML-DSA-65 Certificates.
Encryption Key Consistency (Critical)
Software private keys and HSM PINs are delivered as AES-256-GCM ciphertext keyed by STOA_ENCRYPTION_KEY. Every gateway node must be configured with exactly the same value as the management console:
export STOA_ENCRYPTION_KEY="<exactly the same 32-byte base64 value as the management console>"
If the value is missing or different, software-key certificates fail to decrypt and are
skipped (a warning is logged) and HTTPS for those certificates is unavailable. The PIN of HSM-source certificates also cannot be decrypted, so HSM login fails.
The deployment system should supply this key to all gateway nodes over a secure channel. Do not write it in clear text into the configuration file.
Ports
|
Port |
Purpose |
How to Override |
|---|---|---|
|
6188 |
Plaintext service port. |
gateway.listen_addr |
|
8443 |
HTTPS service port. |
gateway.tls_listen_addr |
|
9095 |
Node administrative endpoint, including the HSM connectivity test. |
STOA_ADMIN_PORT |
Ports