Descrição detalhada

Gerência de segredos compartilhados.

Introdução

As APIs do módulo Safe Keeping visam facilitar as operações de gerenciamento dos segredos custodiados, também conhecidos como Critical Security Parameter (CSP).

Dentro do módulo Safe Keeping, é possível realizar a custódia compartilhada de segredos armazenados no HSM. Esses segredos são gerados com alta segurança, em hardware homologado, garantindo alta entropia e proteção contra uma variedade de ataques, inclusive ataques de side channel.

Arquitetura

O módulo Safe Keeping opera em 3 etapas.

Geração do segredo;
Divisão de partes (shares) do segredo utilizando o algoritmo de Shamir (SSS);
Recuperação do segredo a partir das partes geradas no passo anterior.

Geração do segredo

Nesta etapa o segredo é gerado em uma partição (usuário) do HSM, de forma segura e com alta entropia e existe apenas no HSM.

Cada partição possui autenticação de credencial com usuário e senha e opcionalmente pode ser configurada autenticação adicional, como:

M de N de partição;
2fA com tokens OTP (One Time Password) no formato OATH;
2fA com certificados X.509;

É possível combinar um ou mais tipos de autenticação de partição, conforme a necessidade.

O segredo pode ser gerado de acordo com vários níveis de segurança e com a necessidade do projeto. Ele deve ser escolhido com cuidado para que o nível de segurança seja equivalente nos outros pontos do projeto. Um nível de segurança muito baixo pode fragilizar a segurança dos dados que serão protegidos, já um nível de segurança muito além do necessário pode tornar as operações lentas desnecessariamente.

Veja a tabela a seguir para ter uma ideia.

Nível de segurança	Tamanho em bytes	Grandeza Física Correspondente
64 bits	8	Grãos de areia na Terra.
96 bits	12	Átomos no corpo humano.
112 bits	14	Diâmetro do universo observável em milésimos de milímetros.
128 bits	16	Átomos de oxigênio na atmosfera terrestre.
160 bits	20	Átomos na Terra.

Divisão de partes (shares) do segredo utilizando o algoritmo de Shamir

Nesta estapa é feita a divisão das partes (shares) do segredo, utilizando o algoritmo de Shamir (Shamir Shared Secret) no esquema M de N.

O esquema M de N permite que de um grupo de N partes, sejam necessárias M partes para recompor o segredo.

As partes, também conhecidas como share ou shadow, são geradas de uma forma que seja impossível recompor o segredo com menos do que M partes.

A geração das partes geralmente é feita em uma cerimônia, onde cada parte é distribuída para um membro da organização, e guardada de forma segura. Esta forma evita o conluio de membros da organização. A maneira de distribuir as partes, escolha dos membros e outros detalhes da cerimônia são definidas de acordo com cada negócio.

As partes têm tamanho ligeiramente maior que o nível de segurança por conterem metadados do esquema M de N. Cada parte é disponibilizada no formato Base62 para facilitar a anotação.

‍É recomendado que se gere checksums para cada parte, neste momento. Isto facilita a verificação da digitação das partes no momento da recuperação.

Recuperação do segredo a partir das partes geradas no passo anterior

A recomposição do segredo é feita utilizando M das N partes geradas no passo anterior.

Neste caso é feita uma cerimônia de recuperação de segredo. É necessário que cada custodiante (portador de uma parte) insira a sua parte para a recomposição do segredo. Esta cerimônia é definida de acordo com cada negócio.

O segredo tem tamanho variável dependendo do nível de segurança utilizado, e é disponibilizado no formato Base62 para facilitar a anotação.

‍É recomendado que se verifique os checksums de cada parte, neste momento. Desta forma, evita-se os erros de digitação em um momento crítico.

Uso

Veja as API abaixo e os exemplos para facilitar a implementação.

Gerência de segredos compartilhados. Mais...

Definições e 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)

Funções
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)

Definições e macros

◆ DN_SKEEP_LEVEL_UNKNOWN

#define DN_SKEEP_LEVEL_UNKNOWN (0)

#include <dinamo.h>

Nível de segurança não conhecido. Usado em DSKeepProbeSecret().

◆ DN_SKEEP_SEC_LEVEL_64b

#define DN_SKEEP_SEC_LEVEL_64b (1)

#include <dinamo.h>

Nível de segurança de 64 bits.

◆ DN_SKEEP_SEC_LEVEL_96b

#define DN_SKEEP_SEC_LEVEL_96b (2)

#include <dinamo.h>

Nível de segurança de 96 bits.

◆ DN_SKEEP_SEC_LEVEL_112b

#define DN_SKEEP_SEC_LEVEL_112b (3)

#include <dinamo.h>

Nível de segurança de 112 bits.

◆ DN_SKEEP_SEC_LEVEL_128b

#define DN_SKEEP_SEC_LEVEL_128b (4)

#include <dinamo.h>

Nível de segurança de 128 bits.

◆ DN_SKEEP_SEC_LEVEL_160b

#define DN_SKEEP_SEC_LEVEL_160b (5)

#include <dinamo.h>

Nível de segurança de 160 bits.

Exemplos: skeep_new_split_recover.c e skeep_probe_match.c.

◆ DN_SKEEP_TYPE_NMIND

#define DN_SKEEP_TYPE_NMIND (0)

#include <dinamo.h>

Não limita o tipo de autenticação.

Exemplos: skeep_new_split_recover.c e skeep_probe_match.c.

◆ DN_SKEEP_TYPE_SCRD

#define DN_SKEEP_TYPE_SCRD (1)

#include <dinamo.h>

Partição com autenticação M de N.

◆ DN_SKEEP_TYPE_2FA

#define DN_SKEEP_TYPE_2FA (2)

#include <dinamo.h>

Partição com autenticação OATH.

◆ DN_SKEEP_TYPE_CRT

#define DN_SKEEP_TYPE_CRT (4)

#include <dinamo.h>

Partição com autenticação X.509.

◆ DN_SKEEP_SHARE_CKS_LEN

#define DN_SKEEP_SHARE_CKS_LEN (4)

#include <dinamo.h>

Tamanho do valor de verificação de uma parte (share).

Exemplos: skeep_new_split_recover.c.

◆ DN_SKEEP_GEN_SHARE_CKS

#define DN_SKEEP_GEN_SHARE_CKS (1)

#include <dinamo.h>

Gera o valor de verificação de uma parte (share).

Exemplos: skeep_new_split_recover.c.

Funções

◆ DSKeepNewSecret()

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

#include <dinamo.h>

Cria um novo segredo utilizando módulo Safe Keeping.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in] cszId Indentificador do objeto que será criado no HSM. Veja szKeyId em DGenerateKey() para detalhes sobre tamanhos máximos de identificadores.

[in]

bSecLevel

Nível de segurança. Pode ser uma das opções abaixo.

Valor	Significado	Tamanho em bytes	Grandeza Física Correspondente
DN_SKEEP_SEC_LEVEL_64b	Nível de segurança de 64 bits.	8	Grãos de Areia na Terra
DN_SKEEP_SEC_LEVEL_96b	Nível de segurança de 96 bits.	12	Átomos no Corpo Humano
DN_SKEEP_SEC_LEVEL_112b	Nível de segurança de 112 bits.	14	Diâmetro do Universo Observável em Milésimos de Milímetros
DN_SKEEP_SEC_LEVEL_128b	Nível de segurança de 128 bits.	16	Átomos de Oxigênio na Atmosfera Terrestre
DN_SKEEP_SEC_LEVEL_160b	Nível de segurança de 160 bits.	20	Átomos na Terra
DN_SKEEP_LEVEL_UNKNOWN	Nível de segurança não conhecido. Usado em DSKeepProbeSecret().	-	-

‍Os segredos são ligeiramente menores que as suas partes (shares) por não terem a meta informação do esquema M de N.

Parâmetros

[in]

wAuthType

Tipo de autenticação requerida pela partição do segredo. Pode ser um ou a combinação dos valores abaixo.

Valor	Significado
DN_SKEEP_TYPE_NMIND	Não limita o tipo de autenticação.
DN_SKEEP_TYPE_SCRD	Partição com autenticação M de N.
DN_SKEEP_TYPE_2FA	Partição com autenticação OATH.
DN_SKEEP_TYPE_CRT	Partição com autenticação X.509.

[in] dwReserved Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos: skeep_new_split_recover.c e skeep_probe_match.c.

◆ DSKeepSplitSecret()

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

#include <dinamo.h>

Faz a divisão M de N de um segredo. De acordo com o padrão de compartilhamento de segredos de Shamir.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	cszId	Indentificador do objeto no HSM.
[in]	bSecLevel	Nível de segurança. Ver opções em DSKeepNewSecret().
[in]	wAuthType	Tipo de autenticação requerida pela partição do segredo. Ver opções em DSKeepNewSecret().
[in]	bM	Quantidade mínima de partes (share) necessárias para reconstrução do segredo. Deve ser maior ou igual a DN_SKEEP_M_OF_N_S_MIN e menor ou igual a DN_SKEEP_M_OF_N_S_MAX.
[in]	bN	Quantidade de partes (share) que serão geradas. Deve ser maior ou igual a DN_SKEEP_M_OF_N_S_MIN e menor ou igual a DN_SKEEP_M_OF_N_S_MAX.
[out]	pstShares	Vetor de estruturas SKeepShare que receberá as partes (share) geradas. O tamanho deste vetor deve ser `bN` elementos. ‍As partes (shares) são ligeiramente maiores do que seu segredo correspondente, por conterem a meta informação do esquema M de N.

Parâmetros

[in] dwReserved Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos: skeep_new_split_recover.c e skeep_probe_match.c.

◆ DSKeepProbeSecret()

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

#include <dinamo.h>

Recupera informaçoes de um segredo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	cszId	Indentificador do objeto no HSM.
[out]	pstInfo	Estrutura que receberá as informações do segredo. Recebe uma estrutura SKeepProbeInfo.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos: skeep_probe_match.c.

◆ DSKeepMatchSecret()

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

#include <dinamo.h>

Verifica se as partes (share) de um segredo são válidas.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	cszId	Indentificador do objeto no HSM.
[in]	cpstShares	Vetor de estruturas SKeepShare que contém as partes (share) do segredo. A quantidade de elementos deste vetor deve ser informado em `dwSharesCount`. A quantidade deste buffer deve ser a quantidade de partes M.
[in]	dwSharesCount	Quantidade de elementos de `pstShares`.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: Caso seja utilizada com autorização M de N de partição, esta API pode ser utilizada sem estar autorizada.

Exemplos: skeep_probe_match.c.

◆ DSKeepRecoverSecret()

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

#include <dinamo.h>

Recupera um segredo a partir de suas partes (share).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	cszId	Indentificador do objeto no HSM.
[in]	cpstShares	Vetor de estruturas SKeepShare que contém as partes (share) do segredo. A quantidade de elementos deste vetor deve ser informado em `dwSharesCount`. A quantidade deste buffer deve ser a quantidade de partes M.
[in]	dwSharesCount	Quantidade de elementos de `pstShares`.
[out]	pstRecoverInfo	Estrutura que receberá as informações do segredo. Recebe uma estrutura SKeepRecoverInfo.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos: skeep_new_split_recover.c.

◆ DSKeepRemoveSecret()

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

#include <dinamo.h>

Remove um segredo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	cszId	Indentificador do objeto no HSM.
[in]	bSecLevel	Nível de segurança. Ver opções em DSKeepNewSecret().
[in]	wAuthType	Tipo de autenticação requerida pela partição do segredo. Ver opções em DSKeepNewSecret().
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos: skeep_new_split_recover.c e skeep_probe_match.c.

◆ DSKeepCalcShareCks()

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

#include <dinamo.h>

Gera o valor de verificação de uma parte (share).

Parâmetros

[in]

dwType

Tipo da operação. Pode ser um dos valores abaixo.

Valor	Significado
DN_SKEEP_GEN_SHARE_CKS	Gera o valor de verificação de uma parte (share). Consiste em uma string de DN_SKEEP_SHARE_CKS_LEN números mais o terminador nulo.

[in] cszShare Buffer que contém a parte (share) do segredo.

[out] szCks Buffer que receberá o valor de verificação. O tamanho deste buffer deve ser DN_SKEEP_SHARE_CKS_LEN + 1.

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos: skeep_new_split_recover.c.

Descrição detalhada

Introdução

Arquitetura

Geração do segredo

Divisão de partes (shares) do segredo utilizando o algoritmo de Shamir

Recuperação do segredo a partir das partes geradas no passo anterior

Uso

Definições e Macros

Funções

Definições e macros

◆ DN_SKEEP_LEVEL_UNKNOWN

◆ DN_SKEEP_SEC_LEVEL_64b

◆ DN_SKEEP_SEC_LEVEL_96b

◆ DN_SKEEP_SEC_LEVEL_112b

◆ DN_SKEEP_SEC_LEVEL_128b

◆ DN_SKEEP_SEC_LEVEL_160b

◆ DN_SKEEP_TYPE_NMIND

◆ DN_SKEEP_TYPE_SCRD

◆ DN_SKEEP_TYPE_2FA

◆ DN_SKEEP_TYPE_CRT

◆ DN_SKEEP_SHARE_CKS_LEN

◆ DN_SKEEP_GEN_SHARE_CKS

Funções

◆ DSKeepNewSecret()

◆ DSKeepSplitSecret()

◆ DSKeepProbeSecret()

◆ DSKeepMatchSecret()

◆ DSKeepRecoverSecret()

◆ DSKeepRemoveSecret()

◆ DSKeepCalcShareCks()