Pix

The Pix module APIs are designed to use Pix's HTTP request signing, verification, sending and receiving functionalities.

Network

The HSM does not make direct access to the Pix/DICT servers, but is positioned on the network for use by the PSP's internal servers.

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

Signature and verification

The Pix signature and verification APIs are based on the ISO 20.022 standard, and the DICT APIs follow the XMLDSig format, both defined by SPI in the document "Annex IV - Security Manual".

The API functions for use with Pix and DICT signing require the internal storage in the HSM of the digital certificates for digital signing and the complete chain of trust of the certificates for verification.

To write a digital certificate (or file) to the HSM, use the remote management console or the DWriteFile() API.

The digital certificate for signing must be encoded in ASN1 DER binary format and also follow the X.509 standard. The file containing the chain of trust for verifying the digital signature must be encoded in PKCS#7 format (Public Key Cryptography Standard #7 - Cryptographic Message Syntax Standard).

The JWS Pix signing and validation functions follow RFC 7515 and the SPI documentation.

HTTP requests

The Pix HTTP request APIs provide secure HTTP communication with Pix or DICT servers, using the keys and certificates protected by the HSM.

The Pix standard secure communication functions that follow the definitions described in the following documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.

Operation

The secure connection is made between the PSP server and the Pix/DICT server, the HSM is only used to use PSP objects and private keys.

Access to the HSM only occurs during the TLS handshake. After the tunnel is closed, communication is only maintained between the PSP server and the Pix/DICT server.

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

An HTTP connection is associated with the HSM session handle that was used to open the HTTP session. This makes it possible to maintain the association and access to the connection objects (private key, certificate and certificate chain) within the 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

• The HTTP session is only opened in Pix HTTP request calls.
• The HTTP session is closed when its respective HSM session is physically closed (session closure with cache disabled or explicitly set to physically close the session).
• A closed session (with no explicit definition of physical closure and no cache disabled) does not close the associated HTTP session because there is no physical closure of the session.
• The HTTP session is reused in subsequent HTTP calls, regardless of the type of HTTP operation (POST, GET, DELETE or PUT) used.
• The HTTP session is not reused when the connection parameters (IP, port) are changed.

For example: suppose a POST operation is performed, the HTTP session is kept open within the HSM session handle. When you close the HSM session (without disabling the session cache) the session is stored in the session cache along with the HTTP session. If a new session is requested, the cached session will be returned. When reusing the HSM session handle for a GET operation, the HTTP session is reused because it was stored in the HSM session handle.

JWS

The Pix module provides APIs to help you use the Pix dynamic QR Code. APIs are available for signing and checking JWS (JSON Web Signature).