How to enable Post-Quantum Cryptography in Network Connector

Use this guide to enable Post-Quantum Cryptography (PQC) on your Network Connector after upgrading Segura® Platform to v4.2.2 or later.

Requirements

Segura® Platform upgraded to v4.2.2 or later.
Access to the CLI on the primary Segura® instance.
Access to the CLI on each secondary Segura® instance (if applicable).
Access to Segura® administration SSH to run the orbit CLI commands.
Access to the docker-compose.yaml file of the Network Connector agent you want to enable PQC on.
TCP port 51446 opened on all customer-side network devices (firewalls, ACLs) between the agent and the Segura® vaults. This is required only for PQC-enabled agents. Agents using classical encryption continue to use TCP port 51445 and are not affected

Info

TCP port 51446 is automatically released in the Segura® VM firewall during the upgrade. The manual step described above refers to the customer's own network infrastructure.

Steps

Step 1: Run the setup command on the primary instance

Connect to the CLI of the primary Segura® instance.
Run the following command:

orbit network-connector setup

This installs the snc-server-quantum service in systemd. The command must complete successfully before proceeding.

Warning

This step cannot be skipped or automated during the upgrade process for technical reasons. PQC will not be available until the snc-server-quantum service is installed.

Step 2: Run the setup command on each secondary instance

If your environment has secondary Segura® instances, repeat this step for each one.

Connect to the CLI of a secondary Segura® instance.
Run the following command:

orbit network-connector setup --secondary

Repeat for each remaining secondary instance.

Step 3: Enable PQC on the agent

On the host running the Network Connector agent, open the docker-compose.yaml file.
Locate the environment section under the senhasegura-network-connector-agent service.
Add the SENHASEGURA_QUANTUM_ENABLED variable and set its value to "true":

services:
  senhasegura-network-connector-agent:
    image: "registry.senhasegura.io/network-connector/agent-v2:latest"
    restart: unless-stopped
    networks:
      - senhasegura-network-connector
    environment:
      SENHASEGURA_FINGERPRINT: "CHANGE_ME"
      SENHASEGURA_AGENT_PORT: "CHANGE_ME"
      SENHASEGURA_ADDRESSES: "CHANGE_ME"
      SENHASEGURA_AGENT_SECONDARY: "false"
      SENHASEGURA_QUANTUM_ENABLED: "true"
networks:
  senhasegura-network-connector:
    driver: bridge

Info

The default value of SENHASEGURA_QUANTUM_ENABLED is "false". Agents without this variable, or with the value set to "false", continue to use classical encryption on TCP port 51445.

Save the file.
Restart the agent container to apply the change:

docker compose pull
docker compose up -d

Warning

After upgrading the Segura® Platform and running the setup command, you must also update the agent to a version compatible with PQC. An agent running an older image version will not be able to establish a PQC channel even if SENHASEGURA_QUANTUM_ENABLED is set to "true".

Confirm your results

To verify that PQC is active on the agent, check the agent logs. The Network Connector logs display a connection status Table Report every 5 seconds, showing the current connection mode for each active channel.

Look for an entry that indicates the PQC mode is active.

Confirm that the Table Report shows the following values for the target remote:

Column	Expected value
`MODE`	`QUANTUM`
`STEP`	`CONNECTED`
`BOOTSTRAP`	`DONE`
`HEALTHZ`	`UP (Xms)`
`LAST ERROR`	(empty)

If MODE shows a value other than QUANTUM, or HEALTHZ remains PENDING, PQC has not been established. Check the troubleshooting section.

Troubleshooting

Problem: The agent cannot connect after enabling PQC.
- Solution: Verify that TCP port 51446 is open on all network devices between the agent and the Segura® vaults. If the port is blocked, the agent cannot establish a PQC channel. Check whether the orbit network-connector setup command completed successfully on the primary instance.
Problem: The snc-server-quantum service is not found after running orbit network-connector setup.
- Solution: Confirm that the Segura® Platform was upgraded to v4.2.2 or later before running the command. The service is only available from this version onwards.
Problem: You need to revert PQC and return to classical encryption.
- Solution: Set SENHASEGURA_QUANTUM_ENABLED back to "false" in docker-compose.yaml and restart the agent. No server-side steps are required. The agent will reconnect using classical encryption on TCP port 51445.
Problem: The agent is configured for PQC but keeps logging connection errors and never connects.
- Solution: The agent does not fall back to classical encryption when PQC is enabled. Verify that the orbit network-connector setup command was run successfully on the primary instance (and --secondary on all secondary instances), and that the agent image has been updated to a PQC-compatible version. Also confirm that TCP port 51446 is reachable from the agent host.