# Monetarie - Assinatura PIX e SPB via HSM RTM

Data: 2026-06-20
Status: substituído pela implementação correta em `pix` e `spb`
Referência atual: `docs/handoff/2026-06-21-rtm-hsm-pix-spb-validation.md`

Este plano permanece no repositório somente como histórico. A decisão arquitetural vigente é:

- O Core Bancário nunca assina mensagens TED, PIX, SPB, DICT, ICOM-SPI ou qualquer mensagem operacional de rede financeira BACEN.
- O Core publica intenções, comandos e eventos internos por NATS.
- A cabine PIX é responsável por assinaturas XMLDSig de SPI e DICT.
- A cabine SPB é responsável por assinatura C15, decifragem C14 de entrada e validações de mensagens SPB.
- O HSM RTM usado para mensagens BACEN deve ser configurado nas cabines PIX e SPB, não como caminho operacional do Core.

## Contexto

As chaves ICP-Brasil da Monetarie destinadas à operação financeira devem ficar protegidas no HSM da RTM. A aplicação não deve receber chave privada em arquivo, variável de ambiente ou secret textual para assinar mensagens BACEN.

O contrato público de teste da Ecoscard/RTM foi validado em `http://200.160.162.200:63351/index.html`, no Swagger `/swagger/v1/swagger.json` e na documentação TR-31 em `/help/tr31-help-v1.html`.

## Implementação vigente

PIX:

- `pix/backend/apps/shared/lib/shared/crypto/rtm_hsm.ex`
- `pix/backend/apps/shared/lib/shared/crypto/rtm_hsm/client.ex`
- `pix/backend/apps/shared/lib/shared/crypto/xml_signer.ex`

SPB:

- `spb/services/bacen_gateway/lib/bacen_gateway/crypto/rtm_hsm.ex`
- `spb/services/bacen_gateway/lib/bacen_gateway/crypto/rtm_hsm/client.ex`
- `spb/services/bacen_gateway/lib/bacen_gateway/crypto/message_packer.ex`

Core:

- Pode manter adaptadores KMS genéricos para usos regulatórios não relacionados a mensagens BACEN.
- Não deve configurar HSM RTM como assinador de TED, PIX, SPB, DICT ou ICOM-SPI.
- Não deve conter fluxo que monte, assine, decifre ou transmita mensagem BACEN dessas famílias.

## Contrato HSM aplicado

Sessão:

- `POST /v1/kmip/{vhsm}/get-session-credential`
- Corpo: `cryptoUser`, `token`
- Retorno esperado: `returnValue`

Assinatura RSA:

- `POST /v1/kmip/{vhsm}/sign-rsa`
- Corpo: `session`, `cryptographicAlgorithm`, `privateKeyUid`, `dataSignHex`
- Header operacional: `Authorization: Bearer <sessão>`

Verificação RSA:

- `POST /v1/kmip/{vhsm}/signature-verify-rsa`
- Corpo: `session`, `cryptographicAlgorithm`, `publicKeyUid`, `dataSignHex`, `signatureDataHex`
- Header operacional: `Authorization: Bearer <sessão>`

Cifra e decifra RSA:

- `POST /v1/kmip/{vhsm}/cipher/rsa/encrypt`
- `POST /v1/kmip/{vhsm}/cipher/rsa/decrypt`
- Corpo conforme Swagger validado: `session`, `identifierKey`, `paddingMode`, `dataList`

## Validação

Os testes focados confirmam:

- PIX envia `dataSignHex` EMSA-PKCS1-v1.5 correto para `sign-rsa`.
- PIX envia `Authorization: Bearer <sessão>` nas operações criptográficas após obter sessão.
- SPB envia `dataSignHex` EMSA-PKCS1-v1.5 correto para C15.
- SPB usa `cipher/rsa/decrypt` com `identifierKey`, `paddingMode` e `dataList` para C14 de entrada.
- Core não é caminho operacional de assinatura BACEN.

## Pendências externas

Para assinatura real Monetarie ainda faltam:

1. vHSM real da Monetarie.
2. `cryptoUser` e token de homologação da Monetarie.
3. UIDs das chaves privadas e públicas PIX e SPB.
4. Certificados associados às chaves do HSM.
5. Ambiente RSFN liberado para bateria de mensagens SPI, DICT, ICOM e SPB.

Nenhuma credencial real deve ser gravada neste Markdown.