Gestión

Descripción detallada

Gestión de HSM.

Gestión de HSM. Más...

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_SC_SHADOW_LEN (24)
#define	DN_SC_MAX_PIN_LEN (8)
#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_M_OF_N_PART *pstPart, DWORD dwReserved)
int AAP_API	DNSAuthSetState(HSESSIONCTX hSession, DWORD dwAcl, BYTE bState, DN_M_OF_N_PART *pstParts, DWORD dwPartsCount, 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_SC_SHADOW_LEN

#define DN_SC_SHADOW_LEN (24)

#include <dinamo.h>

DinamoTamaño sombra de una tarjeta inteligente M de N .

DN_SC_MAX_PIN_LEN

#define DN_SC_MAX_PIN_LEN (8)

#include <dinamo.h>

DinamoTamaño máximo del PIN para una tarjeta inteligente M de N .

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 *szNombreClave, void *pParam, BOOL bFinal)

#include <dinamo.h>

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

Parámetros

[en]	szKeyName	Nombre del objeto.
[en]	pParam	Puntero a un parámetro pasado a la función DListObjs().
[en]	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 de callback para registrar eventos generados por el servidor.

Parámetros

[en]	szEvento	Evento de registro.
[en]	pParam	Puntero a un parámetro pasado a la función DgetLogEvents.
[en]	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

[en]	pbData	Búfer que contiene los datos leídos.
[en]	pdwDataLen	Puntero a un DWORD que contiene el número de bytes leídos del fichero
[en]	pParam	Puntero a un parámetro pasado a la función DWriteFile().
[en]	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 la función de callback para guardar localmente el archivo recuperado del HSM.

Parámetros

[en]	pbData	Buffer con los datos que se escribirán en el fichero.
[en]	dwDataLen	Número de bytes a grabar.
[en]	pParam	Puntero a un parámetro pasado a la función DWriteFile().
[en]	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

[en]	pvToken	Puntero que recibirá una estructura DN_A_TOKEN_FULL conteniendo los datos del token de sesión.
[en]	pParam	Puntero a un parámetro pasado a la función DManageAToken().
[en]	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	hSesión,
		funcListKeyCallback	fncallback,
		vacío *	pParam )

#include <dinamo.h>

Enumera los objetos almacenados en el Dinamo , entre claves y archivos.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	fncallback	Puntero a una función de callback utilizada para listar los nombres (identificadores) de los objetos.
[en]	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

Las funciones API Dinamo no debe llamarse desde la función de devolución de llamada (parámetro fncallback) usando 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	hSesión,
		funcListKeyCallback	fncallback,
		vacío *	pParam )

#include <dinamo.h>

Enumera los blobs almacenados en el Dinamo .

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	fncallback	Puntero a una función de devolución de llamada utilizada para enumerar los nombres (identificadores) de los blobs.
[en]	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

Las funciones API Dinamo no debe llamarse desde la función de devolución de llamada (parámetro fncallback) usando 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	hSesión,
		char *	szBackupFile,
		char *	szPin,
		int	nDirección )

#include <dinamo.h>

Crea o restaura la copia de seguridad de los objetos (claves, certificados, etc.) registrados internamente en el Dinamo .

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szBackupFile	Ruta del archivo de copia de seguridad.
[en]	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.
[en]	nDirección	[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.

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 deriva de la contraseña ingresada por el usuario. Esta operación de cifrado/descifrado es independiente del modo de almacenamiento del objeto en el Dinamo (cifrado o no cifrado). La copia de seguridad siempre está cifrada. La contraseña utilizada para generar la copia de seguridad se debe utilizar al realizar la restauración. Es posible indicar si se restablecen o no los parámetros de red (dirección IP, máscara y puerta de enlace). Para restaurar archivos grandes, superiores a 2147483647 bytes, el servidor HSM debe tener al menos la versión 3.9.0.2 o superior.

Observación

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

DBackupObject()

int AAP_API DBackupObject	(	HSESSIONCTX	hSesión,
		DWORD	dwOP,
		char *	szObjectId,
		char *	szPin,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReservado )

#include <dinamo.h>

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

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	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.
[en]	szObjectId	Nombre del objeto dentro del HSM.
[en]	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.
[en]	dwReservado	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.

Como el objeto fue cifrado por SVMK, solo se puede restaurar en HSM Dinamo inicializado con este mismo 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	hSesión,
		funcLogEventCallback	fncallback,
		vacío *	pParam )

#include <dinamo.h>

Recupera los eventos de registro generados por el servidor.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	fncallback	Puntero a una función de callback utilizada para registrar eventos generados por el servidor.
[en]	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 opción permite que un programa reciba mensajes de registro generados internamente en el Dinamo ; el programa ahora recibe una copia de todos los mensajes de registro. Existe un límite de 03 (tres) receptores simultáneamente en el modo de recepción de notificaciones de eventos, para evitar la degradación del desempeño del HSM. Los mensajes enviados siguen registrándose en el archivo interno del servidor. El primer valor hexadecimal que se muestra en la línea de registro es una marca de tiempo y el segundo es una identificación utilizada internamente.

Ejemplos

get_rt_logs.c.

DAdmOperation()

int AAP_API DAdmOperation	(	HSESSIONCTX	hSesión,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Realiza operaciones administrativas en el servidor.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	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.
[en]	pbData	Puntero a los datos o estructuras especificados en dwParam.
[en]	dwDataLen	Tamaño de los datos o de la estructura especificada en dwParam.
[en]	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

La opción AO_KEEPALIVE realiza una prueba para indicar el latido del servicio. Dinamo . El resultado positivo de esta prueba muestra que el HSM está procesando correctamente las solicitudes de los clientes y que su estado interno es consistente y saludable. Puede ser utilizado, por ejemplo, por equipos de monitoreo y soporte para indicar el estado correcto del Dinamo .

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	Permite la autenticación de M de N particiones a través de la API.

Ejemplos

connect_hsm.c.

DGetHSMTLSCert()

int AAP_API DGetHSMTLSCert	(	char *	szDirección,
		int	nPuerto,
		DWORD	dwOutFormat,
		BYTE **	ppbOutCert,
		DWORD *	pdwOutCertLen,
		DWORD	dwFlags )

#include <dinamo.h>

Recupera el certificado HSM utilizado en TLS.

Parámetros

[en]	szDirección	Dirección HSM.
[en]	nPuerto	Puerto de acceso al HSM. El puerto por defecto es DEFAULT_PORT.
[en]	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.
[en]	ppbOutCert	Puntero con el certificado en el formato especificado en dwOutFormat. Este puntero debe liberarse con DFree.
[en]	pdwOutCertLen	Tamaño del certificado indicado en ppbOutCert.
[en]	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	hSesión,
		DWORD	dwOption,
		const char *	szTarget,
		void **	pvResultado,
		DWORD *	pdwResultLen,
		DWORD	dwFlags )

#include <dinamo.h>

Ejecutar herramientas de prueba desde el HSM.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	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.
[en]	szTarget	Dirección de destino de la operación a realizar. Tamaño máximo de DN_NT_MAX_TARGET_LEN.
[fuera]	pvResultado	Puntero que contendrá el resultado de la orden ejecutada. Este puntero debe ser liberado con DFree.
[fuera]	pdwResultLen	Tamaño del búfer devuelto en pvResultado.
[en]	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	hSesión,
		const char *	szFileId,
		BYTE *	pbArchivo,
		DWORD	dwTamañoArchivo,
		DWORD	dwOptions )

#include <dinamo.h>

Importar un archivo en HSM.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szFileId	Identificador del nuevo archivo dentro del HSM.
[en]	pbArchivo	Memoria intermedia que contiene el archivo que se va a importar.
[en]	dwTamañoArchivo	Tamaño del archivo que se va a cargar.
[en]	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	hSesión,
		char *	szFileId,
		DWORD	dwTamañoArchivo,
		funcReadLocalFileCallback	fncallback,
		vacío *	pParam )

#include <dinamo.h>

Importar un archivo en HSM.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szFileId	Identificador del nuevo archivo dentro del HSM.
[en]	dwTamañoArchivo	Tamaño del archivo que se va a cargar.
[en]	fncallback	Puntero a una función de devolución de llamada utilizada para leer el archivo que se va a cargar.
[en]	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	hSesión,
		char *	szFileId,
		funcWriteLocalFileCallback	fncallback,
		vacío *	pParam )

#include <dinamo.h>

Exportar un archivo HSM.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szFileId	Identificador del archivo dentro del HSM.
[en]	fncallback	Puntero a una función de devolución de llamada utilizada para escribir el archivo recuperado.
[en]	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	hSesión,
		const char *	szFileId,
		BYTE **	ppbData,
		DWORD *	pdwDataLen,
		DWORD	dwReservado )

#include <dinamo.h>

Exporta un archivo HSM a una memoria intermedia.

Parámetros

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

#include <dinamo.h>

Elimina un objeto almacenado en el Dinamo , ya sea una clave o un archivo.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	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	hSesión,
		DWORD	dwInicio,
		DWORD	dwOffset,
		DWORD *	pdwLogSize,
		BYTE **	ppbLog )

#include <dinamo.h>

Recupera el contenido del registro del servidor.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	dwStart	Posición inicial, en bytes, del registro a recuperar. Para recibir el contenido completo del registro, introduzca GET_LOG_START_FULL.
[en]	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 .
[fuera]	pdwLogSize	Puntero a DWORD que contendrá la cantidad, en bytes, del registro recuperado.
[fuera]	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

hSesión

)

#include <dinamo.h>

Permite borrar el contenido del registro del servidor.

Parámetros

[en]

hSesión

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	dwTipoServicio,
		DWORD	dwFiltro,
		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

[en]	dwTipoServicio	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 Enumera 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.
[en]	dwFiltro	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 Listar todos los HSM DINAMO Se encontró ST o XP. DN_FIND_FILTER_TYPE_ALL DINAMO Pocket Enumera todos los HSM ST, XP o encontrados.
[fuera]	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().
[fuera]	pdwOutputDataLen	Puntero a DWORD que contendrá el número de estructuras (descritas en dwTipoSalida) devuelto en ppvOutputData.
[en]	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	hSesión,
		BYTE	bOP,
		DN_A_TOKEN_FULL *	pstATokenFull,
		funcListAKeysCallback	fnCallBack,
		vacío *	pvCallbackParam,
		DWORD	dwParam )

#include <dinamo.h>

Gestiona lostokens de acceso propios del 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

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	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.
[en]	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.
[en]	pvCallbackParam	Puntero a cualquier parámetro que se pasará a la función de devolución de llamada. Puede ser NULL.
[en]	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 tokens de acceso 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	hSesión,
		DWORD	dwOP,
		vacío *	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

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	dwOP	Especifica la operación a realizar. Valor Significado DN_ATOKEN_CACHE_GET_COUNT Recupera el número de testigos de sesión de todo el HSM. Pasar 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.
[fuera]	pOutData	Datos de salida. Ver opciones de uso en dwOP.
[en]	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	hSesión,
		const char *	szBindKey,
		DWORD	dwReservado )

#include <dinamo.h>

Asociar un HSM con una cuenta Dinamo Servicios.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szBindKey	Clave de enlace. Generado en el sitio web. Dinamo Servicios.
[en]	dwReservado	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	hSesión,
		DWORD	dwReservado )

#include <dinamo.h>

Desvincula un HSM de una cuenta Dinamo Servicios.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	dwReservado	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_M_DE_N_PARTE *	pstPart,
		DWORD	dwReservado )

#include <dinamo.h>

DinamoLee la sombra de una tarjeta inteligente M de N .

Parámetros

[en]	szPin	PIN de la tarjeta. Debe ser una cadena numérica ASCII con una longitud máxima de DN_SC_MAX_PIN_LEN.
[fuera]	pstPart	Datos de la lectura sombra. Los detalles se pueden ver con la estructura DN_M_OF_N_PART_DETAILS.
[en]	dwReservado	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	hSesión,
		DWORD	dwAcl,
		BYTE	bEstado,
		DN_M_DE_N_PARTE *	pstPartes,
		DWORD	dwPartsCount,
		DWORD	dwReservado )

#include <dinamo.h>

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

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	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.
[en]	bEstado	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.
[en]	pstPartes	Datos de la partición M de N.
[en]	dwPartsCount	Número de piezas.
[en]	dwReservado	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	nValorError,
		char *	szErrorCode,
		char *	szErrorDesc )

#include <dinamo.h>

Obsoleto

Esta API está descontinuada, utilice DGetReturnCodeString().

DGetReturnCodeString()

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

#include <dinamo.h>

Recupera la descripción de un código de retorno de API. DINAMO .

Parámetros

[en]	nValorError	Código de devolución.
[en]	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.