 |
API C/C
HSM Dinamo
|
|
API C/C
HSM Dinamo
|
Operaciones de codificación y descodificación según la norma SPB.
Las APIs del módulo SPB están destinadas a la codificación y decodificación de mensajes en el estándar SPB (Sistema Brasileño de Pagos), de acuerdo con el Manual de Seguridad de la RSFN (Rede Nacional do Sistema Financeiro) publicado por el BACEN (Banco Central do Brasil).
El Sistema Brasileño de Pagos (SPB) funciona con un sistema de intercambio de mensajes entre instituciones financieras en una red privada denominada RSFN. Las normas son definidas y publicadas por el Banco Central. Todos los mensajes intercambiados son encriptados y firmados digitalmente utilizando un esquema de sobre digital. El módulo SPB se encarga de gestionar la seguridad de los mensajes.
El módulo SPB realiza básicamente tres funciones: Codificación y Decodificación en mensajes SPB, y gestión de certificados SPB.
La codificación se realiza sobre los mensajes que van a la cola de salida y consiste en:
La descodificación realiza el proceso inverso, actuando sobre los mensajes que llegan a la cola de entrada;
Toda operación con claves públicas y privadas está ligada al uso de certificados X.509, por lo que además de Codificar y Decodificar el módulo SPB también necesita disponer de alguna gestión de certificados.
Cada institución se identifica en el SPB por su código ISPB (8 dígitos) y puede intercambiar mensajes en los llamados dominios de mensajes, cada uno de los cuales requiere un certificado diferente. Cada institución sólo puede tener un certificado activo a la vez en un dominio.
En el módulo SPB, las instituciones (y sus certificados equivalentes) sólo pueden identificarse mediante el código ISPB.
El módulo SPB se encarga de encriptar los mensajes de acuerdo con las definiciones del BACEN, y la estructura de comunicación SPB puede ser utilizada por otros sistemas entre instituciones financieras motivados, por ejemplo, por la aparición de nuevas aplicaciones dentro del BACEN:
En HSM, la gestión de certificados se realiza mediante Mapas, que son objetos de señalización y referencia. Todas las referencias en el módulo SPB son a Mapas, no a claves y certificados.
En cuanto a la nomenclatura interna que se describe a continuación, la idea es que las claves, certificados y mapas sean gestionados por las funciones SPB especializadas de la biblioteca cliente HSM, de forma que estas reglas de nomenclatura sean totalmente transparentes para la aplicación, que sólo tiene que buscar el código SPB.
Si las funciones de codificación y descodificación sólo tuvieran que gestionar mensajes con certificados activos, bastaría con mantener estos certificados en la base, pero hay casos, como un proceso de auditoría, en los que la aplicación necesita abrir o verificar la firma de un mensaje antiguo que se generó con un certificado que ya ha sido desactivado (o que seguirá activado en el futuro). Por eso, el HSM necesita guardar y acumular todos los certificados de la base, tanto propios como de terceros, a medida que se importan, activan y desactivan.
El manual BACEN especifica que los mensajes XML deben representarse en formato Unicode UTF-16 BE. Para mod_SPB no importa, ya que el contenido que se firmará y cifrará en Encode será exactamente el enviado por el usuario, el HSM no convierte automáticamente el texto ni en Encode ni en Decode.
El manual del BACEN menciona mensajes y punteros de archivos que pueden incluirse en el contenido de un mensaje SPB. La diferencia es que los mensajes XML deben representarse en formato UTF16-BE, mientras que los archivos no tienen este requisito.
Esta distinción entre mensaje y archivo es importante para la persona que llama, ya que decidirá si necesita convertir el formato o no antes de enviarlo al HSM.
En el caso de los mensajes que indican contenido comprimido, la premisa de la aplicación es que el remitente dispone de la infraestructura de compresión necesaria, por lo que el HSM firma y cifra lo que la aplicación pasa en Encode, mientras que en el caso del destinatario la premisa es que puede no disponer de la infraestructura de descompresión, por lo que el HSM descomprime el contenido en Decode y entrega el contenido descomprimido, lo que incluye la detección automática de si el estándar utilizado es gzip o pkzip.
Todos los mensajes enviados están firmados, y algunos pueden ser de uso público, sin destinatario especificado.
| C04 | Mensaje | Archivo | Firmado | Cifrado | Con cremallera | Destinatario | Codificar | Descodifique |
|---|---|---|---|---|---|---|---|---|
| 0 | x | x | x | |||||
| 1 | x | x | x | use cert not yet activated | use cert not yet activated | |||
| 2 | x | x | público | acepta el destino en blanco | acepta el destino en blanco | |||
| 3 | x | x | ||||||
| 4 | x | x | ||||||
| 6 | x | x | público | acepta el destino en blanco | acepta el destino en blanco | |||
| 8 | x | x | x | x | ya debería recibirlo comprimido | se descomprime automáticamente | ||
| 10 | x | x | x | público | ya debería recibirlo comprimido | se descomprime automáticamente |
Según la definición de Bacen, los intercambios y activaciones de certificados SPB se realizan dentro del sistema mediante mensajes específicos.
El HSM puede detectar este tipo de mensaje en Decode y promover el intercambio del certificado en la base del HSM automáticamente, sin que la aplicación tenga que llamar explícitamente a la API de activación de certificados.
Se trata de una opción de parametrización de la llamada Decode.
El HSM gestionará la descodificación GEN0007 (aviso de actualización de certificado a través de la difusión BACEN), la respuesta a un GEN0008 (una consulta de certificado digital, cuya respuesta es un GEN0008R1), la respuesta a un GEN0006, así como el GEN0018 (certificado BACEN). Para HSM, GEN0007 y la respuesta a GEN0008 son equivalentes. En el caso de GEN0018, el certificado del mensaje se importa, pero no se activa automáticamente, porque el manual especifica que BACEN envía los mensajes al menos 03 días antes de la activación; por lo que la aplicación es responsable de controlar el tiempo entre la recepción y la activación; y para activarlo basta con informar a CA y NS, porque el certificado ya estará importado en la base de HSM.
El mensaje GEN0006 es utilizado por las instituciones para informar al BACEN de la activación o actualización del estado de un certificado. En el HSM, la respuesta a este mensaje (GEN0006R1) tiene un tratamiento especial para promover la activación del certificado (a partir de la versión de firmware 5.0.16).
El flujo normal de operaciones para activar un nuevo certificado implica un mensaje GEN0006 de la institución al BACEN, que a su vez envía un mensaje de difusión GEN0007 informando a todos los participantes de que el certificado de la institución debe cambiarse. Como la propia institución también recibe este GEN0007, es en este punto (durante la descodificación) cuando la aplicación puede ordenar al HSM que active automáticamente el nuevo certificado en su base local.
Internamente, HSM sólo opera, importa y exporta certificados en formato DER (binario), pero en la biblioteca las operaciones de importación de certificados admiten tanto el formato DER como el PEM (base64), con detección automática.
El módulo SPB del HSM permite realizar operaciones de codificación y descodificación de mensajes SPB utilizando claves y certificados dentro del HSM.
Esto significa que toda la base de certificados y claves privadas de la propia entidad y de las entidades con las que el banco se comunica estará almacenada y centralizada en el HSM, sin necesidad de control externo.
La identificación de las claves y certificados a utilizar se realiza utilizando el código BIPP de las instituciones de forma natural para las aplicaciones convocantes, en lugar del modelo común de utilizar los identificadores nativos de las claves y certificados.
Para establecer esta relación entre los BIPP y las claves y certificados, se utilizó un objeto del HSM denominado map, que simplemente vincula un BIPP a una clave privada y/o un certificado. Esto permite pasar sólo el BISP a una llamada de codificación SPB en lugar de un nombre de clave.
Para facilitar su uso, se define una ley de formación para los nombres de estos objetos.
Para los nombres clave:
k_<ISPB>_<dom>_<yyyymmddhhmmss>
k: 01 carácter, literal<ISPB>: 08 caracteres, código ISPB<dom>hasta 05 caracteres, dominio<yyyyymmddhhmmss>14 caracteres, fecha y hora GMT en que se generó la clave.
Total: hasta 31 caracteres, por ejemplo k_12345678_str01_20131029110223
Para nombres de certificados:
c_<ISPB>_<dom>_<yyyymmddhhmmss>
c: 01 carácter, literal<ISPB>: 08 caracteres, código ISPB<dom>hasta 05 caracteres, dominio<yyyymmddhhmmss>14 caracteres, fecha y hora GMT en que se importó el certificado.
Total: hasta 31 caracteres, por ejemplo c_12345678_spb_20131101120334
La misma ley de formación se aplica a los certificados de terceros.
El mapa es simplemente un objeto interno de HSM que almacena los Id de otros dos objetos. En el caso del módulo SPB, contiene el Id del certificado y el Id de la clave privada. Cada Id ocupa una posición dentro del mapa denominada ranura.
Dado que cada mensaje implica el procesamiento de certificados, el módulo SPB necesita una forma de identificar de forma única cada certificado para cada institución en cada dominio. Según el estándar Bacen, cada certificado tiene un número de serie (SN) de hasta 32 bytes, definido por la autoridad de certificación (CA) que lo emite, pero no hay garantía de que los números de serie sean globalmente únicos, por lo que la identificación del certificado debe incluir información de la CA (cada CA en el SPB tiene un byte de identificación) y el SN, que supera el límite de 32 caracteres para los identificadores HSM; el RFC 3280 también hace esta distinción para identificar de forma única un certificado. Los Ids de los mapas de certificados utilizados en el módulo SPB utilizan un esquema de compresión de nombres.
La solución adoptada es un hash MD5, que tiene exactamente 16 bytes (32 caracteres) y no produce colisión para este caso de uso. La definición de lo que entrará en la composición del hash es (CA+NS), donde CA y SN están compuestos por caracteres hexadecimales en mayúsculas.
ISPB@dom. O @ se adopta para mejorar la nomenclatura en el cliente, internamente en el firmware @ se traduce en _.El uso de @dom por parte de la aplicación llamante es opcional; la organización puede no utilizar dominios de aplicación.
Desde el punto de vista de la aplicación que llama, puede referirse a los mapas como ISPB@dom o CA@NSpara utilizar la misma API de codificación/decodificación. La biblioteca HSM lo detecta automáticamente.
Los mapas permiten que las ranuras apunten a un FQN, lo que significa que el certificado y la clave pueden estar en particiones diferentes. En cualquier caso, el mapa debe existir siempre en la partición del usuario logueado, aunque los ids apuntados en las ranuras estén en otra partición. En principio, la mejor forma de utilizarlo es mantener todos los certificados y claves de un BIP en la misma partición, sin referencias a particiones remotas.
Para facilitar la identificación de objetos y la búsqueda de BISP, los certificados activos y los pares certificado+clave privada disponen de un MAPA con el identificador BISP.
Todos los certificados y pares certificado+clave privada, independientemente de si están activos o no, tienen un MAPA con MD5 id (CA+SN) para su identificación e historial, donde CA es el identificador de la Autoridad de Certificación y SN es el número de serie del certificado.
El nombre del objeto mapa es el identificador de la institución, que puede ser de 2 tipos:
03@00000000000000000000000087654321 12345678@MES01 La documentación de la API indica si se aceptan ambos tipos de identificador o sólo uno de ellos.
Si desea utilizar objetos en las particiones de otros usuarios, debe especificar el id de la partición en el identificador.
La indicación se realiza añadiendo el nombre de la partición donde se encuentran los objetos al principio del identificador, separado por /.
Por ejemplo: usuario/12345678@MES01
La secuencia de APIs DSPBEncodeInit(), DSPBEncodeCont( ) y DSPBEncodeEnd() realiza una operación de codificación de mensajes SPB.
La estructura de llamada con secuencia init/cont/end permite a la aplicación llamante utilizar la API con cualquier tamaño de mensaje, incluidos archivos de gran tamaño.
El uso de parámetros con identificadores SPB de origen y destino en las API tiene como objetivo aumentar el nivel de comprobación entre lo que la aplicación realmente tiene (el mensaje SPB) y lo que cree que tiene (los parámetros de la API).
La operación de cifrado no modifica el formato de representación del mensaje, por lo que la aplicación debe enviar el mensaje tal y como lo defina el Banco Central (por ejemplo, UTF-16BE). El mensaje se cifrará y firmará a medida que se reciba.
La secuencia de APIs DSPBDecodeInit(), DSPBDecodeCont( ) y DSPBDecodeEnd() realiza una operación de descodificación de mensajes SPB.
La estructura de llamada con secuencia init/cont/end permite a la aplicación llamante utilizar la API con cualquier tamaño de mensaje.
El uso de parámetros ISPB de origen y destino en las API pretende aumentar el nivel de comprobación entre lo que la aplicación tiene realmente (el mensaje SPB) y lo que cree que tiene (los parámetros API).
Durante la descodificación, el firmware del HSM es capaz de detectar que el mensaje es sobre un cambio de certificado y realizar ya esta actualización y activación de forma automática (sin necesidad de más acciones por parte de la aplicación), por lo que el flag bAutoUpdateCert debe estar activado.
La operación de descifrado no cambia el formato de representación del mensaje. El mensaje se pasará a la aplicación tal y como fue descifrado.
Para facilitar la gestión y abstraer los detalles más complejos del módulo SPB, el fabricante del HSM proporciona una consola gráfica. A través de ella se pueden realizar fácilmente todas las operaciones relativas a la carga y activación de certificados, generación de claves y solicitudes de certificados, creación y visualización de dominios, autorización de particiones y muchas otras.
Consulte con su proveedor la disponibilidad de la consola de gestión HSM SPB.
Más detalles en la documentación del equipo.
Operaciones de codificación y descodificación según la norma SPB. Más...
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) |
| int AAP_API DSPBEncodeInit | ( | HSESSIONCTX | hSesión, |
| char * | szSrcISPB, | ||
| char * | szDstISPB, | ||
| DWORD | dwTotalDataLen, | ||
| BYTE | bCódigoError, | ||
| BYTE | bTratamientoEspecial, | ||
| HSPBCTX * | hSPBCtx, | ||
| DWORD | dwFlags ) |
#include <dinamo.h>
Inicia una operación de codificación de mensajes SPB.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). | ||||||||||||||
| [en] | 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. | ||||||||||||||
| [en] | 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. | ||||||||||||||
| [en] | dwTotalDataLen | Tamaño total en bytes del mensaje a codificar. | ||||||||||||||
| [en] | bErrorCode | Código de error del mensaje que se colocará en la cabecera de seguridad, normalmente en los mensajes de respuesta. | ||||||||||||||
| [en] | bTratamientoEspecial | Código especial de tratamiento de mensajes, según el manual del Banco Central. | ||||||||||||||
| [fuera] | hSPBCtx | Puntero al contexto de la operación de codificación SPB. Tras su uso, debe liberarse con la función DSPBEncodeEnd(). | ||||||||||||||
| [en] | dwFlags | Define los detalles de codificación y puede adoptar los siguientes valores descritos en la tabla siguiente.
|
| 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.
| [en] | hSPBCtx | Contexto adquirido a través de la función DSPBEncodeInit(). |
| [en] | 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. |
| [en] | dwDataInLen | Tamaño del búfer en bytes pbDataIn. |
| [fuera] | 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. |
#include <dinamo.h>
Finaliza una operación de cifrado SPB y recibe la cabecera de seguridad.
| [en] | hSPBCtx | Puntero al contexto adquirido a través de la función DSPBEncodeInit(). |
| [fuera] | 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. |
| int AAP_API DSPBDecodeInit | ( | HSESSIONCTX | hSesión, |
| 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.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). | ||||||||||||||
| [en] | 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. | ||||||||||||||
| [en] | 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. | ||||||||||||||
| [en] | pbHeader | Buffer que contiene la cabecera de seguridad del mensaje SPB a descodificar. | ||||||||||||||
| [en] | dwHeaderLen | Tamaño en bytes del búfer pbHeader. | ||||||||||||||
| [en] | bAcceptExpiredCert | Byte para aceptar certificados caducados al descodificar el mensaje. Pase 1 para aceptar y 0 para no aceptar. | ||||||||||||||
| [en] | 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. | ||||||||||||||
| [en] | dwMessageDataLen | Tamaño total del mensaje SPB a descodificar. | ||||||||||||||
| [fuera] | hSPBCtx | Puntero al contexto de la operación de descodificación SPB. Tras su uso, debe liberarse con la función DSPBDecodeEnd(). | ||||||||||||||
| [en] | dwFlags | Define los detalles de descodificación y puede adoptar los siguientes valores descritos en la tabla siguiente.
|
| 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.
| [en] | hSPBCtx | Contexto adquirido a través de la función DSPBDecodeInit. |
| [en] | 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. |
| [en] | dwDataInLen | Tamaño del búfer en bytes pbDataIn. |
| [fuera] | 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(). |
| [fuera] | pdwDataOutLen | Puntero al tamaño del buffer asignado internamente en ppbDataOut. |
#include <dinamo.h>
Finaliza una operación de descodificación SPB y recibe la cabecera de seguridad.
| [en] | hSPBCtx | Puntero al contexto adquirido mediante la función DSPBDecodeInit(). |
| int AAP_API DSPBGenerateKey | ( | HSESSIONCTX | hSesión, |
| 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.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). |
| [en] | 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. |
| [fuera] | 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. |
| [en] | dwKeyParam | Parámetros adicionales de la clave. Consulte las opciones de la función DGenerateKey(). |
| [en] | dwParam | Reservado para uso futuro (debe ser 0). |
| int AAP_API DSPBGenerateCSR | ( | HSESSIONCTX | hSesión, |
| char * | szPrivateKeyName, | ||
| BYTE | bVersión, | ||
| 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.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). | ||||||||||||||
| [en] | szPrivateKeyName | Identificador de la clave privada. Normalmente la cadena generada en DSPBGenerateKey(). | ||||||||||||||
| [en] | bVersión | CSR versión PKCS#10. Se admite la siguiente tabla.
| ||||||||||||||
| [en] | szSPBSujeto | DN (Dinstinguished Name), para generar el CSR, con un tamaño máximo de CORE_P10_CSR_DN_MAX_LEN. Los campos DN deben estar separados por '/'. | ||||||||||||||
| [en] | dwOutType | Tipo de salida CSR. Se admite la siguiente tabla.
| ||||||||||||||
| [fuera] | pdwCSRLen | Puntero al tamaño del búfer asignado en ppbCSR. | ||||||||||||||
| [fuera] | 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(). | ||||||||||||||
| [en] | dwParam | Parámetros adicionales. Se admite la siguiente tabla.
|
| int AAP_API DSPBImportCertificate | ( | HSESSIONCTX | hSesión, |
| BYTE | bActivar, | ||
| const char * | szUsuario, | ||
| BYTE * | pbCertificado, | ||
| DWORD | dwCertificateLen, | ||
| const char * | szDominio, | ||
| 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.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). | ||||||||
| [en] | bActivar | Activa automáticamente el certificado al importarlo. Introduzca 1 para activar y 0 para importar sin activar el certificado. | ||||||||
| [en] | szUsuario | 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. | ||||||||
| [en] | pbCertificado | Buffer que contiene el certificado a importar. El certificado puede estar en formato PEM o DER. | ||||||||
| [en] | dwCertificateLen | Tamaño del búfer al que apunta pbCertificado. | ||||||||
| [en] | szDominio | 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. | ||||||||
| [en] | dwParam | Se admite la siguiente tabla de banderas.
|
| int AAP_API DSPBImportPKCS12 | ( | HSESSIONCTX | hSesión, |
| BYTE | bActivar, | ||
| const char * | szUsuario, | ||
| const char * | szPkcs12Archivo, | ||
| const char * | szPkcs12Pwd, | ||
| const char * | szDominio, | ||
| DWORD | dwKeyAttr ) |
#include <dinamo.h>
Importe un par de claves y un certificado desde un archivo PKCS#12.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). |
| [en] | bActivar | Activa automáticamente el certificado al importarlo. Introduzca 1 para activar y 0 para importar sin activar el certificado. |
| [en] | szUsuario | Nombre del usuario donde se creará la clave. Puede ser NULL si la clave se crea en el usuario autenticado. |
| [en] | szPkcs12Archivo | Nombre de archivo PKCS#12 para la importación. |
| [en] | szPkcs12Pwd | Contraseña del archivo PKCS#12 para la importación. |
| [en] | szDominio | 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. |
| [en] | dwKeyAttr | Parámetros adicionales de la clave. Consulte las opciones de la función DGenerateKey(). |
| int AAP_API DSPBExportPKCS12 | ( | const HSESSIONCTX | hSesión, |
| const char * | szPkcs12Pwd, | ||
| const char * | szISPB, | ||
| const char * | szReservado, | ||
| BYTE ** | ppbPkcs12, | ||
| DWORD * | pdwPkcs12Len, | ||
| DWORD | dwReservado ) |
#include <dinamo.h>
Exporta un par de claves y un certificado en formato PKCS#12 desde un HSM.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). |
| [en] | szPkcs12Pwd | Contraseña para el archivo PKCS#12. Pase NULL para generar PKCS#12 sin contraseña. |
| [en] | szISPB | Identificador del certificado/clave privada en formato CA@SN, ISPB o ISPB@DOM. |
| [en] | szReservado | Reservado para uso futuro (debe ser NULL). |
| [fuera] | ppbPkcs12 | Puntero a un puntero que contendrá el PKCS#12 generado. Esta área de datos se asignará internamente y debe liberarse utilizando DFree(). |
| [fuera] | pdwPkcs12Len | Puntero al tamaño de los datos escritos en ppbPkcs12. |
| [en] | dwReservado | Reservado para uso futuro (debe ser 0). |
| int AAP_API DSPBActivateCertificate | ( | HSESSIONCTX | hSesión, |
| const char * | szIdCert, | ||
| const char * | szDominio, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Activa un certificado SPB en el HSM.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). |
| [en] | 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. |
| [en] | szDominio | 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. |
| [en] | dwParam | Reservado para uso futuro. |
| int AAP_API DSPBGetCertificate | ( | HSESSIONCTX | hSesión, |
| const char * | szIdCert, | ||
| BYTE ** | ppbCertificado, | ||
| DWORD * | pdwCertificateLen, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Activa un certificado SPB en el HSM.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). |
| [en] | 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 el BISP es ND_SPB_ISPB_LEN y el tamaño máximo para el 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. |
| [fuera] | ppbCertificado | 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(). |
| [fuera] | pdwCertificateLen | Puntero al tamaño del búfer apuntado por ppbCertificate. |
| [en] | dwParam | Reservado para uso futuro (debe ser 0). |
| int AAP_API DSPBCalculateObjectId | ( | char * | szISPB, |
| char * | szDominio, | ||
| 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.
| [en] | szISPB | El ISPB de la institución. Debe tener un tamaño de(ND_SPB_ISPB_LEN +1). | ||||||
| [en] | szDominio | 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. | ||||||
| [en] | dwKeyType | Tipo de nombre a generar. Se aceptarán los valores de la siguiente tabla.
| ||||||
| [fuera] | szOutObjName | Buffer de tamaño MAX_OBJ_ID_FQN_LEN que contendrá el nombre del objeto calculado. | ||||||
| [en] | dwParam | Reservado para uso futuro (debe ser 0). |
| int AAP_API DSPBMapInfo | ( | HSESSIONCTX | hSesión, |
| const char * | szIdCert, | ||
| EXT_MAP_2_OBJ_INFO * | pstExtMap, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
API auxiliar que recupera información de un SPB MAP.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). |
| [en] | 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. |
| [fuera] | pstExtMap | Puntero a un EXT_MAP_2_OBJ_INFO que contendrá la información del MAPA solicitado. |
| [en] | dwParam | Reservado para uso futuro (debe ser 0). |
| int AAP_API DSPBSetISPBMap | ( | HSESSIONCTX | hSesión, |
| 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.
| [en] | hSesión | Contexto adquirido a través de la función DOpenSession(). | ||||||||
| [en] | szISPB | ISPB de la institución. Debe tener un tamaño máximo de MAX_OBJ_ID_FQN_LEN. | ||||||||
| [en] | 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. | ||||||||
| [en] | szCertId | Nombre del certificado de la institución. Debe tener una longitud máxima de MAX_OBJ_ID_FQN_LEN. | ||||||||
| [en] | dwParam | Se admite la siguiente tabla de banderas.
|