Módulo Pix

Descrição detalhada

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

Consulte a documentação técnica do HSM sobre detalhes de funcionamento, especificações utilizadas, licenças e nome comercial do módulo.

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. Reaproveitar o handle Pix. O handle criado por DPIXOpenHandle() guarda as credenciais e os identificadores dos objetos, e não depende de uma sessão do HSM aberta. Mantenha o handle durante a vida da aplicação em vez de abrir e fechar a cada requisição.
2. Abrir um handle por thread. O handle pode ser usado por várias threads, nunca simultaneamente. No modo padrão isso não implica uma conexão por handle: todos compartilham o cache de conexões HTTP.
3. Definir um teto de conexões apenas quando o ambiente exigir. O padrão é sem limite, e o cache cresce conforme a concorrência da aplicação. Configure HSM_PIX_POOL_MAX_HANDLES quando houver uma restrição no número de conexões simultâneas com o peer. Nesse caso, meça antes com os contadores do cache (DPIXGetCacheParam()) e defina o limite a partir do maior valor observado, em vez de estimar.
4. Limpar o cache, quando o ambiente exigir, para antecipar a troca de objetos. Os objetos do HSM são lidos durante o handshake, então conexões já abertas seguem usando os anteriores até serem refeitas. Se a troca precisar valer imediatamente, DPIXSetCacheParam() com PIXCP_CLEAR faz a próxima requisição reconectar e reler os objetos.

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 recepção 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.

Funções
int AAP_API	DPIXSign (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedPIXEnvelope, BYTE *pbUnsignedPIXEnvelope, DWORD *pdwSizeSignedPIXEnvelope, BYTE **ppbSignedPIXEnvelope)
	Assina digitalmente um XML no formato ISO 20.022 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
int AAP_API	DPIXVerify (HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedPIXEnvelope, BYTE *pbSignedPIXEnvelope)
	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).
int AAP_API	DPIXDictSign (HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedDictEnvelope, BYTE *pbUnsignedDictEnvelope, DWORD *pdwSizeSignedDictEnvelope, BYTE **ppbSignedDictEnvelope)
	Assina digitalmente um XML no formato XMLDSig seguindo o padrão DICT definido no SPI (Sistema de Pagamentos Instantâneos).
int AAP_API	DPIXDictVerify (HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedDictEnvelope, BYTE *pbSignedDictEnvelope)
	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).
int AAP_API	DPIXJWSSign (HSESSIONCTX hSession, const char *szKeyId, DWORD dwFlags, DWORD dwHeaderLen, BYTE *pbHeader, DWORD dwPayloadLen, BYTE *pbPayload, DWORD *pdwJWSLen, BYTE *pbJWS)
	Faz uma assinatura JWS RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
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)
	Valida um JWS assinado RFC 7515 seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
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)
	Faz uma requisição segura HTTP POST seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
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)
	Faz uma requisição segura HTTP PUT seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
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)
	Faz uma requisição segura HTTP GET seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
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)
	Faz uma requisição segura HTTP DELETE seguindo o padrão PIX definido no SPI (Sistema de Pagamentos Instantâneos).
int AAP_API	DPIXOpenHandle (HPIXSESSIONCTX *phPIXSession, const char *szKeyId, const char *szCertId, const char *szPIXCertChainId, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags, DWORD dwPixFlags)
	Cria um handle PIX, que encapsula uma conexão HTTP persistente e o material TLS (certificado, cadeia e chave) usados no túnel mTLS.
int AAP_API	DPIXCloseHandle (HPIXSESSIONCTX *phPIXSession, DWORD dwReserved)
	Destrói um handle PIX criado por DPIXOpenHandle(), apagando da memória as credenciais nele armazenadas.
int AAP_API	DPIXGetHandleParam (HPIXSESSIONCTX hPIXSession, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
	Recupera informações e contadores de um handle PIX.
int AAP_API	DPIXSetCacheParam (DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwReserved)
	Configura o cache de sessões HTTP do PIX, usado pelas funções DPIXPost(), DPIXPut(), DPIXGet() e DPIXDelete().
int AAP_API	DPIXGetCacheParam (DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
	Recupera a configuração e os contadores do cache de sessões HTTP do PIX.
int AAP_API	DPIXRequest (HPIXSESSIONCTX hPIXSession, const PIX_REQUEST *pstRequest, PIX_RESPONSE *pstResponse, DWORD dwReserved)
	Executa uma requisição HTTP com um handle PIX, para qualquer método.
int AAP_API	DPIXFreeResponse (PIX_RESPONSE *pstResponse)
	Libera os buffers de uma PIX_RESPONSE preenchida por DPIXRequest().

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.

DPIXOpenHandle()

int AAP_API DPIXOpenHandle	(	HPIXSESSIONCTX *	phPIXSession,
		const char *	szKeyId,
		const char *	szCertId,
		const char *	szPIXCertChainId,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags,
		DWORD	dwPixFlags )

#include <dinamo.h>

Cria um handle PIX, que encapsula uma conexão HTTP persistente e o material TLS (certificado, cadeia e chave) usados no túnel mTLS.

O handle é independente de qualquer sessão com o HSM. Uma sessão é obtida internamente, via DOpenSession(), somente durante o handshake TLS, e devolvida imediatamente depois. Requisições que reaproveitam a conexão não acessam o HSM.

Os parâmetros dwParam, pbData, dwDataLen e dwFlags são exatamente os que seriam passados a DOpenSession() e ficam armazenados no handle. São apagados da memória quando o handle é destruído com DPIXCloseHandle().

Parâmetros

[out]	phPIXSession	Ponteiro que receberá o handle criado.
[in]	szKeyId	Identificador da chave privada usada no túnel mTLS.
[in]	szCertId	Identificador do certificado do cliente.
[in]	szPIXCertChainId	Identificador da cadeia de certificados do peer (PKCS#7).
[in]	dwParam	Tipo de autenticação, conforme DOpenSession().
[in]	pbData	Dados de autenticação, conforme DOpenSession().
[in]	dwDataLen	Tamanho de pbData, em bytes.
[in]	dwFlags	Flags de abertura de sessão, conforme DOpenSession().
[in]	dwPixFlags	Valor Significado 0 Padrão. O handle é uma referência leve que não guarda conexão entre chamadas: cada requisição pega uma conexão do cache de sessões HTTP e a devolve ao terminar. DN_PIX_NO_CACHE O handle é exclusivo do chamador e mantém a própria conexão HTTP até DPIXCloseHandle().

Os dois modos seguem o mesmo contrato de HSESSIONCTX: um handle 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 de conexões HTTP.

Retorna

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

Veja também

DPIXCloseHandle() DOpenSession()

Exemplos

pix_handle_no_cache.c, pix_handle_request.c e pix_handle_stats.c.

DPIXCloseHandle()

int AAP_API DPIXCloseHandle	(	HPIXSESSIONCTX *	phPIXSession,
		DWORD	dwReserved )

#include <dinamo.h>

Destrói um handle PIX criado por DPIXOpenHandle(), apagando da memória as credenciais nele armazenadas.

O efeito sobre as conexões depende do modo com que o handle foi criado. Um handle DN_PIX_NO_CACHE é exclusivo, então sua conexão HTTP é fechada aqui. Um handle com cache não possui conexão própria: apenas a referência é liberada, e as conexões do cache seguem disponíveis para outros chamadores até a varredura de ociosidade fechá-las. Para fechá-las de imediato, use DPIXSetCacheParam() com PIXCP_CLEAR.

Parâmetros

[in,out]	phPIXSession	Ponteiro para o handle. Recebe NULL no retorno.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

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

Veja também

DPIXOpenHandle()

Exemplos

pix_handle_no_cache.c, pix_handle_request.c e pix_handle_stats.c.

DPIXGetHandleParam()

int AAP_API DPIXGetHandleParam	(	HPIXSESSIONCTX	hPIXSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Recupera informações e contadores de um handle PIX.

Os valores são sempre do handle informado, nos dois modos. Um handle com cache pega uma conexão emprestada a cada requisição, mas registra o resultado em si mesmo ao fim de cada uma: os contadores são das requisições feitas por este handle, e não da conexão que o atendeu.

Parâmetros

[in]	hPIXSession	Handle PIX.
[in]	dwParam	Valor Significado PIXP_HTTP_RET Tipo de pbData: ND_uint64_t Código de resposta HTTP da última requisição. PIXP_HTTP_REQ_DETAILS Tipo de pbData: PIX_HTTP_REQUEST_DETAILS Detalhes da última requisição. PIXP_STATS Tipo de pbData: PIX_HANDLE_STATS Contadores acumulados do handle. O campo dwVersion deve ser preenchido com PIX_HANDLE_STATS_VERSION antes da chamada.
[out]	pbData	Buffer que receberá o valor. Passar NULL para consultar o tamanho necessário: a função escreve o tamanho em pdwDataLen e retorna zero, seguindo a convenção de DGetSessionParam().
[in,out]	pdwDataLen	Tamanho de pbData na entrada; tamanho necessário ou escrito na saída. Se o buffer for menor que o necessário, a função retorna D_MORE_DATA e escreve aqui o tamanho exigido.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

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

Veja também

DPIXOpenHandle()

Exemplos

pix_handle_stats.c.

DPIXSetCacheParam()

int AAP_API DPIXSetCacheParam	(	DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Configura o cache de sessões HTTP do PIX, usado pelas funções DPIXPost(), DPIXPut(), DPIXGet() e DPIXDelete().

O cache é de escopo da biblioteca. Handles criados explicitamente sem cache com DPIXOpenHandle() pertencem a quem os criou, não entram no cache e não são afetados por esta função.

Parâmetros

[in]	dwParam	Valor Significado PIXCP_CLEAR Tipo de pbData: NULL Marca as sessões HTTP do cache para serem fechadas. As que estiverem ociosas são fechadas imediatamente. As sessões que estiverem em uso são fechadas ao final da requisição em andamento, em vez de retornarem ao cache. PIXCP_MAX_HANDLES Tipo de pbData: DWORD Número máximo de sessões HTTP mantidas no cache. Zero significa sem limite. Reduzir o valor não fecha sessões já existentes, apenas impede a criação de novas. Equivale à variável de ambiente HSM_PIX_POOL_MAX_HANDLES. PIXCP_IDLE_TTL Tipo de pbData: DWORD Tempo, em segundos, após o qual uma sessão HTTP ociosa é fechada. Zero desabilita. Equivale à variável de ambiente HSM_PIX_POOL_IDLE_TTL.
[in]	pbData	Valor a ser definido, conforme dwParam.
[in]	dwDataLen	Tamanho de pbData, em bytes.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

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

Veja também

DPIXGetCacheParam() DPIXOpenHandle()

Exemplos

pix_handle_stats.c.

DPIXGetCacheParam()

int AAP_API DPIXGetCacheParam	(	DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Recupera a configuração e os contadores do cache de sessões HTTP do PIX.

Parâmetros

[in]	dwParam	Valor Significado PIXCP_MAX_HANDLES Tipo de pbData: DWORD Número máximo de sessões HTTP no cache. PIXCP_IDLE_TTL Tipo de pbData: DWORD Tempo de ociosidade, em segundos, para fechamento de uma sessão HTTP. PIXCP_STATS Tipo de pbData: PIX_POOL_STATS Contadores do cache. O campo dwVersion deve ser preenchido com PIX_POOL_STATS_VERSION antes da chamada.
[out]	pbData	Buffer que receberá o valor. Passar NULL para consultar o tamanho necessário: a função escreve o tamanho em pdwDataLen e retorna zero, seguindo a convenção de DGetSessionParam().
[in,out]	pdwDataLen	Tamanho de pbData na entrada; tamanho necessário ou escrito na saída. Se o buffer for menor que o necessário, a função retorna D_MORE_DATA e escreve aqui o tamanho exigido.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

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

Veja também

DPIXSetCacheParam()

Exemplos

pix_handle_stats.c.

DPIXRequest()

int AAP_API DPIXRequest	(	HPIXSESSIONCTX	hPIXSession,
		const PIX_REQUEST *	pstRequest,
		PIX_RESPONSE *	pstResponse,
		DWORD	dwReserved )

#include <dinamo.h>

Executa uma requisição HTTP com um handle PIX, para qualquer método.

O método é informado em #PIX_REQUEST::method, e os parâmetros de entrada e o resultado vão em estruturas, de forma que acrescentar um campo no futuro não muda a assinatura desta função.

A conexão HTTP e o material TLS vêm de hPIXSession, não de uma sessão com o HSM: a chave, o certificado e a cadeia foram definidos em DPIXOpenHandle().

Os buffers de pstResponse são alocados internamente. Liberá-los com DPIXFreeResponse(), inclusive quando a função retorna erro - uma resposta parcial pode ter sido recebida antes da falha.

pstResponse é zerada logo no início da chamada. A única exceção é dwVersion inválida: nesse caso a estrutura não é tocada, porque o seu layout é desconhecido.

Parâmetros

[in]	hPIXSession	Handle PIX criado por DPIXOpenHandle().
[in]	pstRequest	Dados da requisição. O campo dwVersion deve ser preenchido com PIX_REQUEST_VERSION antes da chamada.
[out]	pstResponse	Resposta recebida. O campo dwVersion deve ser preenchido com PIX_RESPONSE_VERSION antes da chamada. Pode ser NULL para descartar a resposta.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

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

Veja também

DPIXOpenHandle() DPIXFreeResponse() DPIXPost()

Exemplos

pix_handle_no_cache.c, pix_handle_request.c e pix_handle_stats.c.

DPIXFreeResponse()

int AAP_API DPIXFreeResponse

(

PIX_RESPONSE *

pstResponse

)

#include <dinamo.h>

Libera os buffers de uma PIX_RESPONSE preenchida por DPIXRequest().

Libera todos os campos com exceção de dwVersion (para manter o layout). Como os ponteiros são zerados, chamar duas vezes é seguro. Passar NULL não faz nada.

Parâmetros

[in,out]

pstResponse

Resposta a liberar.

Retorna

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

Veja também

DPIXRequest()

Exemplos

pix_handle_no_cache.c, pix_handle_request.c e pix_handle_stats.c.