Descripción detallada

Pix Operaciones dirigidas al SPI (Sistema de Pagos Instantáneos).

Consulte la documentación técnica del HSM.

Buenas prácticas

General

Reutilice las sesiones (benefíciese de la caché de sesión). Utilice la caché de sesiones del HSM y gane rendimiento reutilizando las sesiones HSM y HTTP. En este caso se recomienda abrir una sesión, realizar las operaciones que se deseen y luego cerrarla, lo que permite reutilizar la sesión rápidamente, reduciendo así el tiempo de inactividad.
Garantizar el cierre de las sesiones. El cierre de sesiones garantiza la liberación del recurso, tanto en el HSM como en el cliente. Asegúrese de que las sesiones se cierran incluso para operaciones con un código de retorno distinto de éxito.
Utilice sesiones concurrentes. El uso de sesiones concurrentes/paralelas con el HSM ayuda a extraer el máximo rendimiento. Debe prestarse atención al uso de demasiadas sesiones con HSM, para no provocar un uso innecesario de recursos. La curva de rendimiento tiende a subir y a encontrar una meseta.

Peticiones HTTP Pix

Definir un intervalo de recarga de objetos de conexión. Puede optimizar el número de veces que se cargan las claves y objetos HSM definiendo un intervalo de recarga para los objetos HSM. Dado que la actualización de claves/certificados/cadenas de la institución se realiza con poca frecuencia y de forma programada, resulta ventajoso definir un intervalo de recarga para estos objetos. Preste atención a los tiempos de espera de los activos de red que sean inferiores a este valor para evitar desconexiones prematuras y errores innecesarios. Vea más detalles y cómo configurarlo aquí.

Ajustes importantes

General

Configure los tiempos de espera de conexión del HSM. Si no se establece el tiempo de espera del HSM, el valor predeterminado es el del sistema operativo. En caso de fallo de la conexión, la aplicación puede esperar demasiado tiempo. Es importante configurar SIEMPRE los tiempos de espera de envío y recepción de HSM. Aquí encontrará otros parámetros de conexión.

Peticiones HTTP Pix

Define los tiempos de espera de las operaciones HTTP. Si no se define, el tiempo de espera de la operación HTTP por defecto es ilimitado. En caso de fallo de la conexión HTTP, la aplicación puede quedar en espera indefinidamente. Es importante definir SIEMPRE el tiempo de espera en las llamadas a peticiones HTTP.

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

Funciones

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

PIX Firma digitalmente un XML en formato ISO 20.022 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Parámetros

[in] hSession Contexto adquirido a través de la función DOpenSession().

[in] szKeyId Nombre de la clave privada utilizada para la firma. Correspondiente a un certificado CPIA.

[in] szCertId Nombre del certificado digital utilizado para la firma. Certificado digital del PSP registrado en SPI para la firma, también conocido como CPIA o CERTPIA.

[in]

dwFlags

Opciones de suscripción. Pase 0. Si necesita opciones adicionales, se aceptan los siguientes valores.

Valor	Significado
PIX_SIGN_RNS	Permite el uso de espacios de nombres relativos.

[in] dwSizeUnsignedPIXEnvelope Tamaño, en bytes, del XML original en pbUnsignedPIXEnvelope.

[in] pbUnsignedPIXEnvelope Buffer que contiene el XML original.

[out] pdwSizeSignedPIXEnvelope Puntero al tamaño del XML firmado, en bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en ppbSignedPIXEnvelope.

[out] ppbSignedPIXEnvelope Puntero con el retorno al XML firmado. La asignación de memoria se realiza internamente. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree(). Consulte los comentarios para obtener más información.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: Recomendamos utilizar la etiqueta de firma con el cierre completo, como se ve a continuación, por razones de rendimiento.
<Sgntr></Sgntr>

También se acepta la etiqueta con un cierre simple, véase más abajo.
<Sgntr/>

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

PIX Comprueba la firma de un documento XML firmado digitalmente en formato ISO 20.022 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szChainId	Nombre de la cadena PKCS#7 (almacenada internamente en el HSM) del certificado utilizado en la firma. La cadena debe estar completa, desde la CA raíz hasta el certificado real utilizado en la firma. Pix Este formato es necesario porque el mensaje XML de no contiene el certificado utilizado en la firma. Opcionalmente, sólo se puede pasar el certificado X.509 utilizado para firmar en lugar de la cadena completa. A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas. Es importante tener en cuenta que, en el caso de un objeto PKCS#7 de HSM que contenga varias cadenas, la presencia de un certificado caducado en cualquiera de las cadenas generará un código de retorno de firma válido con un certificado caducado (código distinto de cero) en la verificación, aunque la firma se haya realizado con un certificado de una cadena no caducada; depende de la aplicación tratar esto correctamente de acuerdo con la política local.
[in]	szCRL	Nombre de la lista de revocación de certificados (CRL) -almacenada internamente en el HSM- en la que se verificará el certificado digital. Es posible pasar NULL indicando que no hay CRL que comprobar.
[in]	dwFlags	Reservado para uso futuro (debe ser 0).
[in]	dwSizeSignedPIXEnvelope	Tamaño, en bytes, del XML firmado en `pbSignedPIXEnvelope`.
[in]	pbSignedPIXEnvelope	XML firmado.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

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

Firma digitalmente un XML en formato XMLDSig siguiendo el estándar DICT definido en el SPI (Sistema de Pago Instantáneo).

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szKeyId	Nombre de la clave privada utilizada para la firma. Correspondiente a un certificado CPIA.
[in]	szCertId	Nombre del certificado digital utilizado para la firma. Certificado digital del PSP registrado en SPI para la firma, también conocido como CPIA o CERTPIA.
[in]	dwFlags	Reservado para uso futuro (debe ser 0).
[in]	dwSizeUnsignedDictEnvelope	Tamaño, en bytes, del XML original en `pbUnsignedDictEnvelope`.
[in]	pbUnsignedDictEnvelope	Buffer que contiene el XML original.
[out]	pdwSizeSignedDictEnvelope	Puntero al tamaño del XML firmado, en bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en `ppbSignedDictEnvelope`.
[out]	ppbSignedDictEnvelope	Puntero con el retorno al XML firmado. La asignación de memoria se realiza internamente. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree(). Consulte los comentarios para obtener más información.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: No incluya la etiqueta de firma, se añadirá automáticamente.

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

Comprueba la firma de un documento XML firmado digitalmente en formato XMLDSig siguiendo el estándar DICT definido en el SPI (Sistema de Pago Instantáneo).

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szChainId	Nombre de la cadena PKCS#7 (almacenada internamente en el HSM) del certificado utilizado en la firma. La cadena debe estar completa, desde la CA raíz hasta el certificado real utilizado en la firma. Pix Este formato es necesario porque el mensaje XML de no contiene el certificado utilizado en la firma. Opcionalmente, sólo se puede pasar el certificado X.509 utilizado para firmar en lugar de la cadena completa. A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas. Es importante tener en cuenta que, en el caso de un objeto PKCS#7 de HSM que contenga varias cadenas, la presencia de un certificado caducado en cualquiera de las cadenas generará un código de retorno de firma válido con un certificado caducado (código distinto de cero) en la verificación, aunque la firma se haya realizado con un certificado de una cadena no caducada; depende de la aplicación tratar esto correctamente de acuerdo con la política local.
[in]	szCRL	Nombre de la lista de revocación de certificados (CRL) -almacenada internamente en el HSM- en la que se verificará el certificado digital. Es posible pasar NULL indicando que no hay CRL que comprobar.
[in]	dwFlags	Reservado para uso futuro (debe ser 0).
[in]	dwSizeSignedDictEnvelope	Tamaño, en bytes, del XML firmado en `pbSignedDictEnvelope`.
[in]	pbSignedDictEnvelope	XML firmado.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

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

PIX Realiza una firma JWS RFC 7515 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Parámetros

[in] hSession Contexto adquirido a través de la función DOpenSession().

[in] szKeyId Nombre de la clave privada utilizada para firmar. Tal como se define en el PIX

[in] dwFlags Opciones de suscripción. Se debe pasar 0.

[in] dwHeaderLen Tamaño, en bytes, de la cabecera JWS en pbHeader.

[in]

pbHeader

Cabecera JWS para la firma. Al menos el parámetro de cabecera alg debe ser informado. Valores aceptados 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 Tamaño, en bytes, de la carga útil del JWS en pbPayload.

[in] pbPayload Buffer que contiene la carga útil JWS para firmar.

[in,out] pdwJWSLen Puntero al tamaño del búfer pbJWSen bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en pbJWS.

[out] pbJWS Buffer que contendrá el JWS firmado. Si se pasa NULL, la API devolverá 0 y pdwJWSLen contendrá el tamaño necesario estimado de pbJWS.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: Utiliza el formato Compact Serialisation descrito en la Sección-3.1 del RFC 7515.

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

PIX Valida un JWS firmado RFC 7515 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szChain	Nombre de la cadena PKCS#7 (almacenada internamente en el HSM) del certificado utilizado en la firma. La cadena debe estar completa, desde la CA raíz hasta el certificado real utilizado en la firma. Pix Este formato es necesario porque el mensaje XML de no contiene el certificado utilizado en la firma. Opcionalmente, sólo se puede pasar el certificado X.509 utilizado para firmar en lugar de la cadena completa. A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas. Es importante tener en cuenta que, en el caso de un objeto PKCS#7 de HSM que contenga varias cadenas, la presencia de un certificado caducado en cualquiera de las cadenas generará un código de retorno de firma válido con un certificado caducado (código distinto de cero) en la verificación, aunque la firma se haya realizado con un certificado de una cadena no caducada; depende de la aplicación tratar esto correctamente de acuerdo con la política local.
[in]	szCRL	Nombre de la lista de revocación de certificados (CRL) -almacenada internamente en el HSM- en la que se verificará el certificado digital. Es posible pasar NULL indicando que no hay CRL que comprobar.
[in]	dwJWSLen	Tamaño, en bytes, de la firma JWS en `pbJWS`.
[in]	pbJWS	JWS firmado.
[in]	dwFlags	Opciones de validación. Se debe pasar 0.
[in,out]	pdwHeaderLen	Puntero al tamaño del búfer `pbHeader`en bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en `pbHeader`.
[out]	pbHeader	Buffer que contendrá la cabecera JWS. Si se pasa NULL, la API devolverá 0 y `pdwHeaderLen` contendrá el tamaño necesario estimado de `pbHeader`.
[in,out]	pdwPayloadLen	Puntero al tamaño del búfer `pbPayload`en bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en `pbPayload`.
[out]	pbPayload	Buffer que contendrá la carga útil de JWS. Si se pasa NULL, la API devolverá 0 y `pdwPayloadLen` contendrá el tamaño necesario estimado de `pbPayload`.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

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

PIX Realiza una petición HTTP POST segura siguiendo el estándar definido en SPI (Sistema de Pago Instantáneo).

Observación: Configure el tiempo de espera. Consulte más detalles en la sección Buenas prácticas.

Parámetros

[in] hSession Contexto adquirido a través de la función DOpenSession().

[in] szKeyId Nombre de la clave privada utilizada para cerrar el túnel. Corresponde a un certificado CPIC.

[in] szCertId Nombre del certificado utilizado para cerrar el túnel. Certificado digital del PSP registrado en el SPI para la conexión, también conocido como CPIC o CERTPIC.

[in] szPIXCertChainId PIX Nombre de la cadena PKCS#7 utilizada para comprobar el servidor (ICOM o DICT). A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas.

[in] szURL PIX URL del servidor (ICOM o DICT).

[in] dwCountRequestHeaderList Número de líneas rellenadas pszRequestHeaderList.

[in] pszRequestHeaderList Líneas que contienen las cabeceras HTTP personalizadas que se utilizarán en la petición. Se puede pasar null si se desea utilizar la cabecera por defecto sin cambios.
Esta opción sobrescribirá las cabeceras por defecto si se solapan.
Para eliminar una cabecera, pase el nombre de la cabecera sin un valor (p. ej. Acepta:).
Para incluir una cabecera sin contenido, utilice ; en lugar de : (Ej. Acepta;).
NO utilice terminadores CRLF en las cabeceras. Pasar estos terminadores puede causar un comportamiento no deseado. El formateo se realizará internamente.
Esta opción no puede utilizarse para modificar la primera línea de la petición (por ejemplo, POST, PUT, GET, DELETE), que no es una cabecera. Debe utilizarse la API correspondiente, descrita en este manual.
La cabecera inicial estándar incluye Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect y Content-Length.

[in] dwSizeRequestData Tamaño de los datos introducidos pbRequestData.

[in] pbRequestData Datos enviados en la solicitud.

[in] dwTimeOut Tiempo de espera de la operación en milisegundos. Puede establecerse en 0 para que no haya tiempo de espera.

[out] pdwSizeResponseHeaders Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseHeadersen bytes.

[out] ppbResponseHeaders Búfer asignado internamente que contendrá el cabecera devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseHeaders. Este puntero debe liberarse utilizando la API DFree().

[out] pdwSizeResponseBody Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseBodyen bytes.

[out] ppbResponseBody Búfer asignado internamente que contendrá el cuerpo devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseBody. Este puntero debe liberarse utilizando la API DFree().

[in]

dwParam

Valor	Significado
0	Opción por defecto. No comprueba el certificado con el nombre de host.
PIXVERIFICAR_NOMBRE_DE_HOST	Comprueba el certificado con el nombre del host.
PIXENCABEZADO_HTTP_BASICO	Utiliza la cabecera HTTP inicial básica. Incluye Host, User-Agent y Content-Length.
PIXGZIP	Comprime automáticamente los datos de la solicitud. Incluye automáticamente las cabeceras necesarias (Content-Encoding y Accept-Encoding).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

PIX Ejecuta una petición segura siguiendo el estándar definido en el SPI en los documentos: "Anexo IV - Manual de Seguridad", "Especificaciones técnicas y de negocio del ecosistema brasileño de pagos instantáneos" y "Anexo III - Manual de Interfaces de Comunicación" definidos en el SPI.
El túnel negociado es TLS versión 1.2 con autenticación mutua, utilizando el protocolo HTTP versión 1.1 con un Cipher Suite mínimo de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API descomprimirá automáticamente una respuesta que venga comprimida en el estándar gzip. Si decide comprimir los datos de envío, la persona que llame a la API deberá hacerlo en formato gzip.

Esta solicitud utiliza por defecto las siguientes cabeceras.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", donde 0.0.0.0 es la versión de la biblioteca cliente HSM utilizada.

La validación del certificado con el nombre de host se realiza comprobando que el campo Common Name o Subject Alternate Name del certificado coincide con el nombre de host de la URL pasada como parámetro.

Al realizar una petición HTTP, se efectúan 2 operaciones, una para utilizar los objetos HSM (clave privada, certificado y cadena, utilizados para autenticar el túnel) y otra para abrir la sesión HTTP con el servidor HTTP.
Para optimizar los recursos, la sesión con el servidor HTTP se mantiene abierta y se almacena en caché; del mismo modo, la sesión con el HSM se almacena en caché por defecto (la sesión del HSM puede configurarse opcionalmente para que no se almacene en caché).
La sesión HTTP está asociada a la sesión abierta con el HSM, lo que significa que para reutilizar una sesión HTTP hay que utilizar la misma sesión HSM que se utilizó previamente para abrir la sesión HTTP.
La sesión HTTP se cierra físicamente cuando se cierra físicamente la sesión con el HSM.
La sesión con el HSM y la sesión HTTP tienen afinidad de hilo-sesión y no pueden ser utilizadas simultáneamente por varios hilos.

El sondeo largo se ajusta configurando el tiempo de espera de la operación HTTP (POST/GET/DELETE) según la configuración del servidor HTTP.

Ver también: DFree() DPIXGet() DPIXBorrar()

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

PIX Realiza una petición HTTP PUT segura siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Observación: Configure el tiempo de espera. Consulte más detalles en la sección Buenas prácticas.

Parámetros

[in] hSession Contexto adquirido a través de la función DOpenSession().

[in] szKeyId Nombre de la clave privada utilizada para cerrar el túnel. Corresponde a un certificado CPIC.

[in] szCertId Nombre del certificado utilizado para cerrar el túnel. Certificado digital del PSP registrado en el SPI para la conexión, también conocido como CPIC o CERTPIC.

[in] szPIXCertChainId PIX Nombre de la cadena PKCS#7 utilizada para comprobar el servidor (ICOM o DICT). A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas.

[in] szURL PIX URL del servidor (ICOM o DICT).

[in] dwCountRequestHeaderList Número de líneas rellenadas pszRequestHeaderList.

[in] pszRequestHeaderList Líneas que contienen las cabeceras HTTP personalizadas que se utilizarán en la petición. Se puede pasar null si se desea utilizar la cabecera por defecto sin cambios.
Esta opción sobrescribirá las cabeceras por defecto si se solapan.
Para eliminar una cabecera, pase el nombre de la cabecera sin un valor (p. ej. Acepta:).
Para incluir una cabecera sin contenido, utilice ; en lugar de : (Ej. Acepta;).
NO utilice terminadores CRLF en las cabeceras. Pasar estos terminadores puede causar un comportamiento no deseado. El formateo se realizará internamente.
Esta opción no puede utilizarse para modificar la primera línea de la petición (por ejemplo, POST, PUT, GET, DELETE), que no es una cabecera. Debe utilizarse la API correspondiente, descrita en este manual.
La cabecera inicial estándar incluye Host, User-Agent, Accept, Accept-Encoding, Expect y Content-Length.

[in] dwSizeRequestData Tamaño de los datos introducidos pbRequestData.

[in] pbRequestData Datos enviados en la solicitud.

[in] dwTimeOut Tiempo de espera de la operación en milisegundos. Puede establecerse en 0 para que no haya tiempo de espera.

[out] pdwSizeResponseHeaders Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseHeadersen bytes.

[out] ppbResponseHeaders Búfer asignado internamente que contendrá el cabecera devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseHeaders. Este puntero debe liberarse utilizando la API DFree().

[out] pdwSizeResponseBody Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseBodyen bytes.

[out] ppbResponseBody Búfer asignado internamente que contendrá el cuerpo devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseBody. Este puntero debe liberarse utilizando la API DFree().

[in]

dwParam

Valor	Significado
0	Opción por defecto. No comprueba el certificado con el nombre de host.
PIXVERIFICAR_NOMBRE_DE_HOST	Comprueba el certificado con el nombre del host.
PIXENCABEZADO_HTTP_BASICO	Utiliza la cabecera HTTP inicial básica. Incluye Host, User-Agent y Content-Length.
PIXGZIP	Comprime automáticamente los datos de la solicitud. Incluye automáticamente las cabeceras necesarias (Content-Encoding y Accept-Encoding).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

PIX Ejecuta una petición segura siguiendo el estándar definido en el SPI en los documentos: "Anexo IV - Manual de Seguridad", "Especificaciones técnicas y de negocio del ecosistema brasileño de pagos instantáneos" y "Anexo III - Manual de Interfaces de Comunicación" definidos en el SPI.
El túnel negociado es TLS versión 1.2 con autenticación mutua, utilizando el protocolo HTTP versión 1.1 con un Cipher Suite mínimo de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API descomprimirá automáticamente una respuesta que venga comprimida en el estándar gzip. Si decide comprimir los datos de envío, la persona que llame a la API deberá hacerlo en formato gzip.

Esta solicitud utiliza por defecto las siguientes cabeceras.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", donde 0.0.0.0 es la versión de la biblioteca cliente HSM utilizada.

La validación del certificado con el nombre de host se realiza comprobando que el campo Common Name o Subject Alternate Name del certificado coincide con el nombre de host de la URL pasada como parámetro.

Al realizar una petición HTTP, se efectúan 2 operaciones, una para utilizar los objetos HSM (clave privada, certificado y cadena, utilizados para autenticar el túnel) y otra para abrir la sesión HTTP con el servidor HTTP.
Para optimizar los recursos, la sesión con el servidor HTTP se mantiene abierta y se almacena en caché; del mismo modo, la sesión con el HSM se almacena en caché por defecto (la sesión del HSM puede configurarse opcionalmente para que no se almacene en caché).
La sesión HTTP está asociada a la sesión abierta con el HSM, lo que significa que para reutilizar una sesión HTTP hay que utilizar la misma sesión HSM que se utilizó previamente para abrir la sesión HTTP.
La sesión HTTP se cierra físicamente cuando se cierra físicamente la sesión con el HSM.
La sesión con el HSM y la sesión HTTP tienen afinidad de hilo-sesión y no pueden ser utilizadas simultáneamente por varios hilos.

El sondeo largo se ajusta configurando el tiempo de espera de la operación HTTP (POST/GET/DELETE) según la configuración del servidor HTTP.

Ver también: DFree() DPIXPut() DPIXGet() DPIXBorrar()

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

PIX Realiza una petición HTTP GET segura siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Observación: Configure el tiempo de espera. Consulte más detalles en la sección Buenas prácticas.

Parámetros

[in] hSession Contexto adquirido a través de la función DOpenSession().

[in] szKeyId Nombre de la clave privada utilizada para cerrar el túnel. Corresponde a un certificado CPIC.

[in] szCertId Nombre del certificado utilizado para cerrar el túnel. Certificado digital del PSP registrado en el SPI para la conexión, también conocido como CPIC o CERTPIC.

[in] szPIXCertChainId PIX Nombre de la cadena PKCS#7 utilizada para comprobar el servidor (ICOM o DICT). A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas.

[in] szURL PIX URL del servidor (ICOM o DICT).

[in] dwCountRequestHeaderList Número de líneas rellenadas pszRequestHeaderList.

[in] pszRequestHeaderList Líneas que contienen las cabeceras HTTP personalizadas que se utilizarán en la petición. Se puede pasar null si se desea utilizar la cabecera por defecto sin cambios.
Esta opción sobrescribirá las cabeceras por defecto si se solapan.
Para eliminar una cabecera, pase el nombre de la cabecera sin un valor (p. ej. Acepta:).
Para incluir una cabecera sin contenido, utilice ; en lugar de : (Ej. Acepta;).
NO utilice terminadores CRLF en las cabeceras. Pasar estos terminadores puede causar un comportamiento no deseado. El formateo se realizará internamente.
Esta opción no puede utilizarse para modificar la primera línea de la petición (por ejemplo, POST, PUT, GET, DELETE), que no es una cabecera. Debe utilizarse la API correspondiente, descrita en este manual.
La cabecera inicial estándar incluye Host, User-Agent, Accept, Accept-Encoding.

[in] dwTimeOut Tiempo de espera de la operación en milisegundos. Puede establecerse en 0 para que no haya tiempo de espera.

[out] pdwSizeResponseHeaders Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseHeadersen bytes.

[out] ppbResponseHeaders Búfer asignado internamente que contendrá el cabecera devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseHeaders. Este puntero debe liberarse utilizando la API DFree().

[out] pdwSizeResponseBody Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseBodyen bytes.

[out] ppbResponseBody Búfer asignado internamente que contendrá el cuerpo devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseBody. Este puntero debe liberarse utilizando la API DFree().

[in]

dwParam

Valor	Significado
0	Opción por defecto. No comprueba el certificado con el nombre de host.
PIXVERIFICAR_NOMBRE_DE_HOST	Comprueba el certificado con el nombre del host.
PIXENCABEZADO_HTTP_BASICO	Utiliza la cabecera HTTP inicial básica. Incluye Host y User-Agent.
PIXGZIP	Incluye la cabecera Accept-Encoding: gzip si la cabecera básica está activada.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

PIX Ejecuta una petición segura siguiendo el estándar definido en el SPI en los documentos: "Anexo IV - Manual de Seguridad", "Especificaciones técnicas y de negocio del ecosistema brasileño de pagos instantáneos" y "Anexo III - Manual de Interfaces de Comunicación" definidos en el SPI.
El túnel negociado es TLS versión 1.2 con autenticación mutua, utilizando el protocolo HTTP versión 1.1 con un Cipher Suite mínimo de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API descomprimirá automáticamente una respuesta que venga comprimida en el estándar gzip. Si decide comprimir los datos de envío, la persona que llame a la API deberá hacerlo en formato gzip.

Esta solicitud utiliza por defecto las siguientes cabeceras.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", donde 0.0.0.0 es la versión de la biblioteca cliente HSM utilizada.

La validación del certificado con el nombre de host se realiza comprobando que el campo Common Name o Subject Alternate Name del certificado coincide con el nombre de host de la URL pasada como parámetro.

Al realizar una petición HTTP, se efectúan 2 operaciones, una para utilizar los objetos HSM (clave privada, certificado y cadena, utilizados para autenticar el túnel) y otra para abrir la sesión HTTP con el servidor HTTP.
Para optimizar los recursos, la sesión con el servidor HTTP se mantiene abierta y se almacena en caché; del mismo modo, la sesión con el HSM se almacena en caché por defecto (la sesión del HSM puede configurarse opcionalmente para que no se almacene en caché).
La sesión HTTP está asociada a la sesión abierta con el HSM, lo que significa que para reutilizar una sesión HTTP hay que utilizar la misma sesión HSM que se utilizó previamente para abrir la sesión HTTP.
La sesión HTTP se cierra físicamente cuando se cierra físicamente la sesión con el HSM.
La sesión con el HSM y la sesión HTTP tienen afinidad de hilo-sesión y no pueden ser utilizadas simultáneamente por varios hilos.

El sondeo largo se ajusta configurando el tiempo de espera de la operación HTTP (POST/GET/DELETE) según la configuración del servidor HTTP.

Ver también: DFree() DPIXPost() DPIXGet() DPIXBorrar()

Ejemplos: post_put_get_delete_pix.c.

◆ DPIXBorrar()

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>

PIX Realiza una petición segura HTTP DELETE siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).

Observación: Configure el tiempo de espera. Consulte más detalles en la sección Buenas prácticas.

Parámetros

[in] hSession Contexto adquirido a través de la función DOpenSession().

[in] szKeyId Nombre de la clave privada utilizada para cerrar el túnel. Corresponde a un certificado CPIC.

[in] szCertId Nombre del certificado utilizado para cerrar el túnel. Certificado digital del PSP registrado en el SPI para la conexión, también conocido como CPIC o CERTPIC.

[in] szPIXCertChainId PIX Nombre de la cadena PKCS#7 utilizada para comprobar el servidor (ICOM o DICT). A partir de la versión 5.0.23 del firmware del HSM, es posible utilizar un objeto PKCS#7 que contenga varias cadenas.

[in] szURL PIX URL del servidor (ICOM o DICT).

[in] dwCountRequestHeaderList Número de líneas rellenadas pszRequestHeaderList.

[in] pszRequestHeaderList Líneas que contienen las cabeceras HTTP personalizadas que se utilizarán en la petición. Se puede pasar null si se desea utilizar la cabecera por defecto sin cambios.
Esta opción sobrescribirá las cabeceras por defecto si se solapan.
Para eliminar una cabecera, pase el nombre de la cabecera sin un valor (p. ej. Acepta:).
Para incluir una cabecera sin contenido, utilice ; en lugar de : (Ej. Acepta;).
NO utilice terminadores CRLF en las cabeceras. Pasar estos terminadores puede causar un comportamiento no deseado. El formateo se realizará internamente.
Esta opción no puede utilizarse para modificar la primera línea de la petición (por ejemplo, POST, PUT, GET, DELETE), que no es una cabecera. Debe utilizarse la API correspondiente, descrita en este manual.
La cabecera inicial estándar incluye Host, User-Agent, Accept, Accept-Encoding.

[in] dwTimeOut Tiempo de espera de la operación en milisegundos. Puede establecerse en 0 para que no haya tiempo de espera.

[out] pdwSizeResponseHeaders Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseHeadersen bytes.

[out] ppbResponseHeaders Búfer asignado internamente que contendrá el cabecera devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseHeaders. Este puntero debe liberarse utilizando la API DFree().

[out] pdwSizeResponseBody Puntero que contendrá el tamaño de los datos almacenados en el buffer ppbResponseBodyen bytes.

[out] ppbResponseBody Búfer asignado internamente que contendrá el cuerpo devuelto por la solicitud. El tamaño asignado se define en pdwSizeResponseBody. Este puntero debe liberarse utilizando la API DFree().

[in]

dwParam

Valor	Significado
0	Opción estándar para certificados SPB. No comprueba el certificado con el nombre de host.
PIXVERIFICAR_NOMBRE_DE_HOST	Comprueba el certificado con el nombre del host.
PIXENCABEZADO_HTTP_BASICO	Utiliza la cabecera HTTP inicial básica. Incluye Host y User-Agent.
PIXGZIP	Incluye la cabecera Accept-Encoding: gzip si la cabecera básica está activada.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

PIX Ejecuta una petición segura siguiendo el estándar definido en el SPI en los documentos: "Anexo IV - Manual de Seguridad", "Especificaciones técnicas y de negocio del ecosistema brasileño de pagos instantáneos" y "Anexo III - Manual de Interfaces de Comunicación" definidos en el SPI.
El túnel negociado es TLS versión 1.2 con autenticación mutua, utilizando el protocolo HTTP versión 1.1 con un Cipher Suite mínimo de ECDHE-RSA-AES-128-GCM-SHA256.

Esta API descomprimirá automáticamente una respuesta que venga comprimida en el estándar gzip. Si decide comprimir los datos de envío, la persona que llame a la API deberá hacerlo en formato gzip.

Esta solicitud utiliza por defecto las siguientes cabeceras.
"Accept-Encoding: gzip"
"User-Agent: DNLC/0.0.0.0", donde 0.0.0.0 es la versión de la biblioteca cliente HSM utilizada.

La validación del certificado con el nombre de host se realiza comprobando que el campo Common Name o Subject Alternate Name del certificado coincide con el nombre de host de la URL pasada como parámetro.

Al realizar una petición HTTP, se efectúan 2 operaciones, una para utilizar los objetos HSM (clave privada, certificado y cadena, utilizados para autenticar el túnel) y otra para abrir la sesión HTTP con el servidor HTTP.
Para optimizar los recursos, la sesión con el servidor HTTP se mantiene abierta y se almacena en caché; del mismo modo, la sesión con el HSM se almacena en caché por defecto (la sesión del HSM puede configurarse opcionalmente para que no se almacene en caché).
La sesión HTTP está asociada a la sesión abierta con el HSM, lo que significa que para reutilizar una sesión HTTP hay que utilizar la misma sesión HSM que se utilizó previamente para abrir la sesión HTTP.
La sesión HTTP se cierra físicamente cuando se cierra físicamente la sesión con el HSM.
La sesión con el HSM y la sesión HTTP tienen afinidad de hilo-sesión y no pueden ser utilizadas simultáneamente por varios hilos.

El sondeo largo se ajusta configurando el tiempo de espera de la operación HTTP (POST/GET/DELETE) según la configuración del servidor HTTP.

Ver también: DFree() DPIXPost() DPIXPut() DPIXGet()

Ejemplos: post_put_get_delete_pix.c.