Como habilitar Criptografia Pós-Quântica (PQC) no Network Connector

Utilize este guia para habilitar a Criptografia Pós-Quântica (PQC) no seu Network Connector após atualizar a Plataforma Segura® para a versão v4.2.2 ou posterior.

Requisitos

Plataforma Segura® atualizada para a versão v4.2.2 ou posterior.
Acesso à CLI da instância primária do Segura®.
Acesso à CLI de cada instância secundária do Segura® (se aplicável).
Acesso SSH de administração do Segura® para executar os comandos da CLI orbit.
Acesso ao arquivo docker-compose.yaml do agente do Network Connector no qual você deseja habilitar a PQC.
Porta TCP 51446 aberta em todos os dispositivos de rede do cliente (firewalls, ACLs) entre o agente e os cofres do Segura®. Esse requisito se aplica apenas aos agentes com PQC habilitada. Agentes que utilizam criptografia clássica continuam usando a porta TCP 51445 e não são afetados.

Info

A porta TCP 51446 é liberada automaticamente no firewall da VM do Segura® durante a atualização. A etapa manual descrita acima se refere à infraestrutura de rede do próprio cliente.

Passos

Passo 1: execute o comando de configuração na instância primária

Conecte-se à CLI da instância primária do Segura®.
Execute o seguinte comando:

orbit network-connector setup

Esse comando instala o serviço snc-server-quantum no systemd. O comando deve ser concluído com sucesso antes de prosseguir.

Warning

Esta etapa não pode ser ignorada nem automatizada durante o processo de atualização por razões técnicas. A PQC não estará disponível até que o serviço snc-server-quantum seja instalado.

Passo 2: execute o comando de configuração em cada instância secundária

Se o seu ambiente possui instâncias secundárias do Segura®, repita este passo para cada uma delas.

Conecte-se à CLI de uma instância secundária do Segura®.
Execute o seguinte comando:

orbit network-connector setup --secondary

Repita o procedimento para cada instância secundária restante.

Passo 3: habilite a PQC no agente

No host onde o agente do Network Connector está sendo executado, abra o arquivo docker-compose.yaml.
Localize a seção environment dentro do serviço senhasegura-network-connector-agent.
Adicione a variável SENHASEGURA_QUANTUM_ENABLED e defina seu valor como "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

O valor padrão de SENHASEGURA_QUANTUM_ENABLED é "false". Agentes sem essa variável, ou com o valor definido como "false", continuam utilizando criptografia clássica na porta TCP 51445.

Salve o arquivo.
Reinicie o container do agente para aplicar a alteração:

docker compose pull
docker compose up -d

Warning

Após atualizar a Plataforma Segura® e executar o comando de configuração, você também deve atualizar o agente para uma versão compatível com PQC. Um agente em execução com uma versão de imagem mais antiga não conseguirá estabelecer um canal PQC, mesmo que SENHASEGURA_QUANTUM_ENABLED esteja definido como "true".

Confirme os resultados

Para verificar se a PQC está ativa no agente, consulte os logs do agente. Os logs do Network Connector exibem um relatório de status de conexão em formato de tabela a cada 5 segundos, mostrando o modo de conexão atual para cada canal ativo.

Procure por uma entrada que indique que o modo PQC está ativo.

Confirme que o relatório de tabela exibe os seguintes valores para o remote de destino:

Coluna	Valor esperado
`MODE`	`QUANTUM`
`STEP`	`CONNECTED`
`BOOTSTRAP`	`DONE`
`HEALTHZ`	`UP (Xms)`
`LAST ERROR`	(vazio)

Se MODE exibir um valor diferente de QUANTUM, ou se HEALTHZ permanecer como PENDING, a PQC não foi estabelecida. Consulte a seção de solução de problemas.

Solução de problemas

Problema: O agente não consegue se conectar após a habilitação da PQC.
- Solução: Verifique se a porta TCP 51446 está aberta em todos os dispositivos de rede entre o agente e os cofres do Segura®. Se a porta estiver bloqueada, o agente não conseguirá estabelecer um canal PQC. Verifique também se o comando orbit network-connector setup foi concluído com sucesso na instância primária.
Problema: O serviço snc-server-quantum não é encontrado após a execução do comando orbit network-connector setup.
- Solução: Confirme que a Plataforma Segura® foi atualizada para a versão v4.2.2 ou posterior antes de executar o comando. O serviço está disponível somente a partir dessa versão.
Problema: Você precisa reverter a PQC e retornar à criptografia clássica.
- Solução: Defina SENHASEGURA_QUANTUM_ENABLED de volta para "false" no arquivo docker-compose.yaml e reinicie o agente. Nenhuma etapa no servidor é necessária. O agente se reconectará utilizando criptografia clássica na porta TCP 51445.
Problema: O agente está configurado para PQC, mas continua registrando erros de conexão e nunca se conecta.
- Solução: O agente não realiza fallback para criptografia clássica quando a PQC está habilitada. Verifique se o comando orbit network-connector setup foi executado com sucesso na instância primária (e --secondary em todas as instâncias secundárias), e se a imagem do agente foi atualizada para uma versão compatível com PQC. Confirme também se a porta TCP 51446 está acessível a partir do host do agente.

Tópicos relacionados

Para entender os conceitos de PQC: Sobre a Criptografia Pós-Quântica no Network Connector
Para consultar o log de status de conexão: Log de status do Network Connector
Para procedimentos de atualização do agente: Como atualizar o agente do Network Connector
Para instalação do agente: Como instalar o Network Connector