Pix

Descrição detalhada

Operações destinadas ao Pix do SPI (Sistema de Pagamentos Instantâneos).

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
credenciais do PSP psp ->> psp: Autentica SPI psp ->> hsm: Requisita informações
de autenticação hsm ->> hsm: Gera assinatura
para autenticação TLS destroy hsm hsm ->> psp: Envia assinatura psp ->> spi: Envia dados
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
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.

Boas práticas

Geral

1. Reutilizar sessões (se beneficiar do cache de sessões). Use o cache de sessões do HSM e ganhe performance reutilizando as sessões do HSM e HTTP. Neste caso recomenda-se abrir uma sessão, fazer as operações que deseja e logo após fechar; permitindo que a sessão possa ser reutilizada rapidamente, diminuindo assim o tempo ocioso.
2. Garantir o fechamento das sessões. O fechamento das sessões garante a liberação do recurso, tanto no HSM quanto no cliente. Certifique-se que as sessões sejam fechadas inclusive nas operações com código de retorno diferente de sucesso.
3. Utilizar sessões concorrentes. Usar sessões concorrentes/paralelas com o HSM ajuda a extrair o máximo de performance. Deve-se atentar para o excesso de sessões com os HSMs, para não causar um uso desnecessário de recursos. A curva de throughput tende a subir e encontrar um platô.

Requisições HTTP Pix

1. Definir um intervalo de recarregamento de objetos de conexão. É possível otimizar a quantidade de vezes em que ocorre o carregamento das chaves e objetos do HSM definindo um intervalo de recarregamento de objetos do HSM. Como a atualização de chave/certificado/cadeia da instituição é feita poucas vezes e de forma programada, é vantajoso definir um intervalo de recarregamento desses objetos. Atentar para timeouts de ativos de rede menores do que esse valor, isto evita desconexões prematuras e erros desnecessários. Veja mais detalhes e como configurar aqui.

Configurações Importantes

Geral

1. Definir os timeouts de conexão com o HSM. Quando não definido o timeout do HSM o padrão é o do sistema operacional. Em casos de falha de conexão a aplicação pode ficar em espera excessiva. É importante SEMPRE definir o timeout de envio e recebimento do HSM. Outros parâmetros de conexão podem ser vistos aqui.

Requisições HTTP Pix

1. Definir os timeouts da operação HTTP. Quando não definido o timeout padrão da operação HTTP é sem limite. Em casos de falha de conexão HTTP a aplicação pode ficar em espera indefinidamente. É importante SEMPRE definir o timeout nas chamadas de requisições HTTP.

Operações destinadas ao Pix do SPI (Sistema de Pagamentos Instantâneos). Mais...

Funções
int AAP_API	DPIXSign (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedPIXEnvelope, BYTE *pbUnsignedPIXEnvelope, DWORD *pdwSizeSignedPIXEnvelope, BYTE **ppbSignedPIXEnvelope)
int AAP_API	DPIXVerify (HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedPIXEnvelope, BYTE *pbSignedPIXEnvelope)
int AAP_API	DPIXDictSign (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedDictEnvelope, BYTE *pbUnsignedDictEnvelope, DWORD *pdwSizeSignedDictEnvelope, BYTE **ppbSignedDictEnvelope)
int AAP_API	DPIXDictVerify (HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedDictEnvelope, BYTE *pbSignedDictEnvelope)
int AAP_API	DPIXJWSSign (HSESSIONCTX hSession, const char *szKeyId, DWORD dwFlags, DWORD dwHeaderLen, BYTE *pbHeader, DWORD dwPayloadLen, BYTE *pbPayload, DWORD *pdwJWSLen, BYTE *pbJWS)
int AAP_API	DPIXJWSCheck (HSESSIONCTX hSession, const char *szChain, const char *szCRL, DWORD dwJWSLen, BYTE *pbJWS, DWORD dwFlags, DWORD *pdwHeaderLen, BYTE *pbHeader, DWORD *pdwPayloadLen, BYTE *pbPayload)
int AAP_API	DPIXPost (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPIXCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwSizeRequestData, BYTE *pbRequestData, DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
int AAP_API	DPIXPut (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPIXCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwSizeRequestData, BYTE *pbRequestData, DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
int AAP_API	DPIXGet (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPIXCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)
int AAP_API	DPIXDelete (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, const char *szPIXCertChainId, const char *szURL, DWORD dwCountRequestHeaderList, const char *pszRequestHeaderList[], DWORD dwTimeOut, DWORD *pdwSizeResponseHeaders, BYTE **ppbResponseHeaders, DWORD *pdwSizeResponseBody, BYTE **ppbResponseBody, DWORD dwParam)

Funções

DPIXSign()

int AAP_API DPIXSign	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		DWORD	dwFlags,
		DWORD	dwSizeUnsignedPIXEnvelope,
		BYTE *	pbUnsignedPIXEnvelope,
		DWORD *	pdwSizeSignedPIXEnvelope,
		BYTE **	ppbSignedPIXEnvelope )

#include <dinamo.h>

Assina digitalmente um XML no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para assinatura. Correspondente a um certificado CPIA.
[in]	szCertId	Nome do certificado digital utilizado para assinatura. Certificado Digital do PSP cadastrado no SPI para assinatura, também conhecido como CPIA ou CERTPIA.
[in]	dwFlags	Opções de assinatura. Passar 0. Caso precise de alguma opção adicional os seguintes valores são aceitos. Valor Significado PIX_SIGN_RNS Habilita o uso de namespaces relativas.
[in]	dwSizeUnsignedPIXEnvelope	Tamanho, em bytes, do XML original em pbUnsignedPIXEnvelope.
[in]	pbUnsignedPIXEnvelope	Buffer contendo o XML original.
[out]	pdwSizeSignedPIXEnvelope	Ponteiro para o tamanho do XML assinado, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em ppbSignedPIXEnvelope.
[out]	ppbSignedPIXEnvelope	Ponteiro de ponteiro com o retorno para o XML assinado. A alocação de memória é feita internamente. A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree(). Consulte observações para maiores informações.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Recomendamos utilizar a tag de assinatura utilizando o fechamento completo, como visto abaixo, por motivos de performance.

<Sgntr></Sgntr>

A tag com fechamento simples também é aceita, ver abaixo.

<Sgntr/>

Exemplos

sign_verify_pix.c.

DPIXVerify()

int AAP_API DPIXVerify	(	HSESSIONCTX	hSession,
		const char *	szChainId,
		const char *	szCRL,
		DWORD	dwFlags,
		DWORD	dwSizeSignedPIXEnvelope,
		BYTE *	pbSignedPIXEnvelope )

#include <dinamo.h>

Verifica a assinatura de um documento XML assinado digitalmente no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
[in]	szCRL	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).
[in]	dwSizeSignedPIXEnvelope	Tamanho, em bytes, do XML assinado em pbSignedPIXEnvelope.
[in]	pbSignedPIXEnvelope	XML assinado.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

sign_verify_pix.c.

DPIXDictSign()

int AAP_API DPIXDictSign	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		DWORD	dwFlags,
		DWORD	dwSizeUnsignedDictEnvelope,
		BYTE *	pbUnsignedDictEnvelope,
		DWORD *	pdwSizeSignedDictEnvelope,
		BYTE **	ppbSignedDictEnvelope )

#include <dinamo.h>

Assina digitalmente um XML no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para assinatura. Correspondente a um certificado CPIA.
[in]	szCertId	Nome do certificado digital utilizado para assinatura. Certificado Digital do PSP cadastrado no SPI para assinatura, também conhecido como CPIA ou CERTPIA.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).
[in]	dwSizeUnsignedDictEnvelope	Tamanho, em bytes, do XML original em pbUnsignedDictEnvelope.
[in]	pbUnsignedDictEnvelope	Buffer contendo o XML original.
[out]	pdwSizeSignedDictEnvelope	Ponteiro para o tamanho do XML assinado, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em ppbSignedDictEnvelope.
[out]	ppbSignedDictEnvelope	Ponteiro de ponteiro com o retorno para o XML assinado. A alocação de memória é feita internamente. A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree(). Consulte observações para maiores informações.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Não incluir a tag de assinatura, ela será adicionada automaticamente.

Exemplos

sign_verify_dict.c.

DPIXDictVerify()

int AAP_API DPIXDictVerify	(	HSESSIONCTX	hSession,
		const char *	szChainId,
		const char *	szCRL,
		DWORD	dwFlags,
		DWORD	dwSizeSignedDictEnvelope,
		BYTE *	pbSignedDictEnvelope )

#include <dinamo.h>

Verifica a assinatura de um documento XML assinado digitalmente no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szChainId	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
[in]	szCRL	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).
[in]	dwSizeSignedDictEnvelope	Tamanho, em bytes, do XML assinado em pbSignedDictEnvelope.
[in]	pbSignedDictEnvelope	XML assinado.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

sign_verify_dict.c.

DPIXJWSSign()

int AAP_API DPIXJWSSign	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		DWORD	dwFlags,
		DWORD	dwHeaderLen,
		BYTE *	pbHeader,
		DWORD	dwPayloadLen,
		BYTE *	pbPayload,
		DWORD *	pdwJWSLen,
		BYTE *	pbJWS )

#include <dinamo.h>

Faz uma assinatura JWS RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para assinatura. Como definido no manual de segurança do PIX
[in]	dwFlags	Opções de assinatura. Deve ser passado 0.
[in]	dwHeaderLen	Tamanho, em bytes, do Header JWS em pbHeader.
[in]	pbHeader	Header JWS para assinatura. Pelo menos o parâmetro de cabeçalho alg deverá ser informado. Valores aceitos para alg. Valor Significado RS256 RSA 2048 PKCS#1v5 RS384 RSA 3072 PKCS#1v5 RS512 RSA 4096 PKCS#1v5 PS256 RSA 2048 PSS PS384 RSA 3072 PSS PS512 RSA 4096 PSS ES256 ECC SECP256R1 ES384 ECC SECP384R1 ES512 ECC SECP521R1
[in]	dwPayloadLen	Tamanho, em bytes, do Payload JWS em pbPayload.
[in]	pbPayload	Buffer contendo o Payload JWS para assinatura.
[in,out]	pdwJWSLen	Ponteiro para o tamanho do buffer pbJWS, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em pbJWS.
[out]	pbJWS	Buffer que conterá o JWS assinado. Se for passado NULL a API retornará 0 e pdwJWSLen conterá o tamanho necessário estimado de pbJWS.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Utiliza o formato Compact Serialization descrito na Section-3.1 da RFC 7515.

Exemplos

sign_check_pix_jws.c.

DPIXJWSCheck()

int AAP_API DPIXJWSCheck	(	HSESSIONCTX	hSession,
		const char *	szChain,
		const char *	szCRL,
		DWORD	dwJWSLen,
		BYTE *	pbJWS,
		DWORD	dwFlags,
		DWORD *	pdwHeaderLen,
		BYTE *	pbHeader,
		DWORD *	pdwPayloadLen,
		BYTE *	pbPayload )

#include <dinamo.h>

Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szChain	Nome da cadeia PKCS#7 (armazenada internamente no HSM) do certificado utilizado na assinatura. A cadeia deverá ser completa contendo da AC raiz até o próprio certificado utilizado na assinatura. Esta formatação é necessária porque a mensagem XML de Pix não traz o certificado usado na assinatura. Opcionalmente, pode ser passado apenas o certificado X.509 utilizado para assinar, no lugar da cadeia completa. A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias. Importante observar que no caso de um objeto PKCS#7 do HSM que contenha múltiplas cadeias, a presença de um certificado expirado em qualquer das cadeias irá gerar na verificação um código de retorno de assinatura válida com certificado expirado (código diferente de zero), mesmo que a assinatura tenha sido realizada com certificado de cadeia não expirada; fica a cargo da aplicação o tratamento correto conforme a política local.
[in]	szCRL	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.
[in]	dwJWSLen	Tamanho, em bytes, da assinatura JWS em pbJWS.
[in]	pbJWS	JWS assinado.
[in]	dwFlags	Opções de validação. Deve ser passado 0.
[in,out]	pdwHeaderLen	Ponteiro para o tamanho do buffer pbHeader, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em pbHeader.
[out]	pbHeader	Buffer que conterá o Header do JWS. Se for passado NULL a API retornará 0 e pdwHeaderLen conterá o tamanho necessário estimado de pbHeader.
[in,out]	pdwPayloadLen	Ponteiro para o tamanho do buffer pbPayload, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em pbPayload.
[out]	pbPayload	Buffer que conterá o Payload do JWS. Se for passado NULL a API retornará 0 e pdwPayloadLen conterá o tamanho necessário estimado de pbPayload.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

sign_check_pix_jws.c.

DPIXPost()

int AAP_API DPIXPost	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwSizeRequestData,
		BYTE *	pbRequestData,
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

Faz uma requisição segura HTTP POST seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
[in]	szCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
[in]	szPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
[in]	szURL	URL do servidor PIX (ICOM ou DICT).
[in]	dwCountRequestHeaderList	Quantidade de linhas preenchidas em pszRequestHeaderList.
[in]	pszRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect e Content-Length.
[in]	dwSizeRequestData	Tamanho dos dados passados em pbRequestData.
[in]	pbRequestData	Dados enviados na requisição.
[in]	dwTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
[out]	pdwSizeResponseHeaders	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseHeaders, em bytes.
[out]	ppbResponseHeaders	Buffer alocado internamente que conterá o header retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseHeaders. Este ponteiro deverá ser liberado utilizando a API DFree().
[out]	pdwSizeResponseBody	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseBody, em bytes.
[out]	ppbResponseBody	Buffer alocado internamente que conterá o body retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseBody. Este ponteiro deverá ser liberado utilizando a API DFree().
[in]	dwParam	Valor Significado 0 Opção padrão. Não verifica o certificado com o nome do host. PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host, User-Agent e Content-Length. PIX_GZIP Faz a compressão gzip automática dos dados de requisição. Inclui automaticamente os headers necessários (Content-Encoding e Accept-Encoding).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos 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.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

Veja também

DFree() DPIXGet() DPIXDelete()

Exemplos

post_put_get_delete_pix.c.

DPIXPut()

int AAP_API DPIXPut	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwSizeRequestData,
		BYTE *	pbRequestData,
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

Faz uma requisição segura HTTP PUT seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
[in]	szCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
[in]	szPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
[in]	szURL	URL do servidor PIX (ICOM ou DICT).
[in]	dwCountRequestHeaderList	Quantidade de linhas preenchidas em pszRequestHeaderList.
[in]	pszRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding, Expect e Content-Length.
[in]	dwSizeRequestData	Tamanho dos dados passados em pbRequestData.
[in]	pbRequestData	Dados enviados na requisição.
[in]	dwTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
[out]	pdwSizeResponseHeaders	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseHeaders, em bytes.
[out]	ppbResponseHeaders	Buffer alocado internamente que conterá o header retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseHeaders. Este ponteiro deverá ser liberado utilizando a API DFree().
[out]	pdwSizeResponseBody	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseBody, em bytes.
[out]	ppbResponseBody	Buffer alocado internamente que conterá o body retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseBody. Este ponteiro deverá ser liberado utilizando a API DFree().
[in]	dwParam	Valor Significado 0 Opção padrão. Não verifica o certificado com o nome do host. PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host, User-Agent e Content-Length. PIX_GZIP Faz a compressão gzip automática dos dados de requisição. Inclui automaticamente os headers necessários (Content-Encoding e Accept-Encoding).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos 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.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

Veja também

DFree() DPIXPut() DPIXGet() DPIXDelete()

Exemplos

post_put_get_delete_pix.c.

DPIXGet()

int AAP_API DPIXGet	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

Faz uma requisição segura HTTP GET seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
[in]	szCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
[in]	szPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
[in]	szURL	URL do servidor PIX (ICOM ou DICT).
[in]	dwCountRequestHeaderList	Quantidade de linhas preenchidas em pszRequestHeaderList.
[in]	pszRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding.
[in]	dwTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
[out]	pdwSizeResponseHeaders	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseHeaders, em bytes.
[out]	ppbResponseHeaders	Buffer alocado internamente que conterá o header retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseHeaders. Este ponteiro deverá ser liberado utilizando a API DFree().
[out]	pdwSizeResponseBody	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseBody, em bytes.
[out]	ppbResponseBody	Buffer alocado internamente que conterá o body retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseBody. Este ponteiro deverá ser liberado utilizando a API DFree().
[in]	dwParam	Valor Significado 0 Opção padrão. Não verifica o certificado com o nome do host. PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host e User-Agent. PIX_GZIP Inclui o header Accept-Encoding: gzip caso basic header esteja habilitado.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos 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.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

Veja também

DFree() DPIXPost() DPIXGet() DPIXDelete()

Exemplos

post_put_get_delete_pix.c.

DPIXDelete()

int AAP_API DPIXDelete	(	HSESSIONCTX	hSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		const char *	szURL,
		DWORD	dwCountRequestHeaderList,
		const char *	pszRequestHeaderList[],
		DWORD	dwTimeOut,
		DWORD *	pdwSizeResponseHeaders,
		BYTE **	ppbResponseHeaders,
		DWORD *	pdwSizeResponseBody,
		BYTE **	ppbResponseBody,
		DWORD	dwParam )

#include <dinamo.h>

Faz uma requisição segura HTTP DELETE seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).

Observação

Faça as configurações de timeout. Veja mais detalhes na seção Boas práticas.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szKeyId	Nome da chave privada utilizada para fechamento do túnel. Correspondente a um certificado CPIC.
[in]	szCertId	Nome do certificado utilizado para fechamento do túnel. Certificado Digital do PSP cadastrado no SPI para conexão, também conhecido como CPIC ou CERTPIC.
[in]	szPIXCertChainId	Nome da cadeia PKCS#7 utilizada para verificar o servidor PIX (ICOM ou DICT). A partir da versão 5.0.23 do firmware do HSM é possível utilizar um objeto PKCS#7 que contenha várias cadeias.
[in]	szURL	URL do servidor PIX (ICOM ou DICT).
[in]	dwCountRequestHeaderList	Quantidade de linhas preenchidas em pszRequestHeaderList.
[in]	pszRequestHeaderList	Linhas contendo os headers HTTP customizados que serão utilizados na requisição. Pode ser passado nulo caso queira utilizar o header padrão sem alterações. Essa opção irá sobrescrever os headers padrão, caso haja sobreposição. Para remover um header passe o nome do header sem valor (Ex. Accept:). Para incluir um header sem conteúdo utilize ; ao invés de : (Ex. Accept;). NÃO utilizar terminadores CRLF nos headers. A passagem desses terminadores poderá causar comportamentos indesejados. A formatação será feita internamente. Esta opção não pode ser utilizada para alterar a primeira linha da requisição (Ex. POST, PUT, GET, DELETE), que não é um header. Deve-se utilizar a API correspondente, descrita neste manual. O header inicial padrão inclui Host, User-Agent, Accept, Accept-Encoding.
[in]	dwTimeOut	Tempo de timeout da operação em milisegundos. Pode ser passado 0 para não ter tempo de timeout.
[out]	pdwSizeResponseHeaders	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseHeaders, em bytes.
[out]	ppbResponseHeaders	Buffer alocado internamente que conterá o header retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseHeaders. Este ponteiro deverá ser liberado utilizando a API DFree().
[out]	pdwSizeResponseBody	Ponteiro que conterá o tamanho dos dados armazenados no buffer ppbResponseBody, em bytes.
[out]	ppbResponseBody	Buffer alocado internamente que conterá o body retornado pela requisição. O tamanho alocado estará definido em pdwSizeResponseBody. Este ponteiro deverá ser liberado utilizando a API DFree().
[in]	dwParam	Valor Significado 0 Opção padrão para certificados SPB. Não verifica o certificado com o nome do host. PIX_VERIFY_HOST_NAME Verifica certificado com o nome do host. PIX_BASIC_HTTP_HEADER Usa o header HTTP inicial básico. Inclui Host e User-Agent. PIX_GZIP Inclui o header Accept-Encoding: gzip caso basic header esteja habilitado.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Executa uma requisição segura seguindo o padrão PIX definida no SPI nos 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.
O túnel negociado é o TLS versão 1.2 com autenticação mútua, utilizando o protocolo HTTP versão 1.1 com Cipher Suite mínima de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API irá descompactar automaticamente uma resposta que venha compactada no padrão gzip. Caso opte pela compactação dos dados de envio, a compactação deverá ser feita pelo chamador da API, no formato gzip.

Esta requisição utiliza os seguintes headers como padrão.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", onde 0.0.0.0 é a versão da biblioteca cliente do HSM utilizada.

A validação de certificado com o nome do host é feita verificando se os campos Common Name field ou Subject Alternate Name do certificado coincidem com o host name da URL passada como parâmetro.

Ao fazer um request HTTP são feitas 2 operações, uma de uso dos objetos do HSM (chave privada, certificado e cadeia, usados para autenticação do túnel) e outra de abertura da sessão HTTP com o servidor HTTP.
Para otimizar os recursos a sessão com o servidor HTTP é mantida aberta e guardada em cache, igualmente, a sessão com o HSM é guardada em cache por padrão (a sessão do HSM pode ser, opcionalmente, definida para não ser guardada em cache).
A sessão HTTP fica associada à sessão aberta com o HSM, isto significa que para reutilizar uma sessão HTTP deve-se usar a mesma sessão do HSM utilizada anteriormente para abrir a sessão HTTP.
A sessão HTTP é fechada físicamente quando a sessão com o HSM é fechada físicamente.
A sessão do HSM e a HTTP tem afinidade thread-sessão, não podendo ser utilizada simultâneamente entre várias threads.

O ajuste do Long Polling é feito definindo o timeout da operação HTTP (POST/GET/DELETE) de acordo com as configurações do servidor HTTP.

Veja também

DFree() DPIXPost() DPIXPut() DPIXGet()

Exemplos

post_put_get_delete_pix.c.