Descripción detallada

Gestión de secretos compartidos.

Introducción

Las API del módulo Custodia están diseñadas para facilitar la gestión de los secretos custodiados, también conocidos como Parámetros Críticos de Seguridad (CSP).

Dentro del módulo Safe Keeping, es posible llevar a cabo la custodia compartida de secretos almacenados en el HSM. Estos secretos se generan con alta seguridad, en hardware homologado, garantizando una alta entropía y protección frente a diversos ataques, incluidos los de canal lateral.

Arquitectura

El módulo de mantenimiento de la seguridad funciona en 3 etapas.

Generar secretismo;
Repartición departes del secreto mediante el algoritmo de Shamir (SSS);
Recuperación del secreto a partir de las piezas generadas en el paso anterior.

Generar secreto

En esta fase, el secreto se genera en una partición (usuario) del HSM, de forma segura y con alta entropía, y sólo existe en el HSM.

Cada partición tiene autenticación de credenciales con un nombre de usuario y una contraseña, y opcionalmente se puede configurar autenticación adicional, como por ejemplo:

M de N de partición;
2fA con tokens OTP (One Time Password) en el formato OATH;
2fA con certificados X.509;

Puede combinar uno o más tipos de autenticación de partición según sea necesario.

El secreto puede generarse en función de varios niveles de seguridad y de las necesidades del proyecto. Debe elegirse con cuidado para que el nivel de seguridad sea equivalente en otros puntos del proyecto. Un nivel de seguridad demasiado bajo puede debilitar la seguridad de los datos que se protegen, mientras que un nivel de seguridad demasiado alto puede ralentizar innecesariamente las operaciones.

Consulte el cuadro siguiente para hacerse una idea.

Nivel de seguridad	Tamaño en bytes	Cantidad física correspondiente
64 bits	8	Granos de arena en la Tierra.
96 bits	12	Los átomos en el cuerpo humano.
112 bits	14	Diámetro del universo observable en milésimas de milímetro.
128 bits	16	Átomos de oxígeno en la atmósfera terrestre.
160 bits	20	Átomos en la Tierra.

Repartición del secreto mediante el algoritmo de Shamir

En esta etapa, laspartes del secreto se dividen utilizando el algoritmo de Shamir (Shamir Shared Secret) en el esquema M de N.

El esquema M de N significa que a partir de un grupo de N partes, se necesitan M partes para recomponer el secreto.

Las partes, también conocidas como acciones o sombras, se generan de tal forma que es imposible recomponer el secreto con menos de M partes.

La generación de piezas suele hacerse en una ceremonia, en la que cada pieza se distribuye a un miembro de la organización y se almacena de forma segura. De este modo se evita la connivencia entre los miembros de la organización. La forma en que se distribuyen las piezas, la elección de los miembros y otros detalles de la ceremonia se definen en función de cada empresa.

Las partes son ligeramente más grandes que el nivel de seguridad porque contienen metadatos del esquema M de N. Cada parte está disponible en formato Base62 para facilitar la anotación.

‍Se recomienda generar sumas de comprobación para cada parte en este punto. Esto facilita la comprobación de la tipificación de las partes en el momento de la recuperación.

Recuperación del secreto a partir de las partes generadas en el paso anterior

El secreto se recompone utilizando M de las N partes generadas en el paso anterior.

En este caso, se celebra una ceremonia de recuperación del secreto. Es necesario que cada custodio (titular de una acción) introduzca su acción para recuperar el secreto. Esta ceremonia se define en función de cada acuerdo.

El secreto varía de tamaño en función del nivel de seguridad utilizado, y está disponible en formato Base62 para facilitar las anotaciones.

‍Se recomienda comprobar las sumas de comprobación de cada parte en este punto. Esto evita errores de escritura en un momento crítico.

Utilice

Consulte la API a continuación y los ejemplos para facilitar la implementación.

Gestión de secretos compartidos. Más...

Definiciones y macros
#define	DN_SKEEP_LEVEL_UNKNOWN (0)

#define	DN_SKEEP_SEC_LEVEL_64b (1)

#define	DN_SKEEP_SEC_LEVEL_96b (2)

#define	DN_SKEEP_SEC_LEVEL_112b (3)

#define	DN_SKEEP_SEC_LEVEL_128b (4)

#define	DN_SKEEP_SEC_LEVEL_160b (5)

#define	DN_SKEEP_TYPE_NMIND (0)

#define	DN_SKEEP_TYPE_SCRD (1)

#define	DN_SKEEP_TYPE_2FA (2)

#define	DN_SKEEP_TYPE_CRT (4)

#define	DN_SKEEP_SHARE_CKS_LEN (4)

#define	DN_SKEEP_GEN_SHARE_CKS (1)

Funciones
int AAP_API	DSKeepNewSecret (HSESSIONCTX hSession, const char *cszId, BYTE bSecLevel, WORD wAuthType, DWORD dwReserved)

int AAP_API	DSKeepSplitSecret (HSESSIONCTX hSession, const char cszId, BYTE bSecLevel, WORD wAuthType, BYTE bM, BYTE bN, SKeepShare pstShares, DWORD dwReserved)

int AAP_API	DSKeepProbeSecret (HSESSIONCTX hSession, const char cszId, SKeepProbeInfo pstInfo, DWORD dwReserved)

int AAP_API	DSKeepMatchSecret (HSESSIONCTX hSession, const char cszId, const SKeepShare cpstShares, DWORD dwSharesCount, DWORD dwReserved)

int AAP_API	DSKeepRecoverSecret (HSESSIONCTX hSession, const char cszId, const SKeepShare cpstShares, DWORD dwSharesCount, SKeepRecoverInfo *pstRecoverInfo, DWORD dwReserved)

int AAP_API	DSKeepRemoveSecret (HSESSIONCTX hSession, const char *cszId, BYTE bSecLevel, WORD wAuthType, DWORD dwReserved)

int AAP_API	DSKeepCalcShareCks (DWORD dwType, const char cszShare, char szCks)

Definiciones y macros

◆ DN_SKEEP_LEVEL_UNKNOWN

#define DN_SKEEP_LEVEL_UNKNOWN (0)

#include <dinamo.h>

Nivel de seguridad desconocido. Utilizado en DSKeepProbeSecret().

◆ DN_SKEEP_SEC_LEVEL_64b

#define DN_SKEEP_SEC_LEVEL_64b (1)

#include <dinamo.h>

Nivel de seguridad de 64 bits.

◆ DN_SKEEP_SEC_LEVEL_96b

#define DN_SKEEP_SEC_LEVEL_96b (2)

#include <dinamo.h>

Nivel de seguridad de 96 bits.

◆ DN_SKEEP_SEC_LEVEL_112b

#define DN_SKEEP_SEC_LEVEL_112b (3)

#include <dinamo.h>

Nivel de seguridad de 112 bits.

◆ DN_SKEEP_SEC_LEVEL_128b

#define DN_SKEEP_SEC_LEVEL_128b (4)

#include <dinamo.h>

Nivel de seguridad de 128 bits.

◆ DN_SKEEP_SEC_LEVEL_160b

#define DN_SKEEP_SEC_LEVEL_160b (5)

#include <dinamo.h>

Nivel de seguridad de 160 bits.

Ejemplos: skeep_new_split_recover .c y skeep_probe_match.c.

◆ DN_SKEEP_TYPE_NMIND

#define DN_SKEEP_TYPE_NMIND (0)

#include <dinamo.h>

No limita el tipo de autenticación.

Ejemplos: skeep_new_split_recover .c y skeep_probe_match.c.

◆ DN_SKEEP_TYPE_SCRD

#define DN_SKEEP_TYPE_SCRD (1)

#include <dinamo.h>

Partición con M de N autenticación.

◆ DN_SKEEP_TYPE_2FA

#define DN_SKEEP_TYPE_2FA (2)

#include <dinamo.h>

Partición con autenticación OATH.

◆ DN_SKEEP_TYPE_CRT

#define DN_SKEEP_TYPE_CRT (4)

#include <dinamo.h>

Partición con autenticación X.509.

◆ DN_SKEEP_SHARE_CKS_LEN

#define DN_SKEEP_SHARE_CKS_LEN (4)

#include <dinamo.h>

Tamaño del valor de verificación (cuota) de una parte.

Ejemplos: skeep_new_split_recover.c.

◆ DN_SKEEP_GEN_SHARE_CKS

#define DN_SKEEP_GEN_SHARE_CKS (1)

#include <dinamo.h>

Genera el valor de verificación de una acción.

Ejemplos: skeep_new_split_recover.c.

Funciones

◆ DSKeepNewSecret()

int AAP_API DSKeepNewSecret	(	HSESSIONCTX	hSesión,
		const char *	cszId,
		BYTE	bSecLevel,
		PALABRA	wAuthType,
		DWORD	dwReservado )

#include <dinamo.h>

Cree un nuevo secreto utilizando el módulo Guardado Seguro.

Parámetros

[en] hSesión Contexto adquirido a través de la función DOpenSession().

[en] cszId Identificador del objeto que se va a crear en el HSM. Véase szKeyId en DGenerateKey() para obtener más información sobre el tamaño máximo de los identificadores.

[en]

bSecLevel

Nivel de seguridad. Puede ser una de las opciones siguientes.

Valor	Significado	Tamaño en bytes	Cantidad física correspondiente
DN_SKEEP_SEC_LEVEL_64b	Nivel de seguridad de 64 bits.	8	Granos de arena en la tierra
DN_SKEEP_SEC_LEVEL_96b	Nivel de seguridad de 96 bits.	12	Los átomos en el cuerpo humano
DN_SKEEP_SEC_LEVEL_112b	Nivel de seguridad de 112 bits.	14	Diámetro del Universo observable en miles de milímetros
DN_SKEEP_SEC_LEVEL_128b	Nivel de seguridad de 128 bits.	16	Átomos de oxígeno en la atmósfera terrestre
DN_SKEEP_SEC_LEVEL_160b	Nivel de seguridad de 160 bits.	20	Átomos en la Tierra
DN_SKEEP_LEVEL_UNKNOWN	Nivel de seguridad desconocido. Utilizado en DSKeepProbeSecret().	-	-

‍Los secretos son ligeramente más pequeños que sus acciones porque no tienen la metainformación del esquema M de N.

Parámetros

[en]

wAuthType

Tipo de autenticación requerida por la partición secreta. Puede ser uno o una combinación de los valores siguientes.

Valor	Significado
DN_SKEEP_TYPE_NMIND	No limita el tipo de autenticación.
DN_SKEEP_TYPE_SCRD	Partición con M de N autenticación.
DN_SKEEP_TYPE_2FA	Partición con autenticación OATH.
DN_SKEEP_TYPE_CRT	Partición con autenticación X.509.

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

Ejemplos: skeep_new_split_recover .c y skeep_probe_match.c.

◆ DSKeepSplitSecret()

int AAP_API DSKeepSplitSecret	(	HSESSIONCTX	hSesión,
		const char *	cszId,
		BYTE	bSecLevel,
		PALABRA	wAuthType,
		BYTE	bM,
		BYTE	bN,
		SKeepShare *	pstShares,
		DWORD	dwReservado )

#include <dinamo.h>

Divide M de N en secreto. Según el estándar de compartición de secretos de Shamir.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	cszId	Identificador del objeto en el HSM.
[en]	bSecLevel	Nivel de seguridad. Ver opciones en DSKeepNewSecret().
[en]	wAuthType	Tipo de autenticación requerida por la partición secreta. Ver opciones en DSKeepNewSecret().
[en]	bM	Número mínimo de acciones necesarias para reconstruir el secreto. Debe ser mayor o igual que DN_SKEEP_M_OF_N_S_MIN y menor o igual que DN_SKEEP_M_OF_N_S_MAX.
[en]	bN	Número de acciones a generar. Debe ser mayor o igual que DN_SKEEP_M_OF_N_S_MIN y menor o igual que DN_SKEEP_M_OF_N_S_MAX.
[fuera]	pstShares	Vector de estructura SKeepShare que recibirá las acciones generadas. El tamaño de este vector debe ser `bN` elementos. ‍Las acciones son ligeramente mayores que su secreto correspondiente porque contienen la metainformación del esquema M de N.

Parámetros

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

Ejemplos: skeep_new_split_recover .c y skeep_probe_match.c.

◆ DSKeepProbeSecret()

int AAP_API DSKeepProbeSecret	(	HSESSIONCTX	hSesión,
		const char *	cszId,
		SKeepProbeInfo *	pstInfo,
		DWORD	dwReservado )

#include <dinamo.h>

Recuperar información de un secreto.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	cszId	Identificador del objeto en el HSM.
[fuera]	pstInfo	Estructura que recibirá la información del secreto. Recibe una estructura SKeepProbeInfo.
[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.

Ejemplos: skeep_probe_match.c.

◆ DSKeepMatchSecret()

int AAP_API DSKeepMatchSecret	(	HSESSIONCTX	hSesión,
		const char *	cszId,
		const SKeepShare *	cpstShares,
		DWORD	dwSharesCount,
		DWORD	dwReservado )

#include <dinamo.h>

Comprueba que las acciones de un secreto son válidas.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	cszId	Identificador del objeto en el HSM.
[en]	cpstShares	Vector de estructura SKeepShare que contiene las acciones del secreto. El número de elementos de este vector debe introducirse en `dwSharesCount`. La cantidad de este buffer debe ser la cantidad de M piezas.
[en]	dwSharesCount	Número de `pstShares`.
[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: Si se utiliza con una autorización de partición M de N, esta API puede utilizarse sin estar autorizada.

Ejemplos: skeep_probe_match.c.

◆ DSKeepRecoverSecret()

int AAP_API DSKeepRecoverSecret	(	HSESSIONCTX	hSesión,
		const char *	cszId,
		const SKeepShare *	cpstShares,
		DWORD	dwSharesCount,
		SKeepRecoverInfo *	pstRecoverInfo,
		DWORD	dwReservado )

#include <dinamo.h>

Recuperar un secreto a partir de sus partes (compartir).

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	cszId	Identificador del objeto en el HSM.
[en]	cpstShares	Vector de estructura SKeepShare que contiene las acciones del secreto. El número de elementos de este vector debe introducirse en `dwSharesCount`. La cantidad de este buffer debe ser la cantidad de M piezas.
[en]	dwSharesCount	Número de `pstShares`.
[fuera]	pstRecoverInfo	Estructura que recibirá la información secreta. Recibe una estructura SKeepRecoverInfo.
[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.

Ejemplos: skeep_new_split_recover.c.

◆ DSKeepRemoveSecret()

int AAP_API DSKeepRemoveSecret	(	HSESSIONCTX	hSesión,
		const char *	cszId,
		BYTE	bSecLevel,
		PALABRA	wAuthType,
		DWORD	dwReservado )

#include <dinamo.h>

Eliminar un secreto.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	cszId	Identificador del objeto en el HSM.
[en]	bSecLevel	Nivel de seguridad. Ver opciones en DSKeepNewSecret().
[en]	wAuthType	Tipo de autenticación requerida por la partición secreta. Ver opciones en DSKeepNewSecret().
[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.

Ejemplos: skeep_new_split_recover .c y skeep_probe_match.c.

◆ DSKeepCalcCompartirCks()

int AAP_API DSKeepCalcShareCks	(	DWORD	dwType,
		const char *	cszShare,
		char *	szCks )

#include <dinamo.h>

Genera el valor de verificación de una acción.

Parámetros

[en]

dwType

Tipo de operación. Puede ser uno de los valores siguientes.

Valor	Significado
DN_SKEEP_GEN_SHARE_CKS	Genera el valor de comprobación de una acción. Consiste en una cadena de números DN_SKEEP_SHARE_CKS_LEN más el terminador nulo.

[en] cszCompartir Buffer que contiene la parte del secreto.

[fuera] szCks Buffer que recibirá el valor de comprobación. El tamaño de este búfer debe ser DN_SKEEP_SHARE_CKS_LEN + 1.

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

Ejemplos: skeep_new_split_recover.c.