Gestión

Descripción detallada

Gestión de HSM.

Consulte la documentación técnica del HSM.

Definiciones y macros
#define	DN_NT_MAX_TARGET_LEN (255)
#define	DN_NTOOL_PING (1)
#define	DN_NTOOL_TRACERT (2)
#define	DN_NTOOL_CROSS_CHECK (100)
#define	DN_WRITE_FILE_OPT_CERT_CHAIN (1)
#define	DN_WRITE_FILE_OPT_NO_CONVERSION (2)
#define	DN_ATOKEN_CACHE_GET_COUNT (0)
#define	DN_ATOKEN_CACHE_GC (1)
#define	DN_S_NSAUTH_ASSOC (1)
#define	DN_S_NSAUTH_RESET (2)
#define	DN_S_NSAUTH_AUTH (3)
#define	DN_S_NSAUTH_eAUTH (4)
#define	DN_S_NSAUTH_CHECK (5)

Definiciones de tipo
typedef int(AAP_API *	funcListKeyCallback) (char *szKeyName, void *pParam, BOOL bFinal)
typedef int(AAP_API *	funcLogEventCallback) (char *szEvent, void *pParam, BOOL bFinal)
typedef int(AAP_API *	funcReadLocalFileCallback)(BYTE *pbData, DWORD *pdwDataLen, void *pParam, BOOL *pbFinal)
typedef int(AAP_API *	funcWriteLocalFileCallback)(BYTE *pbData, DWORD dwDataLen, void *pParam, BOOL bFinal)
typedef int(AAP_API *	funcListAKeysCallback) (void *pvToken, void *pParam, BOOL bFinal)

Enumeraciones
enum	RetCodeMsgType { CODE_MSG = 1 , DESC_MSG }

Funciones
int AAP_API	DListObjs(HSESSIONCTX hSession, funcListKeyCallback fncallback, void *pParam)
int AAP_API	DListBlobs(HSESSIONCTX hSession, funcListKeyCallback fncallback, void *pParam)
int AAP_API	DBackupData(HSESSIONCTX hSession, char *szBackupFile, char *szPin, int nDirection)
int AAP_API	DBackupObject(HSESSIONCTX hSession, DWORD dwOP, char *szObjectId, char *szPin, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
int AAP_API	DGetLogEvents(HSESSIONCTX hSession, funcLogEventCallback fncallback, void *pParam)
int AAP_API	DAdmOperation(HSESSIONCTX hSession, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)
int AAP_API	DGetHSMTLSCert (char *szAddress, int nPort, DWORD dwOutFormat, BYTE **ppbOutCert, DWORD *pdwOutCertLen, DWORD dwFlags)
int AAP_API	DHSMTool(HSESSIONCTX hSession, DWORD dwOption, const char *szTarget, void **pvResult, DWORD *pdwResultLen, DWORD dwFlags)
int AAP_API	DWriteFileBuffer(HSESSIONCTX hSession, const char *szFileId, BYTE *pbFile, DWORD dwFileSize, DWORD dwOptions)
int AAP_API	DWriteFile(HSESSIONCTX hSession, char *szFileId, DWORD dwFileSize, funcReadLocalFileCallback fncallback, void *pParam)
int AAP_API	DReadFile(HSESSIONCTX hSession, char *szFileId, funcWriteLocalFileCallback fncallback, void *pParam)
int AAP_API	DReadFileBuffer(HSESSIONCTX hSession, const char *szFileId, BYTE **ppbData, DWORD *pdwDataLen, DWORD dwReserved)
int AAP_API	DRemoveObj(HSESSIONCTX hSession, char *szObjId)
int AAP_API	DGetStatLog(HSESSIONCTX hSession, DWORD dwStart, DWORD dwOffset, DWORD *pdwLogSize, BYTE **ppbLog)
int AAP_API	DTruncateLog(HSESSIONCTX hSession)
int AAP_API	DFindHSM(DWORD dwServiceType, DWORD dwFilter, void **ppvOutputData, DWORD *pdwOutputDataLen, DWORD dwFlags)
int AAP_API	DManageAToken(HSESSIONCTX hSession, BYTE bOP, DN_A_TOKEN_FULL *pstATokenFull, funcListAKeysCallback fnCallBack, void *pvCallbackParam, DWORD dwParam)
int AAP_API	DManageATokenCache(HSESSIONCTX hSession, DWORD dwOP, void *pOutData, DWORD dwParam)
int AAP_API	DDSBindHSM(HSESSIONCTX hSession, const char *szBindKey, DWORD dwReserved)
int AAP_API	DDSUnbindHSM(HSESSIONCTX hSession, DWORD dwReserved)
int AAP_API	DSCGetShadow (const char *szPin, DN_SC_M_OF_N_SHADOW *pstShadow, DWORD dwReserved)
int AAP_API	DNSAuthSetState(HSESSIONCTX hSession, DWORD dwAcl, BYTE bState, DN_SC_M_OF_N_SHADOW *pstShadows, DWORD dwShadowsCount, DWORD dwReserved)
int AAP_API	DGetErrorString (int nErrorValue, char *szErrorCode, char *szErrorDesc)
const char *AAP_API	DGetReturnCodeString (int nErrorValue, RetCodeMsgType eErrorType)

Definiciones y macros

DN_NT_MAX_TARGET_LEN

#define DN_NT_MAX_TARGET_LEN   (255)

#include <dinamo.h>

DN_NTOOL_PING

#define DN_NTOOL_PING   (1)

#include <dinamo.h>

DN_NTOOL_TRACERT

#define DN_NTOOL_TRACERT   (2)

#include <dinamo.h>

DN_NTOOL_CROSS_CHECK

#define DN_NTOOL_CROSS_CHECK   (100)

#include <dinamo.h>

DN_WRITE_FILE_OPT_CERT_CHAIN

#define DN_WRITE_FILE_OPT_CERT_CHAIN   (1)

#include <dinamo.h>

DN_WRITE_FILE_OPT_NO_CONVERSION

#define DN_WRITE_FILE_OPT_NO_CONVERSION   (2)

#include <dinamo.h>

DN_ATOKEN_CACHE_GET_COUNT

#define DN_ATOKEN_CACHE_GET_COUNT   (0)

#include <dinamo.h>

DN_ATOKEN_CACHE_GC

#define DN_ATOKEN_CACHE_GC   (1)

#include <dinamo.h>

DN_S_NSAUTH_ASSOC

#define DN_S_NSAUTH_ASSOC   (1)

#include <dinamo.h>

Establece el estado asociado.

DN_S_NSAUTH_RESET

#define DN_S_NSAUTH_RESET   (2)

#include <dinamo.h>

Restablecer estado NSAuth. No asociado y no autorizado.

DN_S_NSAUTH_AUTH

#define DN_S_NSAUTH_AUTH   (3)

#include <dinamo.h>

Establecer el estado autorizado. Aún no está disponible.

DN_S_NSAUTH_eAUTH

#define DN_S_NSAUTH_eAUTH   (4)

#include <dinamo.h>

Establece el estado de la sesión en autorizada. La ACL debe establecerse primero con DN_S_NSAUTH_ASSOC.

DN_S_NSAUTH_CHECK

#define DN_S_NSAUTH_CHECK   (5)

#include <dinamo.h>

Comprueba el conjunto de shadow share. Esta bandera no cambia el estado NSAuth.

Definiciones de tipo

funcListKeyCallback

typedef int(AAP_API * funcListKeyCallback) (char *szKeyName, void *pParam, BOOL bFinal)

#include <dinamo.h>

Puntero a la función de llamada de retorno para listar objetos.

Parámetros

[in]	szKeyName	Nombre del objeto.
[in]	pParam	Puntero a un parámetro pasado a la función DListObjs().
[in]	bFinal	Indicador del último registro.

Devolución

0

funcLogEventCallback

typedef int(AAP_API * funcLogEventCallback) (char *szEvent, void *pParam, BOOL bFinal)

#include <dinamo.h>

Puntero a una función callback para registrar los eventos generados por el servidor.

Parámetros

[in]	szEvent	Evento de registro.
[in]	pParam	Puntero a un parámetro pasado a la función DgetLogEvents.
[in]	bFinal	Indica el final del envío de eventos.

Devolución

0

funcReadLocalFileCallback

typedef int(AAP_API * funcReadLocalFileCallback) (BYTE *pbData, DWORD *pdwDataLen, void *pParam, BOOL *pbFinal)

#include <dinamo.h>

Puntero a una función de devolución de llamada para leer el archivo que se va a cargar en el HSM.

Parámetros

[in]	pbData	Búfer que contiene los datos leídos.
[in]	pdwDataLen	Puntero a un DWORD que contiene el número de bytes leídos del fichero
[in]	pParam	Puntero a un parámetro pasado a la función DWriteFile().
[in]	pbFinal	Bandera que indica el final del archivo.

Devolución

0

funcWriteLocalFileCallback

typedef int(AAP_API * funcWriteLocalFileCallback) (BYTE *pbData, DWORD dwDataLen, void *pParam, BOOL bFinal)

#include <dinamo.h>

Puntero a una función de devolución de llamada para guardar localmente el archivo recuperado del HSM.

Parámetros

[in]	pbData	Buffer con los datos que se escribirán en el fichero.
[in]	dwDataLen	Número de bytes a grabar.
[in]	pParam	Puntero a un parámetro pasado a la función DWriteFile().
[in]	bFinal	Bandera que indica el final del archivo.

Devolución

0

funcListAKeysCallback

typedef int(AAP_API * funcListAKeysCallback) (void *pvToken, void *pParam, BOOL bFinal)

#include <dinamo.h>

Puntero a la función de callback para listar los tokens de sesión en DManageAToken().

Parámetros

[in]	pvToken	Puntero que recibirá una estructura DN_A_TOKEN_FULL conteniendo los datos del token de sesión.
[in]	pParam	Puntero a un parámetro pasado a la función DManageAToken().
[in]	bFinal	Indicador del último registro.

Devolución

0

Enumeraciones

RetCodeMsgType

enum RetCodeMsgType

#include <dinamo.h>

Enumeración de tipos de mensajes de código de retorno.

Enumeradores
CÓDIGO_MSG	Devuelve el texto del código de retorno.
DESC_MSG	Devuelve la descripción del código de retorno.

Funciones

DListObjs()

int AAP_API DListObjs	(	HSESSIONCTX	hSession,
		funcListKeyCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

DinamoLista los objetos almacenados en , incluyendo claves y archivos.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	fncallback	Puntero a una función de callback utilizada para listar los nombres (identificadores) de los objetos.
[in]	pParam	Puntero a cualquier parámetro que se pasará a la función de devolución de llamada

Devolución

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

Notas

Dinamo Las funciones de la API no deben llamarse desde la función dedevolución de llamada (parámetro fncallback) utilizando el mismo contexto (parámetro hSession) pasado a la función DListObjs(). Cuando sea necesario, utilice un contexto de sesión diferente.

Ejemplos

list_keys.c.

DListBlobs()

int AAP_API DListBlobs	(	HSESSIONCTX	hSession,
		funcListKeyCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

DinamoLista los blobs almacenados en .

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	fncallback	Puntero a una función de callback utilizada para listar los nombres (identificadores) de los blobs.
[in]	pParam	Puntero a cualquier parámetro que se pasará a la función de devolución de llamada

Devolución

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

Notas

Dinamo Las funciones de la API no deben llamarse desde la función dedevolución de llamada (parámetro fncallback) utilizando el mismo contexto (parámetro hSession) pasado a la función DListBlobs(). Cuando sea necesario, utilice un contexto de sesión diferente.

DBackupData()

int AAP_API DBackupData	(	HSESSIONCTX	hSession,
		char *	szBackupFile,
		char *	szPin,
		int	nDirection )

#include <dinamo.h>

DinamoCrea o restaura la copia de seguridad de objetos (claves, certificados, etc.) almacenados internamente en .

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szBackupFile	Ruta del archivo de copia de seguridad.
[in]	szPin	Contraseña para proteger el archivo de copia de seguridad. Deben ser caracteres ASCII. La longitud debe estar comprendida entre MIN_BACKUP_PIN_LEN y MAX_BACKUP_PIN_LEN.
[in]	nDirection	[in] Especifica la acción a realizar. Valor Significado MAKE_BACKUP Se creará el archivo de copia de seguridad, si existe, se sobrescribirá. MAKE_RESTORE_WITHOUT_NET_CONFIG Se restaurarán los datos de copia de seguridad existentes, sin incluir los parámetros de red, en el archivo indicado por szBackupFile. MAKE_RESTORE_WITH_NET_CONFIG Se restaurarán los datos de copia de seguridad existentes, incluidos los parámetros de red, en el archivo indicado por szBackupFile. MAKE_USE_WIN_CREDENTIAL Utiliza las credenciales de Windows para la autenticación. Esta opción debe utilizarse con una de las otras opciones. Introduzca el destino de las credenciales en el campo szPin.

Devolución

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

Notas

Esta función crea o recupera una copia de seguridad de los objetos almacenados en el sistema hacia o desde un archivo cifrado. La clave de cifrado y descifrado se obtiene a partir de la contraseña introducida por el usuario. Dinamo Esta operación de cifrado/descifrado es independiente del modo en que esté almacenado el objeto (cifrado o sin cifrar). La copia de seguridad siempre está cifrada. La contraseña utilizada para generar la copia de seguridad debe utilizarse para restaurarla. Puedes indicar si se deben restaurar o no los parámetros de red (dirección IP, máscara y pasarela). Para restaurar archivos de gran tamaño, superiores a 2147483647 bytes, el servidor HSM debe ser al menos de la versión 3.9.0.2 o superior.

Observación

Dinamo Los objetos marcados como no exportables en también se incluirán en la copia de seguridad. Dinamo Esta operación no es selectiva, es decir, se copiarán todos los objetos del área de almacenamiento.

DBackupObject()

int AAP_API DBackupObject	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		char *	szObjectId,
		char *	szPin,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Crea o restaura la copia de seguridad de un objeto específico en el HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwOP	Especifica la acción a realizar. Valor Significado D_BACKUP_OBJ Realiza una copia de seguridad del objeto especificado en szObjectId y escribe el contenido en pbData. pdwDataLen debe contener el tamaño del búfer apuntado por pbData y al final de la llamada recibirá el total de bytes copiados a pbData. Caso pbData es NULL, pdwDataLen recibirá el tamaño del búfer pbData necesario para alojar la copia de seguridad. Puede utilizar un búfer mayor o igual a D_MAX_BACKUP_OBJ_LEN para evitar una llamada extra a esta función, sólo para recuperar el tamaño del buffer de respaldo requerido. D_RESTORE_OBJ Restaura la copia de seguridad del objeto. szObjectId debe contener el nombre que tendrá el objeto restaurado dentro del HSM. pbData debe contener el búfer de la copia de seguridad que se restaurará y pdwDataLen el tamaño de pbData.
[in]	szObjectId	Nombre del objeto dentro del HSM.
[in]	szPin	Contraseña para proteger el archivo de copia de seguridad. Deben ser caracteres ASCII. La longitud debe estar comprendida entre MIN_BACKUP_PIN_LEN y MAX_BACKUP_PIN_LEN.
[in,out]	pbData	Buffer que contiene la copia de seguridad del objeto. Ver opciones en dwOP para más detalles.
[in,out]	pdwDataLen	Tamaño de la copia de seguridad. Ver opciones en dwOP para más detalles.
[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.

Notas

Esta función crea o recupera una copia de seguridad de un objeto específico (una clave, por ejemplo) hacia o desde un archivo cifrado. La copia de seguridad siempre se cifra con dos capas: en primer lugar, con la clave maestra del servidor (SVMK) del HSM y, en segundo lugar, con la clave de cifrado derivada de la contraseña introducida por el usuario. La contraseña utilizada para generar la copia de seguridad debe utilizarse al restaurar.

Dinamo Dado que el objeto ha sido cifrado por la SVMK, sólo puede restaurarse en HSM inicializados con la misma SVMK. Desde el punto de vista de la seguridad, el objeto contenido en la copia de seguridad sigue estando protegido por el límite criptográfico del HSM.

Dinamo Diferentes líneas de modelos HSM pueden tener diferentes métodos para derivar SVMK de la semilla. Pocket Las copias de seguridad generadas en los modelos XP y ST son interoperables entre sí, pero no con las copias de seguridad de los modelos .

Observación

La copia de seguridad se puede realizar con objetos exportables o no exportables y este estado se conserva en el archivo restaurar. Sólo el objeto especificado en szObjectId se incluirán en la copia de seguridad.

DGetLogEvents()

int AAP_API DGetLogEvents	(	HSESSIONCTX	hSession,
		funcLogEventCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Recupera los eventos de registro generados por el servidor.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	fncallback	Puntero a una función de callback utilizada para registrar eventos generados por el servidor.
[in]	pParam	Puntero a cualquier parámetro que será pasado a la función callback.

Devolución

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

Notas

DinamoEsta opción permite que un programa reciba mensajes de registro generados internamente en ; el programa recibe entonces una copia de todos los mensajes de registro. Existe un límite de 03 (tres) receptores que reciben simultáneamente notificaciones de eventos, para evitar degradar el rendimiento del HSM. Los mensajes enviados siguen registrándose en el archivo interno del servidor. El primer valor hexadecimal mostrado en la línea de registro es una marca de tiempo y el segundo es un ID utilizado internamente.

Ejemplos

get_rt_logs.c.

DAdmOperation()

int AAP_API DAdmOperation	(	HSESSIONCTX	hSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Realiza operaciones administrativas en el servidor.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwParam	Especifica la operación que se realizará y, en consecuencia, la estructura o los datos pasados en el parámetro pbData. Valor Significado AO_SHUTDOWN Tipo de pbData: NULL Apague el HSM. En este punto deberá intervenir manualmente para que el servidor vuelva a estar disponible, es decir, deberá encender el equipo e insertar la tarjeta de explotación. Aún no se admite AO_RESTART Tipo de pbData: NULL Reinicie el HSM. En este punto, tendrá que intervenir manualmente para que el servidor vuelva a estar disponible, es decir, insertar la tarjeta de operación. Aún no se admite. AO_KEEPALIVE Tipo de pbData: NULL Realiza un simple intercambio de mensajes entre el cliente y el servidor para mantener la conexión establecida. TO_SET_DATE_TIME Tipo de pbData: struct tm (time.h) Ajuste la fecha y la hora del HSM. Debe introducirse la hora GMT (Greenwich Mean Time) por defecto (sin zona horaria). AO_SET_PWD_SEC_POLICY Tipo de pbData: PWD_SEC_POLICY Define los parámetros de la política de seguridad del HSM. AO_GET_PWD_SEC_POLICY Tipo de pbData: PWD_SEC_POLICY Recupera los parámetros de la política de seguridad del HSM. TO_SET_TLS_BUNDLE Tipo de pbData: TLS_BUNDLE_INFO Define la clave y el certificado que utilizará el TLS del HSM. TO_EFTD_ACTIVATE Tipo de pbData: NULL Activa el módulo EFTd. Actualmente sólo está disponible el módulo DN_EFTD_DEFAULT_USER para esta operación. TO_EFTD_DEACTIVATE Tipo de pbData: NULL Desactiva el módulo EFTd. En la actualidad, sólo el módulo DN_EFTD_DEFAULT_USER para esta operación. TO_EFTD_RESET_CONF Tipo de pbData: NULL Devuelve la configuración del módulo EFTd a los parámetros de fábrica. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. TO_EFTD_GET_CONF Tipo de pbData: *DN_EFTD_CONF Recupera la configuración del módulo EFTd. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. TO_EFTD_SET_MSG_HEADER_LEN Tipo de pbData: *BYTE Define el tamaño de la cabecera del mensaje del módulo EFTd. Acepta valores entre DN_EFTD_MIN_MSG_HEADER_LEN e DN_EFTD_MAX_MSG_HEADER_LEN. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. TO_EFTD_SET_PIN_LEN Tipo de pbData: *BYTE Define el tamaño del pin del módulo EFTd. Acepta valores entre DN_EFTD_MIN_PIN_LEN e DN_EFTD_MAX_PIN_LEN. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. AO_GET_GLOBAL_OBJ_STATS Tipo de pbData: *DN_GLOBAL_OBJ_STATS Recupera las estadísticas globales de los objetos. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. AO_GET_SEC_POLICY_GFLAGS Tipo de pbData: *ORDEN Recupera los indicadores de seguridad del HSM. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. AO_SET_SEC_POLICY_GFLAGS Tipo de pbData: DWORD Establece los indicadores de seguridad del HSM. Sólo los usuarios con ACL_USR_REMOTE_INFO o ACL_SYS_OPERATOR están autorizados para esta operación. Consulte los valores admitidos en las observaciones.
[in]	pbData	Puntero a los datos o estructuras especificados en dwParam.
[in]	dwDataLen	Tamaño de los datos o de la estructura especificada en dwParam.
[in]	dwFlags	Debe ser 0 o uno de los valores siguientes. Valor Significado TO_KEEPALIVE_FLAG_NOISELESS Tipo de dwParam: AO_KEEPALIVE Hace que la operación keep alive no genere registros en el HSM.

Devolución

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

Notas

DinamoLa opción AO_KEEPALIVE ejecuta una prueba de heartbeat en el servicio. Un resultado positivo a esta prueba indica que el HSM está procesando correctamente las peticiones de los clientes y que su estado interno es coherente y está intacto. Dinamo Puede ser utilizada, por ejemplo, por equipos de monitorización y soporte para indicar el estado OK de .

Las opciones AO_GET_SEC_POLICY_GFLAGS y AO_SET_SEC_POLICY_GFLAGS admiten los siguientes valores:

Valor	Significado
DN_SEPOL_GF_ENABLE_HTTP_X509_SA	Permite la autenticación de clientes HTTP mediante certificados X.509.
DN_SEPOL_GF_ENABLE_NSA_API_AUTH	Habilita la autenticación de M de N particiones a través de la API.

Ejemplos

connect_hsm.c.

DGetHSMTLSCert()

int AAP_API DGetHSMTLSCert	(	char *	szAddress,
		int	nPort,
		DWORD	dwOutFormat,
		BYTE **	ppbOutCert,
		DWORD *	pdwOutCertLen,
		DWORD	dwFlags )

#include <dinamo.h>

Recupera el certificado HSM utilizado en TLS.

Parámetros

[in]	szAddress	Dirección HSM.
[in]	nPort	Puerto de acceso al HSM. El puerto por defecto es DEFAULT_PORT.
[in]	dwOutFormat	Formato de salida del certificado. Valor Significado CERT_OUT_DER Exporta el certificado del servidor en formato X.509 DER. CERT_OUT_DER Exporta el certificado del servidor en formato X.509 PEM.
[in]	ppbOutCert	Puntero con el certificado en el formato especificado en dwOutFormat. Este puntero debe liberarse con DFree.
[in]	pdwOutCertLen	Tamaño del certificado indicado en ppbOutCert.
[in]	dwFlags	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.

DHSMTool()

int AAP_API DHSMTool	(	HSESSIONCTX	hSession,
		DWORD	dwOption,
		const char *	szTarget,
		void **	pvResult,
		DWORD *	pdwResultLen,
		DWORD	dwFlags )

#include <dinamo.h>

Ejecutar herramientas de prueba desde el HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwOption	Opción de funcionamiento. Valor Significado DN_NTOOL_PING Realiza una operación PING desde el HSM. pvResultado contendrá una cadena. DN_NTOOL_TRACERT Realiza una operación TRACERT desde el HSM. pvResultado contendrá una cadena. DN_NTOOL_CROSS_CHECK Realiza una operación de comprobación cruzada desde el HSM. pvResultado contendrá un vector de estructuras CROSS_CHECK_NODE.
[in]	szTarget	Dirección de destino de la operación a ejecutar. Tamaño máximo de DN_NT_MAX_TARGET_LEN.
[out]	pvResult	Puntero que contendrá el resultado de la orden ejecutada. Este puntero debe ser liberado con DFree.
[out]	pdwResultLen	Tamaño del búfer devuelto en pvResultado.
[in]	dwFlags	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.

DWriteFileBuffer()

int AAP_API DWriteFileBuffer	(	HSESSIONCTX	hSession,
		const char *	szFileId,
		BYTE *	pbFile,
		DWORD	dwFileSize,
		DWORD	dwOptions )

#include <dinamo.h>

Importar un archivo en HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szFileId	Identificador del nuevo archivo dentro del HSM.
[in]	pbFile	Memoria intermedia que contiene el archivo que se va a importar.
[in]	dwFileSize	Tamaño del archivo que se va a cargar.
[in]	dwOptions	Valor

Significado

DN_WRITE_FILE_OPT_CERT_CHAIN

El archivo proporcionado es una cadena de certificados. No utilice esta opción con otros tipos de archivo.

DN_WRITE_FILE_OPT_NO_CONVERSION

El archivo se importará sin conversión de formato.

Devolución

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

Notas

El archivo grabado es opaco para el HSM, está protegido por SVMK (Server Master Key) y siempre será un objeto exportable.
El tamaño máximo de archivo aceptado por HSM es de 64 Kb.
Los archivos enviados al HSM, descritos en la tabla siguiente, tendrán sus tipos detectados automáticamente.

Tipo	Formato
Certificados X.509	DER o PEM
CRL (Lista de revocación de certificados) o LCR (Lista de certificados revocados)	DER o PEM
Cadenas de certificados PKCS#7	DER o PEM (la detección de PEM requiere el uso del indicador DN_WRITE_FILE_OPT_CERT_CHAIN)

Ejemplos

pkcs7_sign.c, sign_check_pix_jws.c, sign_verify_dict.c, sign_verify_pix.c y sign_verify_xml.c.

DWriteFile()

int AAP_API DWriteFile	(	HSESSIONCTX	hSession,
		char *	szFileId,
		DWORD	dwFileSize,
		funcReadLocalFileCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Importar un archivo en HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szFileId	Identificador del nuevo archivo dentro del HSM.
[in]	dwFileSize	Tamaño del archivo que se va a cargar.
[in]	fncallback	Puntero a una función de devolución de llamada utilizada para leer el archivo que se va a cargar.
[in]	pParam	Puntero a cualquier parámetro que será pasado a la función callback.

Devolución

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

Notas

El archivo grabado es opaco para el HSM, no se cifrará internamente y siempre será un objeto exportable.
El tamaño máximo de archivo aceptado por HSM es de 512kb.
Los archivos enviados al HSM, descritos en la tabla siguiente, tendrán sus tipos detectados automáticamente.

Tipo	Formato
Certificados X.509	DER
CRL (Lista de revocación de certificados) o LCR (Lista de certificados revocados)	DER
Cadenas de certificados PKCS#7	DER

DReadFile()

int AAP_API DReadFile	(	HSESSIONCTX	hSession,
		char *	szFileId,
		funcWriteLocalFileCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Exportar un archivo HSM.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szFileId	Identificador del archivo dentro del HSM.
[in]	fncallback	Puntero a una función de devolución de llamada utilizada para escribir el archivo recuperado.
[in]	pParam	Puntero a cualquier parámetro que será pasado a la función callback.

Devolución

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

Notas

Esta API no debe utilizarse para exportar claves.

DReadFileBuffer()

int AAP_API DReadFileBuffer	(	HSESSIONCTX	hSession,
		const char *	szFileId,
		BYTE **	ppbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Exporta un archivo HSM a una memoria intermedia.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szFileId	Identificador del archivo dentro del HSM.
[out]	ppbData	Puntero que recibirá los datos del fichero leído. La memoria se asigna internamente. La memoria debe liberarse con DFree().
[out]	pdwDataLen	Recibe el tamaño del búfer asignado en ppbDatos.
[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.

Notas

Esta API no debe utilizarse para exportar claves.

DRemoveObj()

int AAP_API DRemoveObj	(	HSESSIONCTX	hSession,
		char *	szObjId )

#include <dinamo.h>

DinamoElimina un objeto almacenado en , ya sea una clave o un archivo.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szObjId	Identificador del objeto dentro del HSM. Este identificador no debe contener espacios ni caracteres especiales. Los caracteres en mayúsculas y minúsculas distinguen entre mayúsculas y minúsculas.

Devolución

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

Ejemplos

ckd_bchain.c, gen_ecdh. c, gen_xecdh .c, get_key_info_bchain.c, get_pub_key_bchain .c, import_export_bchain.c y sign_verify_bchain.c.

DGetStatLog()

int AAP_API DGetStatLog	(	HSESSIONCTX	hSession,
		DWORD	dwStart,
		DWORD	dwOffset,
		DWORD *	pdwLogSize,
		BYTE **	ppbLog )

#include <dinamo.h>

Recupera el contenido del registro del servidor.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwStart	Posición inicial, en bytes, del registro a recuperar. Para recibir el contenido completo del registro, introduzca GET_LOG_START_FULL.
[in]	dwOffset	Cantidad, en bytes, que se recuperará desde la posición inicial indicada por dwStart. Para recibir todo el contenido del registro, indique GET_LOG_END_FULL .
[out]	pdwLogSize	Puntero a DWORD que contendrá la cantidad, en bytes, del registro recuperado.
[out]	ppbLog	Puntero al puntero que contendrá el registro recuperado del servidor. La asignación de memoria se realiza internamente por la biblioteca. La aplicación que llama es responsable de liberar la memoria asignada. Véase la función DFree().

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

DGetStatLogSize(), DTruncateLog()

Ejemplos

download_log.c.

DTruncateLog()

int AAP_API DTruncateLog

(

HSESSIONCTX

hSession

)

#include <dinamo.h>

Permite borrar el contenido del registro del servidor.

Parámetros

[in]

hSession

Contexto adquirido a través de la función DOpenSession().

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

DGetStatLogSize() , DGetStatLog()

DFindHSM()

int AAP_API DFindHSM	(	DWORD	dwServiceType,
		DWORD	dwFilter,
		void **	ppvOutputData,
		DWORD *	pdwOutputDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Busca, mediante el protocolo SLP vía multicast, los HSM disponibles en la red.

Parámetros

[in]	dwServiceType	Define el tipo de servicio HSM que se buscará. Valor Significado DN_FIND_SRVC_TYPE_IP Lista todos los servicios de tipo IP encontrados. Lista todas las interfaces IP disponibles. El mismo HSM puede aparecer en la lista más de una vez con diferentes IP. El valor de dwFiltro debe ser DN_FIND_FILTER_TYPE_ALL. DN_FIND_SRVC_TYPE_AAP Lista todos los servicios de tipo AAP encontrados. Enumera todos los HSM que tienen el servicio en ejecución. DN_FIND_SRVC_TYPE_ALL Enumera todos los tipos de servicio.
[in]	dwFilter	Define el tipo de filtro que se utilizará en la búsqueda. Valor Significado DN_FIND_FILTER_TYPE_POCKET Pocket Enumera todos los HSM encontrados. DN_FIND_FILTER_TYPE_HSM DINAMO Enumera todos los HSM ST o XP encontrados. DN_FIND_FILTER_TYPE_ALL DINAMO Pocket Enumera todos los HSM ST, XP o encontrados.
[out]	ppvOutputData	Puntero, de tipo SLP_SRVR_INFO, que contendrá la lista de HSMs encontrados. La asignación de memoria se realiza internamente por la biblioteca. La aplicación que llama es responsable de liberar la memoria asignada. Véase la función DFree().
[out]	pdwOutputDataLen	Puntero a DWORD que contendrá el número de estructuras (descritas en dwTipoSalida) devuelto en ppvOutputData.
[in]	dwFlags	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.

Notas

La búsqueda se realiza mediante SLP (Service Location Protocol) vía multicast. Todos los HSM accesibles y que ejecuten el servicio aparecerán en esta lista.

DManageAToken()

int AAP_API DManageAToken	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		DN_A_TOKEN_FULL *	pstATokenFull,
		funcListAKeysCallback	fnCallBack,
		void *	pvCallbackParam,
		DWORD	dwParam )

#include <dinamo.h>

Gestiona lostokens de acceso del propio usuario.

Observación

Al diseñar la aplicación, tenga en cuenta el hecho de que los Access Tokens son volátiles, como se detalla a continuación.

Para la autenticación mediante testigos de sesión, véase la función DOpenSession() con la opción SS_ATOKEN.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	bOP	Especifica la operación a realizar. Valor Significado DN_A_TOKEN_OP_ISSUE Emitir un testigo de sesión. Rellene el parámetro qwExpiración entrada en pstATokenFullque a la vuelta de la API recibirá el token emitido. Pase NULL en fnCallBack e pvCallbackParam. DN_A_TOKEN_OP_REVOKE Revocar un testigo de sesión si existe. Rellene el campo Clave entrada en pstATokenFull. Pasar NULL en fnCallBack e pvCallbackParam. DN_A_TOKEN_OP_L_ISSUE Emite un testigo de sesión. Sólo para el HSM conectado, no replica el testigo de sesión. Rellena el qwExpiración entrada en pstATokenFullque a la vuelta de la API recibirá el token emitido. Pase NULL en fnCallBack e pvCallbackParam. DN_A_TOKEN_OP_L_REVOKE Revoca un testigo de sesión si existe. Sólo para el HSM conectado, no replica el testigo de sesión. Rellene el campo Clave entrada en pstATokenFull. Pasar NULL en fnCallBack e pvCallbackParam. DN_A_TOKEN_OP_LIST Lista todos los tokens activos para este usuario. La función de devolución de llamada debe pasarse en fnCallBack. Pasar NULL en pstATokenFull;
[in,out]	pstATokenFull	Puntero a una estructura de tipo DN_A_TOKEN_FULL. Ver opción bOP para obtener instrucciones sobre cómo rellenar la estructura.
[in]	fnCallBack	Puntero a función callback de tipo funcListAKeysCallback. Puede ser NULL. Véase el bOP para obtener instrucciones sobre cómo rellenar la estructura.
[in]	pvCallbackParam	Puntero a cualquier parámetro que se pasará a la función de devolución de llamada. Puede ser NULL.
[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.

Notas

Los Access Tokens se guardan en memoria volátil, por lo que se borran al reiniciar el HSM. A pesar de ser volátiles, los Access Tokens se replican entre los HSM.

La limpieza de las credenciales de acceso caducadas se realiza en dos fases:

• cuando un usuario que tiene Access Tokens caducados hace un intento de inicio de sesión utilizando Access Tokens. Borra sólo las propias credenciales de acceso.
• mediante la función DManageATokenCache(). Borra todos los tokens de acceso caducados del HSM.

El límite máximo de Access Tokens emitidos por HSM puede verse en la siguiente tabla.

Modelo	Límite máximo
Pocket	1024
XP	1 millón
ST	1 millón

Esta operación está disponible a partir de la versión 3.17 del firmware del HSM. La implementación de Access Tokens anterior a la versión de firmware 3.17 es heredada.

Las aplicaciones que utilicen esta funcionalidad deben actualizar el cliente HSM a la versión 3.2.18 o superior, junto con el firmware HSM a la versión 3.17 o superior.

No hay compatibilidad entre las versiones nuevas y antiguas del cliente HSM y el firmware.

DManageATokenCache()

int AAP_API DManageATokenCache	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		void *	pOutData,
		DWORD	dwParam )

#include <dinamo.h>

Gestiona la caché de tokens de sesión(Access Tokens) para todo el HSM. Esta funcionalidad es adecuada para el control granular de la autenticación de aplicaciones, donde la emisión de tokens es gestionada por el responsable de seguridad.

Para la autenticación mediante testigos de sesión, véase la función DOpenSession( ) con la opción SS_ATOKEN. Los tokens de acceso se emiten mediante la función DManageAToken().

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwOP	Especifica la operación a realizar. Valor Significado DN_ATOKEN_CACHE_GET_COUNT Recupera el número de testigos de sesión de todos los HSM. Introduce pOutData a DWORD que recibirá el número total de tokens de sesión HSM. DN_ATOKEN_CACHE_GC Ejecuta el recolector de basura para tokens de sesión HSM. Esta opción limpia todos los tokens de acceso HSM que ya no son válidos. Pase NULL en pOutData.
[out]	pOutData	Datos de salida. Ver opciones de uso en dwOP.
[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.

Notas

Esta operación está disponible a partir de la versión 3.17 del firmware del HSM y a partir de la versión 3.2.18 del cliente del HSM.
La opción DN_ATOKEN_CACHE_GC debe ser llamada periódicamente por la aplicación para mantener bajo control los niveles de caché de Access Token. El calendario de ejecución de la GC debe programarse teniendo en cuenta las horas de mayor carga de trabajo del HSM.

DDSBindHSM()

int AAP_API DDSBindHSM	(	HSESSIONCTX	hSession,
		const char *	szBindKey,
		DWORD	dwReserved )

#include <dinamo.h>

Dinamo Vincular un HSM a una cuenta de Servicios.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szBindKey	Clave de enlace. Dinamo Generada en la web de Servicios.
[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.

DDSUnbindHSM()

int AAP_API DDSUnbindHSM	(	HSESSIONCTX	hSession,
		DWORD	dwReserved )

#include <dinamo.h>

Dinamo Desvincula un HSM de una cuenta de Servicios.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[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.

DSCGetSombra()

int AAP_API DSCGetShadow	(	const char *	szPin,
		DN_SC_M_OF_N_SHADOW *	pstShadow,
		DWORD	dwReserved )

#include <dinamo.h>

DinamoLee la sombra de una tarjeta inteligente M de N .

Parámetros

[in]	szPin	PIN de la tarjeta. Debe ser una cadena numérica ASCII con una longitud máxima de DN_SC_MAX_PIN_LEN.
[out]	pstShadow	Datos de lectura en la sombra.
[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.

DNSAuthSetState()

int AAP_API DNSAuthSetState	(	HSESSIONCTX	hSession,
		DWORD	dwAcl,
		BYTE	bState,
		DN_SC_M_OF_N_SHADOW *	pstShadows,
		DWORD	dwShadowsCount,
		DWORD	dwReserved )

#include <dinamo.h>

Establece el estado de autorización de la partición M de N.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwAcl	ACL de usuario. Valor Significado NSAUTH_ACL_NOP Sin permiso. NSAUTH_ACL_OBJ_OPEN Permiso para abrir/utilizar objetos. Establecido por defecto. NSAUTH_ACL_OBJ_EXPORT Permiso para exportar objetos. NSAUTH_ACL_OBJ_DEL Permiso para eliminar objetos. NSAUTH_ACL_OBJ_BLOCK Permiso para bloquear objetos. NSAUTH_ACL_NS_DEL Permiso para eliminar el espacio de nombres. El usuario debe estar en el estado asociado para poder ser eliminado.
[in]	bState	Estado por definir. Valor Significado DN_S_NSAUTH_ASSOC Defina el estado asociado. Introduzca la ACL del usuario. DN_S_NSAUTH_RESET Restablecer estado NSAuth. No asociado y no autorizado. Pasar NSAUTH_ACL_NOP en dwAcl. DN_S_NSAUTH_AUTH Establece el estado autorizado. Aún no disponible. DN_S_NSAUTH_eAUTH Establece el estado de la sesión en autorizada. La ACL debe tener el valor DN_S_NSAUTH_ASSOC primero. Pase NSAUTH_ACL_NOP en dwAcl. DN_S_NSAUTH_CHECK Comprueba el conjunto de sombras. Esta bandera no cambia el estado NSAuth. Pasar NSAUTH_ACL_NOP en dwAcl.
[in]	pstShadows	Datos de las sombras de las tarjetas inteligentes de la partición M de N.
[in]	dwShadowsCount	Número de sombras en pstShadows.
[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.

DGetErrorString()

int AAP_API DGetErrorString	(	int	nErrorValue,
		char *	szErrorCode,
		char *	szErrorDesc )

#include <dinamo.h>

Obsoleto

Esta API está descontinuada, utilice DGetReturnCodeString().

DGetReturnCodeString()

const char *AAP_API DGetReturnCodeString	(	int	nErrorValue,
		RetCodeMsgType	eErrorType )

#include <dinamo.h>

DINAMORecupera la descripción de un código de retorno de las API .

Parámetros

[in]	nErrorValue	Código de devolución.
[in]	eErrorType	Devuelve el tipo de cadena. Valor Significado CÓDIGO_MSG Devuelve el texto del código de retorno. DESC_MSG Devuelve la descripción del código de retorno.

Devolución

Devuelve la cadena definida en eErrorType.