Pular para conteúdo

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]
    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

As requisições são feitas a partir de um handle Pix, criado por DPIXOpenHandle(). O handle guarda as credenciais de autenticação e os identificadores dos objetos usados no handshake (chave privada, certificado e cadeia do peer), e não fica preso a uma sessão do HSM: a sessão é aberta apenas durante o handshake TLS e liberada logo em seguida.

Todos os métodos HTTP passam por uma única função, DPIXRequest(), que recebe o método (POST, PUT, GET ou DELETE) na estrutura de requisição.

O handle pode ser criado em dois modos:

  • Padrão: o handle é uma referência leve, sem conexão própria. Cada requisição pega uma conexão emprestada do cache de conexões HTTP e a devolve ao terminar. Vários handles compartilham as mesmas conexões, e a quantidade de conexões acompanha a concorrência real da aplicação, não a quantidade de handles abertos.
  • Exclusivo (DN_PIX_NO_CACHE): o handle mantém a própria conexão HTTP até ser fechado e não participa do cache. Use quando a aplicação precisa de uma correspondência direta entre handle e conexão, ou seja, quando a quantidade de conexões abertas com o peer precisa ser previsível e controlada pela própria aplicação.
---
title: Handles Pix e conexões HTTP
---

%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
flowchart LR
    cache[("Cache de<br>conexões HTTP")]
    spi["SPI (Pix/Dict)"]

    subgraph app [Aplicação]
      h1[Handle padrão]
      h2[Handle padrão]
      h3["Handle exclusivo<br>(DN_PIX_NO_CACHE)"]
    end

    h1 --> cache
    h2 --> cache
    cache --> spi
    h3 --> spi

O cache reaproveita a conexão livre usada mais recentemente (MRU) entre as que correspondem à mesma identidade, aos mesmos objetos e ao mesmo destino, o que mantém quente um conjunto pequeno de conexões e deixa as demais expirarem por ociosidade. Veja Cache de Conexões HTTP Pix.

Em ambos os modos o handle segue o mesmo contrato de uso do handle de sessão do HSM: pode ser usado por várias threads, nunca simultaneamente. Para fazer requisições em paralelo, abra um handle por thread — no modo padrão isso não implica uma conexão por handle, pois todos compartilham o mesmo cache.

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).

Nome Comercial

Consulte o tópico Módulos sobre o atual nome comercial do módulo; ele será utilizado em apresentações, material de marketing e divulgação, propostas comerciais e contratos.

Licença

Consulte os tópicos Licenças e Módulos sobre a necessidade de licença específica para a utilização das APIs do módulo e qual o nome desta licença.

API Pix

Documentação específica da API para o módulo Pix, com funções, classes e exemplos.