Módulo Pix

Descripción detallada

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

Véase Documentación técnica de HSM sobre detalles de funcionamiento, especificaciones utilizadas, licencias e nombre comercial del módulo.

Buenas prácticas

General

1. 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.
2. 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.
3. 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

1. Reutiliza el identificador Pix. El identificador creado por DPIXOpenHandle() almacena las credenciales y los identificadores de los objetos, y no depende de que haya una sesión de HSM abierta. Mantén el identificador durante todo el tiempo que dure la aplicación, en lugar de abrirlo y cerrarlo con cada solicitud.
2. Abrir un identificador por hilo. Un handle puede ser utilizado por varios subprocesos, aunque nunca de forma simultánea. En el modo predeterminado, esto no implica una conexión por handle: todos comparten el caché de conexiones HTTP.
3. Establece un límite máximo de conexiones solo cuando el entorno lo requiera. El valor predeterminado es ilimitado, y la caché crece en función de la concurrencia de la aplicación. Configura HSM_PIX_POOL_MAX_HANDLES cuando exista una restricción en el número de conexiones simultáneas con el par. En ese caso, mide primero con los contadores de la caché (DPIXGetCacheParam()) y establece el límite a partir del valor más alto observado, en lugar de hacer una estimación.
4. Vaciar la caché, cuando el entorno lo requiera, para anticipar la sustitución de objetos. Los objetos del HSM se leen durante el handshake, por lo que las conexiones ya abiertas siguen utilizando los anteriores hasta que se vuelven a establecer. Si es necesario que la sustitución surta efecto de inmediato, la función DPIXSetCacheParam() con PIXCP_CLEAR hace que la siguiente solicitud se vuelva a conectar y vuelva a leer los objetos.

Ajustes importantes

General

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

1. 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)
	PIX Firma digitalmente un XML en formato ISO 20.022 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).
int AAP_API	DPIXVerify(HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedPIXEnvelope, BYTE *pbSignedPIXEnvelope)
	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).
int AAP_API	DPIXDictSign(HSESSIONCTX hSession, const char *szKeyId, const char *szCertId, DWORD dwFlags, DWORD dwSizeUnsignedDictEnvelope, BYTE *pbUnsignedDictEnvelope, DWORD *pdwSizeSignedDictEnvelope, BYTE **ppbSignedDictEnvelope)
	Firma digitalmente un XML en formato XMLDSig siguiendo el estándar DICT definido en el SPI (Sistema de Pago Instantáneo).
int AAP_API	DPIXDictVerify(HSESSIONCTX hSession, const char *szChainId, const char *szCRL, DWORD dwFlags, DWORD dwSizeSignedDictEnvelope, BYTE *pbSignedDictEnvelope)
	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).
int AAP_API	DPIXJWSSign(HSESSIONCTX hSession, const char *szKeyId, DWORD dwFlags, DWORD dwHeaderLen, BYTE *pbHeader, DWORD dwPayloadLen, BYTE *pbPayload, DWORD *pdwJWSLen, BYTE *pbJWS)
	PIX Realiza una firma JWS RFC 7515 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).
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)
	PIX Valida un JWS firmado RFC 7515 siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).
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)
	PIX Realiza una petición HTTP POST segura siguiendo el estándar definido en SPI (Sistema de Pago Instantáneo).
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)
	PIX Realiza una petición HTTP PUT segura siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).
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)
	PIX Realiza una petición HTTP GET segura siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).
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)
	PIX Realiza una petición segura HTTP DELETE siguiendo el estándar definido en el SPI (Sistema de Pago Instantáneo).
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)
	Crea un identificad PIX, que encapsula una conexión HTTP persistente y el material TLS (certificado, cadena y clave) utilizado en el túnel mTLS.
int AAP_API	DPIXCloseHandle (HPIXSESSIONCTX *phPIXSession, DWORD dwReserved)
	Destruye un identificador PIX creado mediante DPIXOpenHandle(), borrando de la memoria las credenciales almacenadas en él.
int AAP_API	DPIXGetHandleParam (HPIXSESSIONCTX hPIXSession, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
	Recupera información y contadores de un identificador « PIX ».
int AAP_API	DPIXSetCacheParam (DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwReserved)
	Configura la caché de sesiones HTTP de PIX, utilizada por las funciones DPIXPost(), DPIXPut(), DPIXGet() y DPIXDelete().
int AAP_API	DPIXGetCacheParam (DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
	Recupera la configuración y los contadores de la caché de sesiones HTTP de PIX.
int AAP_API	DPIXRequest (HPIXSESSIONCTX hPIXSession, const PIX_REQUEST *pstRequest, PIX_RESPONSE *pstResponse, DWORD dwReserved)
	Realiza una solicitud HTTP con un identificador PIX, para cualquier método.
int AAP_API	DPIXFreeResponse (PIX_RESPONSE *pstResponse)
	Libera los búferes de una PIX_RESPONSE rellenada por DPIXRequest().

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 JWS en pbPayload.
[in]	pbPayload	Buffer que contiene la carga útil JWS para firmar.
[in,out]	pdwJWSLen	Puntero al tamaño del búfer pbJWS, en 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 estimado requerido 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 estimado requerido de pbHeader.
[in,out]	pdwPayloadLen	Puntero al tamaño del búfer de 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 JWS. Si se pasa NULL, la API devolverá 0 y pdwPayloadLen contendrá el tamaño estimado requerido 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 en 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 (por ejemplo, Accept:). Para incluir una cabecera sin contenido, utilice ; en lugar de : (por ejemplo, Accept;). NO utilice terminadores CRLF en las cabeceras. Pasar estos terminadores puede causar un comportamiento no deseado. El formateo se hará internamente. Esta opción no puede utilizarse para cambiar 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 por defecto incluye Host, User-Agent, Accept, Accept-Encoding, Content-Type, Expect y Content-Length.
[in]	dwSizeRequestData	Tamaño de los datos pasados en 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 búfer ppbResponseHeaders, en bytes.
[out]	ppbResponseHeaders	Búfer asignado internamente que contendrá la cabecera devuelta por la petición. 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 ppbResponseBody, en bytes.
[out]	ppbResponseBody	Búfer asignado internamente que contendrá el cuerpo devuelto por la petición. 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 en 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 (por ejemplo, Accept:). Para incluir una cabecera sin contenido, utilice ; en lugar de : (por ejemplo, Accept;). 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 cambiar 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 por defecto incluye Host, User-Agent, Accept, Accept-Encoding, Expect y Content-Length.
[in]	dwSizeRequestData	Tamaño de los datos pasados en 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 búfer ppbResponseHeaders, en bytes.
[out]	ppbResponseHeaders	Búfer asignado internamente que contendrá la cabecera devuelta por la petición. 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 ppbResponseBody, en bytes.
[out]	ppbResponseBody	Búfer asignado internamente que contendrá el cuerpo devuelto por la petición. 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 en 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 (por ejemplo, Accept:). Para incluir una cabecera sin contenido, utilice ; en lugar de : (por ejemplo, Accept;). 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 cambiar 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 por defecto 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 búfer ppbResponseHeaders, en bytes.
[out]	ppbResponseHeaders	Búfer asignado internamente que contendrá la cabecera devuelta por la petición. 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 ppbResponseBody, en bytes.
[out]	ppbResponseBody	Búfer asignado internamente que contendrá el cuerpo devuelto por la petición. 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 en 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 (por ejemplo, Accept:). Para incluir una cabecera sin contenido, utilice ; en lugar de : (por ejemplo, Accept;). 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 cambiar 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 por defecto 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 búfer ppbResponseHeaders, en bytes.
[out]	ppbResponseHeaders	Búfer asignado internamente que contendrá la cabecera devuelta por la petición. 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 ppbResponseBody, en bytes.
[out]	ppbResponseBody	Búfer asignado internamente que contendrá el cuerpo devuelto por la petición. 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.

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>

Crea un identificad PIX, que encapsula una conexión HTTP persistente y el material TLS (certificado, cadena y clave) utilizado en el túnel mTLS.

El identificador es independiente de cualquier sesión con el HSM. La sesión se obtiene internamente, mediante DOpenSession(), únicamente durante el establecimiento de la conexión TLS, y se devuelve inmediatamente después. Las solicitudes que reutilizan la conexión no acceden al HSM.

Los parámetros dwParam, pbData, dwDataLen y dwFlags son exactamente los mismos que se pasarían a DOpenSession() y se almacenan en el identificador. Se borran de la memoria cuando el identificador se destruye con DPIXCloseHandle().

Parámetros

[out]	phPIXSession	Puntero que recibirá el handle creado.
[in]	szKeyId	Identificador de la clave privada utilizada en el túnel mTLS.
[in]	szCertId	Identificador del certificado del cliente.
[in]	szPIXCertChainId	Identificador de la cadena de certificados del par (PKCS#7).
[in]	dwParam	Tipo de autenticación, según DOpenSession().
[in]	pbData	Datos de autenticación, según DOpenSession().
[in]	dwDataLen	Tamaño de pbData, en bytes.
[in]	dwFlags	Parámetros de inicio de sesión, según DOpenSession().
[in]	dwPixFlags	Valor Significado 0 Estándar. El «handle» es una referencia ligera que no mantiene la conexión entre llamadas: cada solicitud toma una conexión de la caché de sesiones HTTP y la devuelve al finalizar. DN_PIX_NO_CACHE El identificador es exclusivo del llamante y mantiene la propia conexión HTTP hasta que se ejecuta DPIXCloseHandle().

Ambos modos siguen el mismo contrato de HSESSIONCTX: un identificador puede ser utilizado por varios subprocesos, aunque nunca de forma simultánea. Para realizar solicitudes en paralelo, abre un identificador por subproceso; en el modo predeterminado, esto no implica una conexión por identificador, ya que todos comparten la misma caché de conexiones HTTP.

Devolución

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

Ver también

DPIXCloseHandle() DOpenSession()

Ejemplos

pix_handle_no_cache.c, pix_handle_request.c y pix_handle_stats.c.

DPIXCloseHandle()

int AAP_API DPIXCloseHandle	(	HPIXSESSIONCTX *	phPIXSession,
		DWORD	dwReserved )

#include <dinamo.h>

Destruye un identificador PIX creado mediante DPIXOpenHandle(), borrando de la memoria las credenciales almacenadas en él.

El efecto sobre las conexiones depende de cómo se haya creado el identificador. Un handle DN_PIX_NO_CACHE es exclusivo, por lo que su conexión HTTP se cierra aquí. Un handle con caché no tiene conexión propia: solo se libera la referencia, y las conexiones de la caché siguen estando disponibles para otros usuarios hasta que el escáner de inactividad las cierre. Para cerrarlas de inmediato, utiliza DPIXSetCacheParam() con PIXCP_CLEAR.

Parámetros

[in,out]	phPIXSession	Puntero al handle. Devuelve NULL.
[in]	dwReserved	Reservado para uso futuro (debe ser 0).

Devolución

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

Ver también

DPIXOpenHandle()

Ejemplos

pix_handle_no_cache.c, pix_handle_request.c y pix_handle_stats.c.

DPIXGetHandleParam()

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

#include <dinamo.h>

Recupera información y contadores de un identificador « PIX ».

Los valores siempre corresponden al identificador indicado, en ambos modos. Un identificador con caché toma prestada una conexión en cada solicitud, pero registra el resultado en sí mismo al final de cada una: los contadores corresponden a las solicitudes realizadas por este identificador, y no a la conexión que las atendió.

Parámetros

[in]	hPIXSession	PIX.
[in]	dwParam	Valor Significado PIXP_HTTP_RET Tipo de pbData: ND_uint64_t Código de respuesta HTTP de la última solicitud. PIXP_HTTP_REQ_DETAILS Tipo de pbData: PIX_HTTP_REQUEST_DETAILS Detalles de la última solicitud. PIXP_STATS Tipo de pbData: PIX_HANDLE_STATS Contadores acumulados del handle. El campo dwVersion debe rellenarse con PIX_HANDLE_STATS_VERSION antes de la llamada.
[out]	pbData	Buffer que recibirá el valor. Pasa NULL para consultar el tamaño necesario: la función escribe el tamaño en pdwDataLen y devuelve cero, siguiendo la convención de DGetSessionParam().
[in,out]	pdwDataLen	Tamaño de pbData en la entrada; tamaño necesario o escrito en la salida. Si el búfer es menor que el necesario, la función devuelve D_MORE_DATA y escribe aquí el tamaño requerido.
[in]	dwReserved	Reservado para uso futuro (debe ser 0).

Devolución

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

Ver también

DPIXOpenHandle()

Ejemplos

pix_handle_stats.c.

DPIXSetCacheParam()

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

#include <dinamo.h>

Configura la caché de sesiones HTTP de PIX, utilizada por las funciones DPIXPost(), DPIXPut(), DPIXGet() y DPIXDelete().

La caché tiene un ámbito de biblioteca. Los identificadores creados explícitamente sin caché mediante DPIXOpenHandle() pertenecen a quien los ha creado, no se almacenan en la caché y no se ven afectados por esta función.

Parámetros

[in]	dwParam	Valor Significado PIXCP_CLEAR Tipo de pbData: NULL Marca las sesiones HTTP de la caché para que se cierren. Las que estén inactivas se cierran inmediatamente. Las sesiones que estén en uso se cierran al finalizar la solicitud en curso, en lugar de volver a la caché. PIXCP_MAX_HANDLES Tipo de pbData: DWORD Número máximo de sesiones HTTP almacenadas en la caché. El valor cero significa que no hay límite. Reducir este valor no cierra las sesiones ya existentes, sino que solo impide la creación de otras nuevas. Equivale a la variable de entorno HSM_PIX_POOL_MAX_HANDLES. PIXCP_IDLE_TTL Tipo de pbData: DWORD Tiempo, en segundos, tras el cual se cierra una sesión HTTP inactiva. El valor cero desactiva esta opción. Equivale a la variable de entorno HSM_PIX_POOL_IDLE_TTL.
[in]	pbData	Valor por definir, según dwParam.
[in]	dwDataLen	Tamaño de pbData, en bytes.
[in]	dwReserved	Reservado para uso futuro (debe ser 0).

Devolución

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

Ver también

DPIXGetCacheParam() DPIXOpenHandle()

Ejemplos

pix_handle_stats.c.

DPIXGetCacheParam()

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

#include <dinamo.h>

Recupera la configuración y los contadores de la caché de sesiones HTTP de PIX.

Parámetros

[in]	dwParam	Valor Significado PIXCP_MAX_HANDLES Tipo de pbData: DWORD Número máximo de sesiones HTTP en la caché. PIXCP_IDLE_TTL Tipo de pbData: DWORD Tiempo de inactividad, en segundos, para cerrar una sesión HTTP. PIXCP_STATS Tipo de pbData: PIX_POOL_STATS Contadores de la caché. El campo dwVersion debe rellenarse con PIX_POOL_STATS_VERSION antes de la llamada.
[out]	pbData	Buffer que recibirá el valor. Pasa NULL para consultar el tamaño necesario: la función escribe el tamaño en pdwDataLen y devuelve cero, siguiendo la convención de DGetSessionParam().
[in,out]	pdwDataLen	Tamaño de pbData en la entrada; tamaño necesario o escrito en la salida. Si el búfer es menor que el necesario, la función devuelve D_MORE_DATA y escribe aquí el tamaño requerido.
[in]	dwReserved	Reservado para uso futuro (debe ser 0).

Devolución

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

Ver también

DPIXSetCacheParam()

Ejemplos

pix_handle_stats.c.

DPIXRequest()

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

#include <dinamo.h>

Realiza una solicitud HTTP con un identificador PIX, para cualquier método.

El método se indica en #PIX_REQUEST::method, y los parámetros de entrada y el resultado se almacenan en estructuras, de modo que añadir un campo en el futuro no modifica la firma de esta función.

La conexión HTTP y los datos TLS proceden de hPIXSession, no de una sesión con el HSM: la clave, el certificado y la cadena se han definido en DPIXOpenHandle().

Los búferes de pstResponse se asignan internamente. Libéralos con DPIXFreeResponse(), incluso cuando la función devuelva un error, ya que es posible que se haya recibido una respuesta parcial antes del fallo.

pstResponse se pone a cero justo al inicio de la llamada. La única excepción es un dwVersion no válido: en ese caso, no se modifica la estructura, ya que se desconoce su formato.

Parámetros

[in]	hPIXSession	Mánula « PIX » creada mediante DPIXOpenHandle().
[in]	pstRequest	Datos de la solicitud. El campo dwVersion debe rellenarse con PIX_REQUEST_VERSION antes de la llamada.
[out]	pstResponse	Respuesta recibida. El campo dwVersion debe rellenarse con PIX_RESPONSE_VERSION antes de la llamada. Puede ser NULL para descartar la respuesta.
[in]	dwReserved	Reservado para uso futuro (debe ser 0).

Devolución

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

Ver también

DPIXOpenHandle() DPIXFreeResponse() DPIXPost()

Ejemplos

pix_handle_no_cache.c, pix_handle_request.c y pix_handle_stats.c.

DPIXFreeResponse()

int AAP_API DPIXFreeResponse

(

PIX_RESPONSE *

pstResponse

)

#include <dinamo.h>

Libera los búferes de una PIX_RESPONSE rellenada por DPIXRequest().

Borra todos los campos excepto dwVersion (para mantener el diseño). Como los punteros se ponen a cero, es seguro llamarla dos veces. Pasar NULL no tiene ningún efecto.

Parámetros

[in,out]

pstResponse

Respuesta pendiente de publicación.

Devolución

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

Ver también

DPIXRequest()

Ejemplos

pix_handle_no_cache.c, pix_handle_request.c y pix_handle_stats.c.