SPB

Descripción detallada

Operaciones de codificación y descodificación según la norma SPB.

Consulte la documentación técnica del HSM.

Funciones
int AAP_API	DSPBEncodeInit(HSESSIONCTX hSession, char *szSrcISPB, char *szDstISPB, DWORD dwTotalDataLen, BYTE bErrorCode, BYTE bSpecialTreatment, HSPBCTX *hSPBCtx, DWORD dwFlags)
int AAP_API	DSPBEncodeCont(HSPBCTX hSPBCtx, BYTE *pbDataIn, DWORD dwDataInLen, BYTE *pbDataOut, DWORD *pdwDataOutLen)
int AAP_API	DSPBEncodeEnd(HSPBCTX *hSPBCtx, BYTE *pbSPBHeader, DWORD *pdwSPBHeaderLen)
int AAP_API	DSPBDecodeInit(HSESSIONCTX hSession, char *szSrcISPB, char *szDstISPB, BYTE *pbHeader, DWORD dwHeaderLen, BYTE bAcceptExpiredCert, BYTE bAutoUpdateCert, DWORD dwMessageDataLen, HSPBCTX *hSPBCtx, DWORD dwFlags)
int AAP_API	DSPBDecodeCont(HSPBCTX hSPBCtx, BYTE *pbDataIn, DWORD dwDataInLen, BYTE **ppbDataOut, DWORD *pdwDataOutLen)
int AAP_API	DSPBDecodeEnd(HSPBCTX *hSPBCtx)
int AAP_API	DSPBGenerateKey(HSESSIONCTX hSession, char *szID, char *szPrivateKeyName, DWORD dwKeyParam, DWORD dwParam)
int AAP_API	DSPBGenerateCSR(HSESSIONCTX hSession, char *szPrivateKeyName, BYTE bVersion, char *szSPBSubject, DWORD dwOutType, DWORD *pdwCSRLen, BYTE **ppbCSR, DWORD dwParam)
int AAP_API	DSPBImportCertificate(HSESSIONCTX hSession, BYTE bActivate, const char *szUser, BYTE *pbCertificate, DWORD dwCertificateLen, const char *szDomain, DWORD dwParam)
int AAP_API	DSPBImportPKCS12(HSESSIONCTX hSession, BYTE bActivate, const char *szUser, const char *szPkcs12File, const char *szPkcs12Pwd, const char *szDomain, DWORD dwKeyAttr)
int AAP_API	DSPBExportPKCS12 (const HSESSIONCTX hSession, const char *szPkcs12Pwd, const char *szISPB, const char *szReserved, BYTE **ppbPkcs12, DWORD *pdwPkcs12Len, DWORD dwReserved)
int AAP_API	DSPBActivateCertificate(HSESSIONCTX hSession, const char *szIdCert, const char *szDomain, DWORD dwParam)
int AAP_API	DSPBGetCertificate(HSESSIONCTX hSession, const char *szIdCert, BYTE **ppbCertificate, DWORD *pdwCertificateLen, DWORD dwParam)
int AAP_API	DSPBCalculateObjectId (char *szISPB, char *szDomain, DWORD dwKeyType, char *szOutObjName, DWORD dwParam)
int AAP_API	DSPBMapInfo(HSESSIONCTX hSession, const char *szIdCert, EXT_MAP_2_OBJ_INFO *pstExtMap, DWORD dwParam)
int AAP_API	DSPBSetISPBMap(HSESSIONCTX hSession, char *szISPB, char *szKeyId, char *szCertId, DWORD dwParam)

Funciones

DSPBEncodeInit()

int AAP_API DSPBEncodeInit	(	HSESSIONCTX	hSession,
		char *	szSrcISPB,
		char *	szDstISPB,
		DWORD	dwTotalDataLen,
		BYTE	bErrorCode,
		BYTE	bSpecialTreatment,
		HSPBCTX *	hSPBCtx,
		DWORD	dwFlags )

#include <dinamo.h>

Inicia una operación de codificación de mensajes SPB.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szSrcISPB	Identificador de la institución de origen con tamaño máximo MAX_OBJ_ID_FQN_LEN. El identificador de la fuente debe tener el siguiente formato: ISPB@DOMINIO, siendo opcional la parte del dominio. El tamaño exacto para la JNSP es ND_SPB_ISPB_LEN y el tamaño máximo de DOMINIO es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador del DOMINIO. El nombre del mapa correspondiente, fuera de la norma de denominación del módulo SPB, también puede transmitirse en casos específicos, véase dwFlags.
[in]	szDstISPB	Tamaño máximo del identificador de la institución de destino MAX_OBJ_ID_FQN_LEN. El identificador de destino debe tener el siguiente formato: ISPB@DOMINIO, siendo opcional la parte del dominio. El tamaño de la JNSP es ND_SPB_ISPB_LEN y el tamaño máximo de DOMINIO es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador del DOMINIO. El nombre del mapa correspondiente, fuera de la norma de denominación del módulo SPB, también puede transmitirse en casos específicos, véase dwFlags.
[in]	dwTotalDataLen	Tamaño total en bytes del mensaje a codificar.
[in]	bErrorCode	Código de error del mensaje que se colocará en la cabecera de seguridad, normalmente en los mensajes de respuesta.
[in]	bSpecialTreatment	Código especial de tratamiento de mensajes, según el manual del Banco Central.
[out]	hSPBCtx	Puntero al contexto de la operación de codificación SPB. Tras su uso, debe liberarse con la función DSPBEncodeEnd().
[in]	dwFlags	Define los detalles de codificación y puede adoptar los siguientes valores descritos en la tabla siguiente. Valor Significado 0 Utiliza el estándar SPB (Sistema Brasileño de Pagos). ND_SPB_ENCODE_GEN_01 Genera un mensaje GEN 01. ND_SPB_USO_CIP1 Utiliza el estándar CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea. Cuando esta bandera no está activada, se utiliza el estándar SPB (Sistema Brasileño de Pagos). Compatible con C3 Nuclea. ND_SPB_USE_ANY Acepta el estándar CIP/C3 Nuclea y SPB. La detección se realiza internamente. ND_SPB_ENCODE_HEADER_V3 Codifica el mensaje utilizando la cabecera de seguridad versión 3. En el futuro, esta opción estará activada por defecto. La cabecera V3 está disponible a partir de la versión 5.0.16 del firmware del HSM. ND_SPB_RAW Modo sin comprobaciones específicas de SPB. Sólo acepta el uso del nombre MAP como parámetros para szSrcISPB e szDstISPB.

Devolución

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

Notas

DSPBEncodeCont() y DSPBEncodeEnd() deben ser llamadas para enviar el mensaje y finalizar la codificación. Incluso en caso de error, libere siempre el contexto de la operación mediante DSPBEncodeEnd().
Tipos de certificado:
SPB - El OU debe contener el ISPB en el formato de prefijo "ISPB-" + 8 dígitos. Por ejemplo: ISPB-11111111.
CIP1 - La OU debe contener el ISPB en formato de 8 dígitos. Por ejemplo: 11111111.

Ejemplos

spb_enc_dec.c.

DSPBEncodeCont()

int AAP_API DSPBEncodeCont	(	HSPBCTX	hSPBCtx,
		BYTE *	pbDataIn,
		DWORD	dwDataInLen,
		BYTE *	pbDataOut,
		DWORD *	pdwDataOutLen )

#include <dinamo.h>

Envía partes o la totalidad del mensaje para su codificación en el HSM.

Parámetros

[in]	hSPBCtx	Contexto adquirido a través de la función DSPBEncodeInit().
[in]	pbDataIn	Buffer que contiene una parte o la totalidad del mensaje a codificar. El tamaño por llamada es DN_SPB_MAX_NOTIFY_DATA_SEG bytes. Se pueden enviar tamaños más pequeños si se trata del último o único fragmento del mensaje.
[in]	dwDataInLen	Tamaño del búfer en bytes pbDataIn.
[out]	pbDataOut	Búfer que recibirá los datos del mensaje codificado. Debe ser igual o superior a pbDataIn. Si es la última pieza, añada espacio en el tamaño para un posible relleno/etiqueta. Recomendamos utilizar un tamaño mínimo de DN_SPB_MAX_RCV_NOTIFY_DATA_SEG bytes para garantizar que se reciben todos los datos devueltos.
[in,out]	pdwDataOutLen	Puntero a un DWORD que contiene el tamaño de pbDataOut. La entrada debe contener el tamaño del buffer apuntado por pbDataOut, la salida contiene el tamaño de los datos que fueron codificados en pbDataOut.

Devolución

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

Notas

Incluso en caso de error, libere siempre el contexto de la operación mediante DSPBEncodeEnd().

Ejemplos

spb_enc_dec.c.

DSPBEncodeEnd()

int AAP_API DSPBEncodeEnd	(	HSPBCTX *	hSPBCtx,
		BYTE *	pbSPBHeader,
		DWORD *	pdwSPBHeaderLen )

#include <dinamo.h>

Finaliza una operación de cifrado SPB y recibe la cabecera de seguridad.

Parámetros

[in]	hSPBCtx	Puntero al contexto adquirido a través de la función DSPBEncodeInit().
[out]	pbSPBHeader	Buffer que contiene la cabecera de seguridad del mensaje codificado. Debe tener un tamaño igual o superior a DN_SPB_MSG_HEADER_V2_LEN bytes.
[in,out]	pdwSPBHeaderLen	Puntero a un DWORD que al entrar debe contener el tamaño del buffer apuntado por pbSPBHeader, y al salir contendrá el tamaño de la cabecera escrita en pbSPBHeader.

Devolución

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

Ejemplos

spb_enc_dec.c.

DSPBDecodeInit()

int AAP_API DSPBDecodeInit	(	HSESSIONCTX	hSession,
		char *	szSrcISPB,
		char *	szDstISPB,
		BYTE *	pbHeader,
		DWORD	dwHeaderLen,
		BYTE	bAcceptExpiredCert,
		BYTE	bAutoUpdateCert,
		DWORD	dwMessageDataLen,
		HSPBCTX *	hSPBCtx,
		DWORD	dwFlags )

#include <dinamo.h>

Inicia una operación de descodificación de mensajes SPB.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szSrcISPB	Identificador de la institución de origen con tamaño máximo MAX_OBJ_ID_FQN_LEN. El identificador de la fuente debe tener el siguiente formato: BISF@DOMINIO, siendo opcional la parte del dominio. La longitud exacta para ISPB es ND_SPB_ISPB_LEN y el tamaño máximo de DOMINIO es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador del DOMINIO. También puede pasar el nombre del mapa correspondiente, fuera de la norma de denominación del módulo SPB en casos específicos, véase dwFlags.
[in]	szDstISPB	Identificador de la institución de destino con tamaño máximo MAX_OBJ_ID_FQN_LEN. El identificador de destino debe tener el siguiente formato: ISPB@DOMINIO. El tamaño para ISPB es ND_SPB_ISPB_LEN y el tamaño máximo de DOMINIO es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador del DOMINIO. También puede pasar el nombre del mapa correspondiente, fuera de la norma de denominación del módulo SPB en casos específicos, véase dwFlags.
[in]	pbHeader	Buffer que contiene la cabecera de seguridad del mensaje SPB a descodificar.
[in]	dwHeaderLen	Tamaño en bytes del búfer pbHeader.
[in]	bAcceptExpiredCert	Byte para aceptar certificados caducados al descodificar el mensaje. Pase 1 para aceptar y 0 para no aceptar.
[in]	bAutoUpdateCert	Activa o desactiva la actualización automática de certificados en la base de datos del HSM si el mensaje es un intercambio de certificados. Actualmente se gestionan los siguientes mensajes: GEN0006 (respuesta), GEN0007, GEN0008 (respuesta) y GEN0018. El certificado se importa y se activa automáticamente, excepto en el caso de GEN0018 (certificado del Banco Central), en el que el certificado se importa pero no se activa. Introduzca 1 para activado y 0 para desactivado.
[in]	dwMessageDataLen	Tamaño total del mensaje SPB a descodificar.
[out]	hSPBCtx	Puntero al contexto de la operación de descodificación SPB. Tras su uso, debe liberarse con la función DSPBDecodeEnd().
[in]	dwFlags	Define los detalles de descodificación y puede adoptar los siguientes valores descritos en la tabla siguiente. Valor Significado 0 Utiliza el estándar SPB (Sistema Brasileño de Pagos). ND_SPB_OUT_NO_PADDING Elimina el relleno del final del mensaje SPB tras el descifrado. ND_SPB_OUT_WITH_PADDING Mantiene el relleno al final del mensaje SPB tras el descifrado. ND_SPB_USO_CIP1 Utiliza el estándar CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea. Cuando este indicador no está activado, se utiliza el estándar SPB (Sistema Brasileño de Pagos). ND_SPB_USE_ANY Acepta el estándar CIP/C3 Nuclea y SPB. La detección se realiza internamente. ND_SPB_RAW Modo sin comprobaciones específicas de SPB. Sólo acepta el uso del nombre MAP como parámetros para szSrcISPB e szDstISPB.

Devolución

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

Notas

Se debe llamar a DSPBDecodeCont() y DSPBDecodeEnd() para enviar el mensaje y finalizar la codificación. Incluso en caso de error, libere siempre el contexto de operación utilizando DSPBDecodeEnd(). La gestión de GEN0006R1 (respuesta GEN0006) está disponible a partir de la versión de firmware 5.0.16.
Tipos de certificado:
SPB - El OU debe contener el ISPB en el formato de prefijo "ISPB-" + 8 dígitos. Por ejemplo: ISPB-11111111.
CIP1 - La OU debe contener el BIPP en formato de 8 dígitos. Por ejemplo: 11111111.

Ejemplos

spb_enc_dec.c.

DSPBDecodeCont()

int AAP_API DSPBDecodeCont	(	HSPBCTX	hSPBCtx,
		BYTE *	pbDataIn,
		DWORD	dwDataInLen,
		BYTE **	ppbDataOut,
		DWORD *	pdwDataOutLen )

#include <dinamo.h>

Envía partes o la totalidad del mensaje para su descodificación en el HSM.

Parámetros

[in]	hSPBCtx	Contexto adquirido a través de la función DSPBDecodeInit.
[in]	pbDataIn	Buffer que contiene una parte o la totalidad del mensaje a descodificar. El tamaño por llamada es de ND_SPB_MAX_NOTIFY_DATA_SEG bytes. Pueden enviarse tamaños menores si se trata del último o único fragmento del mensaje.
[in]	dwDataInLen	Tamaño del búfer en bytes pbDataIn.
[out]	ppbDataOut	Puntero que recibirá los datos codificados. El tamaño del búfer asignado está disponible a través de pdwDataOutLen. La asignación de memoria se realiza internamente. La desasignación se realiza en la siguiente llamada a DSPBDecodeCont() o DSPBDecodeEnd().
[out]	pdwDataOutLen	Puntero al tamaño del buffer asignado internamente en ppbDataOut.

Devolución

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

Ejemplos

spb_enc_dec.c.

DSPBDecodeEnd()

int AAP_API DSPBDecodeEnd

(

HSPBCTX *

hSPBCtx

)

#include <dinamo.h>

Finaliza una operación de descodificación SPB y recibe la cabecera de seguridad.

Parámetros

[in]

hSPBCtx

Puntero al contexto adquirido mediante la función DSPBDecodeInit().

Devolución

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

Ejemplos

spb_enc_dec.c.

DSPBGenerateKey()

int AAP_API DSPBGenerateKey	(	HSESSIONCTX	hSession,
		char *	szID,
		char *	szPrivateKeyName,
		DWORD	dwKeyParam,
		DWORD	dwParam )

#include <dinamo.h>

Genera una clave privada según el estándar SPB. Se trata de una función especializada de la API de generación de claves HSM.
La aplicación genera la clave (RSA 2048 o según lo establecido en el manual actualizado de Bacen) con la identificación siguiendo la ley de formación interna, descrita en la presentación del módulo SPB.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szID	Identificador de la institución a la que se destina la clave privada. El identificador de la institución debe tener el siguiente formato: "ISPB@DOMINIO", siendo opcional la parte del dominio. La longitud exacta para ISPB es ND_SPB_ISPB_LEN y la longitud máxima para DOMINIO es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador de DOMINIO.
[out]	szPrivateKeyName	Búfer de tamaño MAX_OBJ_ID_FQN_LEN o superior. Este búfer recibirá una cadena que contiene el identificador del par de claves generado en el HSM. Este identificador debe ser conservado por la aplicación para su uso posterior en DSPBGenerateCSR() y/u otros.
[in]	dwKeyParam	Parámetros adicionales de la clave. Consulte las opciones de la función DGenerateKey().
[in]	dwParam	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.

Ejemplos

spb_gen_key_csr.c.

DSPBGenerarCSR()

int AAP_API DSPBGenerateCSR	(	HSESSIONCTX	hSession,
		char *	szPrivateKeyName,
		BYTE	bVersion,
		char *	szSPBSubject,
		DWORD	dwOutType,
		DWORD *	pdwCSRLen,
		BYTE **	ppbCSR,
		DWORD	dwParam )

#include <dinamo.h>

Genera una CSR (solicitud de firma de certificado) para SPB. Se trata de una función especializada de la API de generación de CSR PKCS#10 de HSM.
No existen reglas de validación para los certificados SPB; esto depende de la aplicación, que puede generar CSR para diferentes sistemas, como SPB y CIP.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szPrivateKeyName	Identificador de la clave privada. Normalmente la cadena generada en DSPBGenerateKey().
[in]	bVersion	CSR versión PKCS#10. Se admite la siguiente tabla. Valor Significado CORE_P10_CSR_VERSION1 PKCS#10 CSR versión 1.
[in]	szSPBSubject	DN (Dinstinguished Name), para generar la CSR, con un tamaño máximo de CORE_P10_CSR_DN_MAX_LEN. Los campos DN deben estar separados por '/'.
[in]	dwOutType	Tipo de salida CSR. Se admite la siguiente tabla. Valor Significado P10_CSR_DER Exporta el CSR en formato DER. P10_CSR_PEM Exporta el CSR en formato PEM.
[out]	pdwCSRLen	Puntero al tamaño del búfer asignado en ppbCSR.
[out]	ppbCSR	Puntero que recibirá el CSR. El tamaño del búfer asignado estará disponible a través de pdwCSRLen. La asignación de memoria se realiza internamente. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree().
[in]	dwParam	Parámetros adicionales. Se admite la siguiente tabla. Valor Significado 0 Utiliza el hash estándar HSM en la firma CSR. CORE_P10_HASH_SHA1 Utiliza SHA-1 en la firma CSR. CORE_P10_HASH_SHA224 Utiliza SHA-224 en la firma CSR. CORE_P10_HASH_SHA256 Utiliza SHA-256 en la firma CSR. CORE_P10_HASH_SHA384 Utiliza SHA-384 en la firma CSR. CORE_P10_HASH_SHA512 Utiliza SHA-512 en la firma CSR.

Notas

Ejemplos de campo DN.

/CN=BANCO TESTE S/A P001/OU=SISBACEN-00888/OU=ISPB-54444619/O=ICP-Brasil/L=Sao Paulo/S=Sao Paulo/C=BR

Devolución

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

Ejemplos

spb_gen_key_csr.c.

DSPBImportCertificate()

int AAP_API DSPBImportCertificate	(	HSESSIONCTX	hSession,
		BYTE	bActivate,
		const char *	szUser,
		BYTE *	pbCertificate,
		DWORD	dwCertificateLen,
		const char *	szDomain,
		DWORD	dwParam )

#include <dinamo.h>

Importa un certificado SPB y lo asocia a un par de claves dentro del HSM (mediante un objeto map), si existe tal clave.

La aplicación no necesita indicar si se trata de su propio certificado o del de un tercero; el HSM busca una clave privada que se corresponda con la clave pública del certificado y, si la encuentra, la asocia al mapa correspondiente. Cuando no se encuentra una clave privada correspondiente, se supone que el certificado pertenece a un tercero. Esta búsqueda interna por parte del HSM hace que la operación sea más rápida, atómica y segura, ya que la biblioteca no necesita realizar operaciones de exportación y búsquedas locales.

El certificado se crea en la base de HSM con la ley de formación de nombres definida. HSM analiza el certificado para recuperar campos como ISPB.

Si el HSM encuentra la clave privada, se crea un mapa identificado por MD5(CA+NS), colocando el id de la clave en la ranura1 y el id del certificado recién importado en la ranura2. Devuelve un error si el mapa ya existe. Este es el caso de un certificado propio.

Si el firmware no encuentra la clave privada, se crea un mapa identificado por MD5(CA+NS), dejando slot1 vacío y slot2 con el id del certificado recién importado. Devuelve un error si el mapa ya existe. Este es el caso de un certificado de terceros.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	bActivate	Activa automáticamente el certificado al importarlo. Introduzca 1 para activar y 0 para importar sin activar el certificado.
[in]	szUser	Nombre de usuario, para importar el certificado, con longitud máxima(MAX_USR_LEN+1). Puede ser NULL si la importación se realiza desde la sesión actual del usuario.
[in]	pbCertificate	Buffer que contiene el certificado a importar. El certificado puede estar en formato PEM o DER.
[in]	dwCertificateLen	Tamaño del búfer al que apunta pbCertificado.
[in]	szDomain	Dominio de mensaje del certificado que se va a activar. Debe tener un tamaño máximo de(ND_SPB_DOMAIN_MAX_LEN + 1). Puede ser NULL si no se ha definido ningún dominio.
[in]	dwParam	Se admite la siguiente tabla de banderas. Valor Significado 0 Utiliza el estándar SPB (Sistema Brasileño de Pagos). ND_SPB_USO_CIP1 Utiliza la norma CIP (Cámara Interbancaria de Pagamentos). ND_SPB_USE_ANY Acepta el estándar CIP y SPB. La detección se realiza internamente.

Devolución

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

Notas

Tipos de certificados:
SPB - El OU debe contener el ISPB en el formato de prefijo "ISPB-" + 8 dígitos. Por ejemplo: ISPB-11111111.
CIP1 - La OU debe contener el BIPP en formato de 8 dígitos. Por ejemplo: 11111111.

Ejemplos

spb_gen_key_csr.c.

DSPBImportPKCS12()

int AAP_API DSPBImportPKCS12	(	HSESSIONCTX	hSession,
		BYTE	bActivate,
		const char *	szUser,
		const char *	szPkcs12File,
		const char *	szPkcs12Pwd,
		const char *	szDomain,
		DWORD	dwKeyAttr )

#include <dinamo.h>

Importe un par de claves y un certificado desde un archivo PKCS#12.

El certificado y la clave privada se crean en la base del HSM con la ley de formación de nombres definida. El HSM analiza el certificado para recuperar campos como CA y NS.

En el proceso de importación se crea un mapa identificado por MD5(CA+NS), en slot1 va el id de la clave y en slot2 el id del certificado. Devuelve un error si el mapa ya existe, es decir, si el certificado y la clave privada ya existen en la base de datos del HSM.

Esta API detecta automáticamente si se trata de un certificado SPB o CIP.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	bActivate	Activa automáticamente el certificado al importarlo. Introduzca 1 para activar y 0 para importar sin activar el certificado.
[in]	szUser	Nombre del usuario donde se creará la clave. Puede ser NULL si la clave se crea en el usuario autenticado.
[in]	szPkcs12File	Nombre de archivo PKCS#12 para la importación.
[in]	szPkcs12Pwd	Contraseña del archivo PKCS#12 para la importación.
[in]	szDomain	Dominio de mensaje del certificado que se va a activar. Debe tener un tamaño máximo de(ND_SPB_DOMAIN_MAX_LEN + 1). cPuede ser NULL si no se ha definido ningún dominio.
[in]	dwKeyAttr	Parámetros adicionales de la clave. Consulte las opciones de la función DGenerateKey().

Devolución

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

Ejemplos

spb_activate_cert.c, spb_enc_dec.c, spb_get_cert.c y spb_import_p12.c.

DSPBExportPKCS12()

int AAP_API DSPBExportPKCS12	(	const HSESSIONCTX	hSession,
		const char *	szPkcs12Pwd,
		const char *	szISPB,
		const char *	szReserved,
		BYTE **	ppbPkcs12,
		DWORD *	pdwPkcs12Len,
		DWORD	dwReserved )

#include <dinamo.h>

Exporta un par de claves y un certificado en formato PKCS#12 desde un HSM.

Esta llamada acepta identificadores de certificado/clave privada en formatos CA@SN e ISPB@DOM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szPkcs12Pwd	Contraseña para el archivo PKCS#12. Pase NULL para generar PKCS#12 sin contraseña.
[in]	szISPB	Identificador del certificado/clave privada en formato CA@SN, ISPB o ISPB@DOM.
[in]	szReserved	Reservado para uso futuro (debe ser NULL).
[out]	ppbPkcs12	Puntero a un puntero que contendrá el PKCS#12 generado. Esta área de datos se asignará internamente y debe liberarse utilizando DFree().
[out]	pdwPkcs12Len	Puntero al tamaño de los datos escritos en ppbPkcs12.
[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.

DSPBActivateCertificate()

int AAP_API DSPBActivateCertificate	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		const char *	szDomain,
		DWORD	dwParam )

#include <dinamo.h>

Activa un certificado SPB en el HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szIdCert	Identificador del certificado a activar. El identificador del certificado debe tener el siguiente formato: CA@SN. El tamaño para CA es ND_SPB_CA_LEN y el tamaño para SN es ND_SPB_SN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 03@12345678 donde 03 es el identificador de CA y 12345678 es el número de serie del certificado.
[in]	szDomain	Dominio de mensaje del certificado que se va a activar. Debe tener un tamaño máximo de(ND_SPB_DOMAIN_MAX_LEN + 1). Puede ser NULL si no se ha definido ningún dominio.
[in]	dwParam	Reservado para uso futuro.

Devolución

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

Ejemplos

spb_activate_cert.c.

DSPBGetCertificate()

int AAP_API DSPBGetCertificate	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		BYTE **	ppbCertificate,
		DWORD *	pdwCertificateLen,
		DWORD	dwParam )

#include <dinamo.h>

Activa un certificado SPB en el HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szIdCert	Identificación del certificado a recuperar. El identificador del certificado puede tener los siguientes formatos: ID, CA@SN o ISPB@DOMINIO. La longitud exacta para CA es ND_SPB_CA_LEN y la longitud máxima para SN es ND_SPB_SN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 03@12345678 donde 03 es el identificador de CA y 12345678 es el ISPB de la institución. El tamaño exacto para ISPB es ND_SPB_ISPB_LEN y el tamaño máximo para DOMINIO es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador de DOMINIO.
[out]	ppbCertificate	Puntero que recibirá el certificado. El tamaño del búfer asignado estará disponible a través de pdwCertificateLen. La asignación de memoria se realiza internamente por la biblioteca. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree().
[out]	pdwCertificateLen	Puntero al tamaño del búfer apuntado por ppbCertificate.
[in]	dwParam	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.

Ejemplos

spb_get_cert.c.

DSPBCalculateObjectId()

int AAP_API DSPBCalculateObjectId	(	char *	szISPB,
		char *	szDomain,
		DWORD	dwKeyType,
		char *	szOutObjName,
		DWORD	dwParam )

#include <dinamo.h>

API auxiliar que calcula (localmente) un nombre de objeto en el formato estándar del módulo SPB.

Parámetros

[in]	szISPB	El ISPB de la institución. Debe tener un tamaño de(ND_SPB_ISPB_LEN +1).
[in]	szDomain	Dominio de mensaje del certificado que se va a activar. Debe tener un tamaño máximo de(ND_SPB_DOMAIN_MAX_LEN + 1). Puede ser NULL si no se ha definido ningún dominio.
[in]	dwKeyType	Tipo de nombre a generar. Se aceptarán los valores de la siguiente tabla. Valor Significado SPB_GENERATE_KEY_NAME Genera un nombre para una clave. SPB_GENERATE_CER_NAME Genera un nombre para un certificado.
[out]	szOutObjName	Buffer de tamaño MAX_OBJ_ID_FQN_LEN que contendrá el nombre del objeto calculado.
[in]	dwParam	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.

DSPBMapInfo()

int AAP_API DSPBMapInfo	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		EXT_MAP_2_OBJ_INFO *	pstExtMap,
		DWORD	dwParam )

#include <dinamo.h>

API auxiliar que recupera información de un SPB MAP.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szIdCert	Identificación del certificado a recuperar. El identificador del certificado puede tener los siguientes formatos: ID, CA@SN o ISPB@DOMINIO. La longitud exacta para CA es ND_SPB_CA_LEN y la longitud máxima para SN es ND_SPB_SN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 03@12345678 donde 03 es el identificador de CA y 12345678 es el número de serie del certificado. El tamaño exacto para ISPB es ND_SPB_ISPB_LEN y el tamaño máximo para DOMAIN es ND_SPB_DOMAIN_MAX_LEN. El tamaño máximo del identificador es ND_SPB_ID_MAX_LEN. Ejemplo: 12345678@MES01 donde 12345678 es el ISPB de la institución y MES01 es el identificador de DOMINIO.
[out]	pstExtMap	Puntero a un EXT_MAP_2_OBJ_INFO que contendrá la información del MAPA solicitado.
[in]	dwParam	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.

Ejemplos

spb_get_cert.c.

DSPBSetISPBMap()

int AAP_API DSPBSetISPBMap	(	HSESSIONCTX	hSession,
		char *	szISPB,
		char *	szKeyId,
		char *	szCertId,
		DWORD	dwParam )

#include <dinamo.h>

API auxiliar que crea o modifica un mapa SPB. El mapa se identifica a partir de los datos CA y NS del certificado proporcionado.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szISPB	ISPB de la institución. Debe tener un tamaño máximo de MAX_OBJ_ID_FQN_LEN.
[in]	szKeyId	Nombre de la clave privada de la institución. Debe tener una longitud máxima de MAX_OBJ_ID_FQN_LEN. Puede ser NULL si sólo se está definiendo el certificado.
[in]	szCertId	Nombre del certificado de la institución. Debe tener una longitud máxima de MAX_OBJ_ID_FQN_LEN.
[in]	dwParam	Se admite la siguiente tabla de banderas. Valor Significado 0 Utiliza el estándar SPB (Sistema Brasileño de Pagos). ND_SPB_USO_CIP1 Utiliza la norma CIP (Cámara Interbancaria de Pagamentos). ND_SPB_USE_ANY Acepta el estándar CIP y SPB. La detección se realiza internamente.

Devolución

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