Detailed description

Management of shared secrets.

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

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