Pix

As APIs do módulo Pix são destinadas ao uso das funcionalidades de assinatura, verificação, envio e recebimentos de requisições HTTP Pix.

Rede

O HSM não faz acessos direto aos servidores Pix/DICT, sendo posicionado na rede para uso dos servidores internos do PSP.

---
title: Diagrama físico de rede
---

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
flowchart LR
    psp[Aplicação PSP]
    hsm[HSM fa:key]
    fw[Firewall]
    rsfn{{RSFN}}
    spi["SPI (Pix/Dict)"]

    subgraph redepsp [Rede PSP]
      hsm <--> psp
      psp <--> fw
    end
    fw <--> rsfn
    rsfn <--> spi

Assinatura e verificação

As APIs de assinatura e verificação Pix tem como base o padrão ISO 20.022, as APIs DICT seguem o formato XMLDSig, ambas definidas pelo SPI no documento "Anexo IV – Manual de Segurança".

As funções de API para uso com assinatura Pix e DICT exigem o armazenamento interno no HSM dos certificados digitais para assinatura digital e da cadeia completa de confiança dos certificados para verificação.

Para um gravar um certificado digital (ou arquivo) no HSM utilize a console de gerenciamento remoto ou a API DWriteFile().

O certificado digital para assinatura deverá estar codificado no formato binário ASN1 DER e também seguir o padrão X.509 . O arquivo contendo a cadeia de confiança para verificação de assinatura digital deverá estar codificada no formato PKCS#7 (Public Key Cryptography Standard #7 – Cryptographic Message Syntax Standard).

As funções de assinatura e validação JWS Pix seguem a RFC 7515 e a documentação do SPI.

Requisições HTTP

As APIs de requisições HTTP Pix disponibilizam a comunicação segura HTTP com os servidores Pix ou DICT, utilizando as chaves e certificados protegidos pelo HSM.

As funções de comunicação segura padrão Pix que seguem as definições descritas nos seguintes documentos: "Anexo IV – Manual de Segurança", "Especificações técnicas e de negócio do ecossistema de pagamentos instantâneos brasileiro" e "Anexo III - Manual das Interfaces de comunicação" definidos no SPI.

Funcionamento

A conexão segura é feita entre o servidor do PSP e o servidor do Pix/DICT, o HSM é utilizado apenas para uso de objetos e chave privada do PSP.

O acesso ao HSM ocorre apenas no momento do handshake TLS. Após o fechamento do túnel a comunicação é mantida apenas entre o servidor do PSP e o servidor do Pix/DICT.

---
title: Visão geral handshake TLS utilizando o HSM
---

%%{ init: { 'flowchart': { 'curve': 'basis' }} }%%
sequenceDiagram
    participant hsm as HSM
    participant psp as PSP
    participant spi as SPI (Pix/Dict)

    Note over hsm: certificado TLS
    psp ->> spi: Inicia handshake TLS
    spi ->> psp: Requisita<br>credenciais do PSP
    psp ->> psp: Autentica SPI
    psp ->> hsm: Requisita informações<br>de autenticação
    hsm ->> hsm: Gera assinatura<br>para autenticação TLS
    destroy hsm
    hsm ->> psp: Envia assinatura
    psp ->> spi: Envia dados<br>de autenticação
    spi ->> spi: Autentica PSP
    loop Canal TLS
        %% necessário manter o espaço após o spi: (ou usar um text)
        psp-->spi: 
        psp ->> spi: Requisição<br>Pix/Dict
        spi ->> psp: Resposta
    end

Uma conexão HTTP está associada ao handle de sessão do HSM que foi utilizado na abertura da sessão HTTP. Isto permite manter a associação e o acesso aos objetos de conexão (chave privada, certificado e cadeia de certificados) dentro do HSM.

---
title: Handle de sessão do HSM
---

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
flowchart TB
    hsm[Sessão HSM]
    http[Sessão HTTP]
    %% necessário manter os espaços após o subpgraph (ou usar um text)
    subgraph  
      hsm
      http
    end

A abertura da sessão HTTP só é feita nas chamadas de requisição HTTP Pix.
O fechamento da sessão HTTP acontece quando sua respectiva sessão do HSM é fechada físicamente (fechamento da sessão com cache desabilitado ou explicitamente definido para fechamento físico da sessão).
Uma sessão fechada (sem definição explícita de fechamento físico e sem cache desabilitado) não fecha a sessão HTTP associada pois não há fechamento físico da sessão.
A sessão HTTP é reutilizada em chamadas HTTP posteriores, independente do tipo de operação HTTP (POST, GET, DELETE ou PUT) utilizada.
A sessão HTTP não é reutilizada quando os parâmetros de conexão (IP, porta) são alterados.

Por exemplo: suponha que uma operação de POST é feita, a sessão HTTP é mantida aberta dentro do handle de sessão do HSM. Ao fechar a sessão do HSM (sem desabilitar o cache de sessões) a sessão é guardada no cache de sessões juntamente com a sessão HTTP. Pedindo a abertura de uma nova sessão, a sessão guardada em cache será retornada. Ao reutilizar o handle de sessão do HSM para uma operação GET, a sessão HTTP é reutilizada pois estava guardada no handle de sessão do HSM.

JWS

O módulo Pix disponibiliza APIs que auxiliam no uso do QR Code dinâmico Pix. São disponibilizadas APIs para assinatura e checagem JWS (JSON Web Signature).