Detailed description

Management of shared secrets.

Introduction

The Safe Keeping module's APIs are designed to make it easier to manage secrets in custody, also known as Critical Security Parameter (CSP).

The Safe Keeping module enables shared custody of secrets stored in the HSM. These secrets are generated with high security, on approved hardware, guaranteeing high entropy and protection against a variety of attacks, including side channel attacks.

Architecture

The Safe Keeping module operates in 3 stages.

Generating secrecy;
Splittingshares of the secret using the Shamir algorithm (SSS);
Recovery of the secret from the parts generated in the previous step.

Generating secrecy

At this stage the secret is generated in a partition (user) of the HSM, securely and with high entropy, and exists only in the HSM.

Each partition has credential authentication with a username and password and additional authentication can optionally be configured, such as:

M of N of partition;
2fA with OTP (One Time Password) tokens in the format OATH;
2fA with X.509 certificates;

You can combine one or more types of partition authentication as required.

The secret can be generated according to various security levels and the needs of the project. It must be chosen carefully so that the level of security is equivalent at other points in the project. A security level that is too low can weaken the security of the data being protected, while a security level that is too high can slow down operations unnecessarily.

See the table below for an idea.

Security level	Size in bytes	Corresponding Physical Quantity
64 bits	8	Grains of sand on Earth.
96 bits	12	Atoms in the human body.
112 bits	14	Diameter of the observable universe in thousandths of a millimeter.
128 bits	16	Oxygen atoms in the Earth's atmosphere.
160 bits	20	Atoms on Earth.

Splittingshares of the secret using Shamir's algorithm

At this stage, theshares of the secret are divided using the Shamir algorithm (Shamir Shared Secret) in the M of N scheme.

The M of N scheme means that from a group of N parts, M parts are needed to recompose the secret.

The parts, also known as shares or shadows, are generated in such a way that it is impossible to recompose the secret with fewer than M parts.

The generation of parts is usually done in a ceremony, where each part is distributed to a member of the organization and stored securely. This prevents collusion between members of the organization. The way the shares are distributed, the choice of members and other details of the ceremony are defined according to each business.

The parts are slightly larger than the security level because they contain metadata from the M of N scheme. Each part is available in Base62 format to facilitate annotation.

‍It is recommended to generate checksums for each part at this point. This makes it easier to verify the typing of the parts at the time of retrieval.

Recovery of the secret from the parts generated in the previous step

The secret is recomposed using M of the N parts generated in the previous step.

In this case, a secret recovery ceremony takes place. It is necessary for each custodian (Cardholder of a party) to insert their part for the recovery of the secret. This ceremony is defined according to each deal.

The secret varies in size depending on the security level used, and is available in Base62 format for easy annotation.

‍It is recommended to check the checksums of each part at this point. This avoids typing errors at a critical moment.

Use

See the API below and the examples to facilitate implementation.

Management of shared secrets. More...

Settings and 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)

Functions
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)

Definitions and macros

◆ DN_SKEEP_LEVEL_UNKNOWN

#define DN_SKEEP_LEVEL_UNKNOWN (0)

#include <dinamo.h>

Security level not known. Used in DSKeepProbeSecret().

◆ DN_SKEEP_SEC_LEVEL_64b

#define DN_SKEEP_SEC_LEVEL_64b (1)

#include <dinamo.h>

64-bit security level.

◆ DN_SKEEP_SEC_LEVEL_96b

#define DN_SKEEP_SEC_LEVEL_96b (2)

#include <dinamo.h>

96-bit security level.

◆ DN_SKEEP_SEC_LEVEL_112b

#define DN_SKEEP_SEC_LEVEL_112b (3)

#include <dinamo.h>

112-bit security level.

◆ DN_SKEEP_SEC_LEVEL_128b

#define DN_SKEEP_SEC_LEVEL_128b (4)

#include <dinamo.h>

128-bit security level.

◆ DN_SKEEP_SEC_LEVEL_160b

#define DN_SKEEP_SEC_LEVEL_160b (5)

#include <dinamo.h>

160-bit security level.

Examples: skeep_new_split_recover.c and skeep_probe_match.c.

◆ DN_SKEEP_TYPE_NMIND

#define DN_SKEEP_TYPE_NMIND (0)

#include <dinamo.h>

It does not limit the type of authentication.

Examples: skeep_new_split_recover.c and skeep_probe_match.c.

◆ DN_SKEEP_TYPE_SCRD

#define DN_SKEEP_TYPE_SCRD (1)

#include <dinamo.h>

Partition with M of N authentication.

◆ DN_SKEEP_TYPE_2FA

#define DN_SKEEP_TYPE_2FA (2)

#include <dinamo.h>

Partition with authentication OATH.

◆ DN_SKEEP_TYPE_CRT

#define DN_SKEEP_TYPE_CRT (4)

#include <dinamo.h>

Partition with X.509 authentication.

◆ DN_SKEEP_SHARE_CKS_LEN

#define DN_SKEEP_SHARE_CKS_LEN (4)

#include <dinamo.h>

Size of a party's verification value (share).

Examples: skeep_new_split_recover.c.

◆ DN_SKEEP_GEN_SHARE_CKS

#define DN_SKEEP_GEN_SHARE_CKS (1)

#include <dinamo.h>

Generates the check value of a share.

Examples: skeep_new_split_recover.c.

Functions

◆ DSKeepNewSecret()

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

#include <dinamo.h>

Create a new secret using the Safe Keeping module.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in] cszId Identifier of the object to be created in the HSM. See szKeyId in DGenerateKey() for details on maximum identifier sizes.

[in]

bSecLevel

Security level. It can be one of the options below.

Value	Meaning	Size in bytes	Corresponding Physical Quantity
DN_SKEEP_SEC_LEVEL_64b	64-bit security level.	8	Grains of Sand in the Earth
DN_SKEEP_SEC_LEVEL_96b	96-bit security level.	12	Atoms in the Human Body
DN_SKEEP_SEC_LEVEL_112b	112-bit security level.	14	Diameter of the Observable Universe in Thousands of Millimeters
DN_SKEEP_SEC_LEVEL_128b	128-bit security level.	16	Oxygen Atoms in the Earth's Atmosphere
DN_SKEEP_SEC_LEVEL_160b	160-bit security level.	20	Atoms on Earth
DN_SKEEP_LEVEL_UNKNOWN	Security level not known. Used in DSKeepProbeSecret().	-	-

‍Secrets are slightly smaller than their shares because they don't have the meta information of the M of N scheme.

Parameters

[in]

wAuthType

Type of authentication required by the secret partition. It can be one or a combination of the values below.

Value	Meaning
DN_SKEEP_TYPE_NMIND	It does not limit the type of authentication.
DN_SKEEP_TYPE_SCRD	Partition with M of N authentication.
DN_SKEEP_TYPE_2FA	Partition with authentication OATH.
DN_SKEEP_TYPE_CRT	Partition with X.509 authentication.

[in] dwReserved Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: skeep_new_split_recover.c and 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>

Divides M from N in a secret. According to Shamir's secret sharing pattern.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	cszId	Object identifier in the HSM.
[in]	bSecLevel	Security level. See options in DSKeepNewSecret().
[in]	wAuthType	Type of authentication required by the secret partition. See options in DSKeepNewSecret().
[in]	bM	Minimum number of shares needed to rebuild the secret. It must be greater than or equal to DN_SKEEP_M_OF_N_S_MIN and less than or equal to DN_SKEEP_M_OF_N_S_MAX.
[in]	bN	Number of shares to be generated. Must be greater than or equal to DN_SKEEP_M_OF_N_S_MIN and less than or equal to DN_SKEEP_M_OF_N_S_MAX.
[out]	pstShares	Structure vector SKeepShare which will receive the generated shares. The size of this vector must be `bN` elements. ‍The shares are slightly larger than their corresponding secret because they contain the meta information of the M of N scheme.

Parameters

[in] dwReserved Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: skeep_new_split_recover.c and skeep_probe_match.c.

◆ DSKeepProbeSecret()

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

#include <dinamo.h>

Retrieve information from a secret.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	cszId	Object identifier in the HSM.
[out]	pstInfo	Structure that will receive the secret's information. Receives a SKeepProbeInfo structure.
[in]	dwReserved	Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: skeep_probe_match.c.

◆ DSKeepMatchSecret()

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

#include <dinamo.h>

Checks that the shares of a secret are valid.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	cszId	Object identifier in the HSM.
[in]	cpstShares	Structure vector SKeepShare which contains the shares of the secret. The number of elements in this vector must be entered in `dwSharesCount`. The quantity of this buffer must be the quantity of M parts.
[in]	dwSharesCount	Number of `pstShares`.
[in]	dwReserved	Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: If used with M of N partition authorization, this API can be used without being authorized.

Examples: 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>

Recover a secret from its parts (share).

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	cszId	Object identifier in the HSM.
[in]	cpstShares	Structure vector SKeepShare which contains the shares of the secret. The number of elements in this vector must be entered in `dwSharesCount`. The quantity of this buffer must be the quantity of M parts.
[in]	dwSharesCount	Number of `pstShares`.
[out]	pstRecoverInfo	Structure that will receive the secret information. Receives a SKeepRecoverInfo structure.
[in]	dwReserved	Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: 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 a secret.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	cszId	Object identifier in the HSM.
[in]	bSecLevel	Security level. See options in DSKeepNewSecret().
[in]	wAuthType	Type of authentication required by the secret partition. See options in DSKeepNewSecret().
[in]	dwReserved	Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: skeep_new_split_recover.c and skeep_probe_match.c.

◆ DSKeepCalcShareCks()

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

#include <dinamo.h>

Generates the check value of a share.

Parameters

[in]

dwType

Type of operation. Can be one of the values below.

Value	Meaning
DN_SKEEP_GEN_SHARE_CKS	Generates the check value of a share. It consists of a string of DN_SKEEP_SHARE_CKS_LEN numbers plus the null terminator.

[in] cszShare Buffer containing the share of the secret.

[out] szCks Buffer that will receive the check value. The size of this buffer must be DN_SKEEP_SHARE_CKS_LEN + 1.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: skeep_new_split_recover.c.

Detailed description

Introduction

Architecture

Generating secrecy

Splittingshares of the secret using Shamir's algorithm

Recovery of the secret from the parts generated in the previous step

Use

Settings and Macros

Functions

Definitions and 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

Functions

◆ DSKeepNewSecret()

◆ DSKeepSplitSecret()

◆ DSKeepProbeSecret()

◆ DSKeepMatchSecret()

◆ DSKeepRecoverSecret()

◆ DSKeepRemoveSecret()

◆ DSKeepCalcShareCks()