Pix

Detailed description

Operations destined for the Pix of the SPI (Instant Payment System).

Pix

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

Network

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

--- title: Diagrama físico de rede --- %%{ init: { 'flowchart': { 'curve': 'basis' } } }%% flowchart LR psp[Aplicação PSP] hsm[HSM] fw[Firewall] rsfn{{RSFN}} spi["SPI (Pix/Dict)"] subgraph redepsp [Rede PSP] hsm <--> psp psp <--> fw end fw <--> rsfn rsfn <--> spi

Signature and verification

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

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

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

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

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

HTTP requests

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

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

Operation

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

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

--- title: Visão geral handshake TLS utilizando o HSM --- %%{ init: { 'flowchart': { 'curve': 'basis' }} }%% sequenceDiagram participant hsm as HSM participant psp as PSP participant spi as SPI (Pix/Dict) Note over hsm: certificado TLS psp ->> spi: Inicia handshake TLS spi ->> psp: Requisita
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

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

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

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

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

Good practices

General

1. Reuse sessions (benefit from session caching). Use the HSM session cache and gain performance by reusing HSM and HTTP sessions. In this case, it is recommended that you open a session, perform the operations you want and then close it, allowing the session to be reused quickly, thus reducing downtime.
2. Ensuring that sessions are closed. Closing sessions guarantees the release of the resource, both in the HSM and on the client. Make sure that sessions are closed even for operations with a return code other than success.
3. Use concurrent sessions. Using concurrent/parallel sessions with the HSM helps to extract maximum performance. Attention should be paid to using too many sessions with HSMs, so as not to cause unnecessary use of resources. The throughput curve tends to rise and find a plateau.

Pix HTTP requests

1. Define a connection object reload interval. You can optimize the number of times HSM keys and objects are loaded by setting a reload interval for HSM objects. As the institution's key/certificate/chain update is done infrequently and on a scheduled basis, it is advantageous to define a reload interval for these objects. Pay attention to network asset timeouts that are shorter than this value to avoid premature disconnections and unnecessary errors. See more details and how to configure here.

Important settings

General

1. Set the HSM connection timeouts. When the HSM timeout is not set, the default is that of the operating system. In the event of a connection failure, the application may wait too long. It is important to ALWAYS set the HSM's send and receive timeouts. Other connection parameters can be found here.

Pix HTTP requests

1. Define the HTTP operation timeouts. When not defined, the default HTTP operation timeout is unlimited. In the event of an HTTP connection failure, the application may be put on hold indefinitely. It is important to ALWAYS set the timeout in HTTP request calls.

Operations destined for the Pix of the SPI (Instant Payment System). More...

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

Functions

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>

Digitally signs an XML in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for signing. Corresponding to a CPIA certificate.
[in]	szCertId	Name of the digital certificate used for signing. Digital certificate of the PSP registered with SPI for signing, also known as CPIA or CERTPIA.
[in]	dwFlags	Subscription options. Pass 0. If you need any additional options, the following values are accepted. Value Meaning PIX_SIGN_RNS Enables the use of relative namespaces.
[in]	dwSizeUnsignedPIXEnvelope	Size, in bytes, of the original XML in pbUnsignedPIXEnvelope.
[in]	pbUnsignedPIXEnvelope	Buffer containing the original XML.
[out]	pdwSizeSignedPIXEnvelope	Pointer to the size of the signed XML, in bytes. When the function returns, this parameter will contain the size of the data stored in ppbSignedPIXEnvelope.
[out]	ppbSignedPIXEnvelope	Pointer with the return to the signed XML. Memory allocation is done internally. The calling application is responsible for freeing the allocated memory using the DFree() API. See comments for more information.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

We recommend using the signature tag using the full closure, as seen below, for performance reasons.

<Sgntr></Sgntr>

The tag with a simple closing is also accepted, see below.

<Sgntr/>

Examples

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>

Checks the signature of a digitally signed XML document in ISO 20.022 format following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the actual certificate used in the signature. This formatting is necessary because the Pix XML message does not contain the certificate used in the signature. Optionally, only the X.509 certificate used for signing can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
[in]	szCRL	Name of the Certificate Revocation List (CRL) - stored internally in the HSM - where the digital certificate will be verified. It is possible to pass NULL indicating that there is no CRL to check.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	dwSizeSignedPIXEnvelope	Size, in bytes, of the XML signed on pbSignedPIXEnvelope.
[in]	pbSignedPIXEnvelope	Signed XML.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples

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>

Digitally signs an XML in XMLDSig format following the DICT standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for signing. Corresponding to a CPIA certificate.
[in]	szCertId	Name of the digital certificate used for signing. Digital certificate of the PSP registered with SPI for signing, also known as CPIA or CERTPIA.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	dwSizeUnsignedDictEnvelope	Size, in bytes, of the original XML in pbUnsignedDictEnvelope.
[in]	pbUnsignedDictEnvelope	Buffer containing the original XML.
[out]	pdwSizeSignedDictEnvelope	Pointer to the size of the signed XML, in bytes. When the function returns, this parameter will contain the size of the data stored in ppbSignedDictEnvelope.
[out]	ppbSignedDictEnvelope	Pointer with the return to the signed XML. Memory allocation is done internally. The calling application is responsible for freeing the allocated memory using the DFree() API. See comments for more information.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

Do not include the signature tag, it will be added automatically.

Examples

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>

Checks the signature of a digitally signed XML document in XMLDSig format following the DICT standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szChainId	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the actual certificate used in the signature. This formatting is necessary because the Pix XML message does not contain the certificate used in the signature. Optionally, only the X.509 certificate used for signing can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
[in]	szCRL	Name of the Certificate Revocation List (CRL) - stored internally in the HSM - where the digital certificate will be verified. It is possible to pass NULL indicating that there is no CRL to check.
[in]	dwFlags	Reserved for future use (must be 0).
[in]	dwSizeSignedDictEnvelope	Size, in bytes, of the XML signed on pbSignedDictEnvelope.
[in]	pbSignedDictEnvelope	Signed XML.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples

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>

It makes a JWS RFC 7515 signature following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used for signing. As defined in the PIX security manual
[in]	dwFlags	Subscription options. Must be passed 0.
[in]	dwHeaderLen	Size, in bytes, of the JWS Header in pbHeader.
[in]	pbHeader	JWS header for signature. At least the header parameter alg must be informed. Accepted values for alg. Value Meaning 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	Size, in bytes, of the JWS payload in pbPayload.
[in]	pbPayload	Buffer containing the JWS payload for signing.
[in,out]	pdwJWSLen	Pointer to buffer size pbJWSin bytes. When the function returns, this parameter will contain the size of the data stored in pbJWS.
[out]	pbJWS	Buffer that will contain the signed JWS. If NULL is passed, the API will return 0 and pdwJWSLen will contain the estimated necessary size of pbJWS.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It uses the Compact Serialization format described in Section-3.1 of RFC 7515.

Examples

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>

Validates an RFC 7515 signed JWS following the PIX standard defined in the SPI (Instant Payment System).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szChain	Name of the PKCS#7 chain (stored internally in the HSM) of the certificate used in the signature. The chain must be complete, from the root CA to the actual certificate used in the signature. This formatting is necessary because the Pix XML message does not contain the certificate used in the signature. Optionally, only the X.509 certificate used for signing can be passed instead of the complete chain. As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several chains. It is important to note that in the case of an HSM PKCS#7 object containing multiple chains, the presence of an expired certificate in any of the chains will generate a valid signature return code with an expired certificate (non-zero code) in the verification, even if the signature was made with a certificate from a non-expired chain; it is up to the application to handle this correctly according to local policy.
[in]	szCRL	Name of the Certificate Revocation List (CRL) - stored internally in the HSM - where the digital certificate will be verified. It is possible to pass NULL indicating that there is no CRL to check.
[in]	dwJWSLen	Size, in bytes, of the JWS signature in pbJWS.
[in]	pbJWS	JWS signed.
[in]	dwFlags	Validation options. Must be passed 0.
[in,out]	pdwHeaderLen	Pointer to buffer size pbHeaderin bytes. When the function returns, this parameter will contain the size of the data stored in pbHeader.
[out]	pbHeader	Buffer that will contain the JWS Header. If NULL is passed, the API will return 0 and pdwHeaderLen will contain the estimated necessary size of pbHeader.
[in,out]	pdwPayloadLen	Pointer to buffer size pbPayloadin bytes. When the function returns, this parameter will contain the size of the data stored in pbPayload.
[out]	pbPayload	Buffer that will contain the JWS payload. If NULL is passed, the API will return 0 and pdwPayloadLen will contain the estimated necessary size of pbPayload.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples

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>

It makes a secure HTTP POST request following the PIX standard defined in SPI (Instant Payment System).

Observation

Make the timeout settings. See more details in the Best practices section.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used to close the tunnel. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used to close the tunnel. Digital certificate of the PSP registered in the SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several strings.
[in]	szURL	URL of the PIX server (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header without content, use ; instead of : (Ex. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. You must use the corresponding API, described in this manual. The standard initial header includes Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect and Content-Length.
[in]	dwSizeRequestData	Size of data passed in pbRequestData.
[in]	pbRequestData	Data sent in the request.
[in]	dwTimeOut	Operation timeout time in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the buffer ppbResponseHeadersin bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The allocated size is defined in pdwSizeResponseHeaders. This pointer must be released using the API DFree().
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the buffer ppbResponseBodyin bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be released using the API DFree().
[in]	dwParam	Value Meaning 0 Default option. Does not check the certificate with the host name. PIX_VERIFY_HOST_NAME Checks certificate with host name. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host, User-Agent and Content-Length. PIX_GZIP Automatically gzips the request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

DFree() DPIXGet() DPIXDelete()

Examples

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>

It makes a secure HTTP PUT request following the PIX standard defined in the SPI (Instant Payment System).

Observation

Make the timeout settings. See more details in the Best practices section.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used to close the tunnel. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used to close the tunnel. Digital certificate of the PSP registered in the SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several strings.
[in]	szURL	URL of the PIX server (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header without content, use ; instead of : (Ex. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. You must use the corresponding API, described in this manual. The standard initial header includes Host, User-Agent, Accept, Accept-Encoding, Expect and Content-Length.
[in]	dwSizeRequestData	Size of data passed in pbRequestData.
[in]	pbRequestData	Data sent in the request.
[in]	dwTimeOut	Operation timeout time in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the buffer ppbResponseHeadersin bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The allocated size is defined in pdwSizeResponseHeaders. This pointer must be released using the API DFree().
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the buffer ppbResponseBodyin bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be released using the API DFree().
[in]	dwParam	Value Meaning 0 Default option. Does not check the certificate with the host name. PIX_VERIFY_HOST_NAME Checks certificate with host name. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host, User-Agent and Content-Length. PIX_GZIP Automatically gzips the request data. Automatically includes the necessary headers (Content-Encoding and Accept-Encoding).

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

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

Examples

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>

It makes a secure HTTP GET request following the PIX standard defined in the SPI (Instant Payment System).

Observation

Make the timeout settings. See more details in the Best practices section.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used to close the tunnel. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used to close the tunnel. Digital certificate of the PSP registered in the SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several strings.
[in]	szURL	URL of the PIX server (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header without content, use ; instead of : (Ex. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. You must use the corresponding API, described in this manual. The standard initial header includes Host, User-Agent, Accept, Accept-Encoding.
[in]	dwTimeOut	Operation timeout time in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the buffer ppbResponseHeadersin bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The allocated size is defined in pdwSizeResponseHeaders. This pointer must be released using the API DFree().
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the buffer ppbResponseBodyin bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be released using the API DFree().
[in]	dwParam	Value Meaning 0 Default option. Does not check the certificate with the host name. PIX_VERIFY_HOST_NAME Checks certificate with host name. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host and User-Agent. PIX_GZIP Includes the Accept-Encoding: gzip header if basic header is enabled.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

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

Examples

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>

It makes a secure HTTP DELETE request following the PIX standard defined in SPI (Instant Payment System).

Observation

Make the timeout settings. See more details in the Best practices section.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szKeyId	Name of the private key used to close the tunnel. Corresponds to a CPIC certificate.
[in]	szCertId	Name of the certificate used to close the tunnel. Digital certificate of the PSP registered in the SPI for connection, also known as CPIC or CERTPIC.
[in]	szPIXCertChainId	Name of the PKCS#7 string used to check the PIX server (ICOM or DICT). As of version 5.0.23 of the HSM firmware, it is possible to use a PKCS#7 object that contains several strings.
[in]	szURL	URL of the PIX server (ICOM or DICT).
[in]	dwCountRequestHeaderList	Number of lines filled in pszRequestHeaderList.
[in]	pszRequestHeaderList	Lines containing the customized HTTP headers that will be used in the request. Can be passed null if you want to use the default header without changes. This option will overwrite the default headers if they overlap. To remove a header, pass the name of the header without a value (e.g. Accept:). To include a header without content, use ; instead of : (Ex. Accept;). Do NOT use CRLF terminators in headers. Passing these terminators may cause unwanted behavior. Formatting will be done internally. This option cannot be used to change the first line of the request (e.g. POST, PUT, GET, DELETE), which is not a header. You must use the corresponding API, described in this manual. The standard initial header includes Host, User-Agent, Accept, Accept-Encoding.
[in]	dwTimeOut	Operation timeout time in milliseconds. Can be set to 0 for no timeout.
[out]	pdwSizeResponseHeaders	Pointer that will contain the size of the data stored in the buffer ppbResponseHeadersin bytes.
[out]	ppbResponseHeaders	Internally allocated buffer that will contain the header returned by the request. The allocated size is defined in pdwSizeResponseHeaders. This pointer must be released using the API DFree().
[out]	pdwSizeResponseBody	Pointer that will contain the size of the data stored in the buffer ppbResponseBodyin bytes.
[out]	ppbResponseBody	Internally allocated buffer that will contain the body returned by the request. The allocated size is defined in pdwSizeResponseBody. This pointer must be released using the API DFree().
[in]	dwParam	Value Meaning 0 Standard option for SPB certificates. Does not check the certificate against the host name. PIX_VERIFY_HOST_NAME Checks certificate with host name. PIX_BASIC_HTTP_HEADER Uses the basic initial HTTP header. Includes Host and User-Agent. PIX_GZIP Includes the Accept-Encoding: gzip header if basic header is enabled.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It executes a secure request following the PIX standard defined in the SPI in the documents: "Annex IV - Security Manual", "Technical and business specifications of the Brazilian instant payment ecosystem" and "Annex III - Communication Interfaces Manual" defined in the SPI.
The negotiated tunnel is TLS version 1.2 with mutual authentication, using the HTTP protocol version 1.1 with a minimum Cipher Suite of ECDHE-RSA-AES-128-GCM-SHA256.

This API will automatically decompress a response that comes compressed in the gzip standard. If you choose to compress the sending data, the API caller must do so in gzip format.

This request uses the following headers by default.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", where 0.0.0.0 is the version of the HSM client library used.

Certificate validation with the host name is done by checking that the Common Name field or Subject Alternate Name field of the certificate matches the host name of the URL passed as a parameter.

When making an HTTP request, 2 operations are performed, one to use the HSM objects (private key, certificate and chain, used for tunnel authentication) and the other to open the HTTP session with the HTTP server.
To optimize resources, the session with the HTTP server is kept open and cached; likewise, the session with the HSM is cached by default (the HSM session can optionally be set not to be cached).
The HTTP session is associated with the session opened with the HSM, which means that to reuse an HTTP session you must use the same HSM session that was previously used to open the HTTP session.
The HTTP session is physically closed when the session with the HSM is physically closed.
The HSM session and the HTTP session have thread-session affinity and cannot be used simultaneously by several threads.

Long Polling is adjusted by setting the HTTP operation timeout (POST/GET/DELETE) according to the HTTP server settings.

See also

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

Examples

post_put_get_delete_pix.c.