Blockchain Module

Detailed description

Operations to support the security of Blockchain-based structures.

See HSM technical documentation about operating details, specifications used, licenses e module trade name.

Settings and Macros
#define	DN_BCHAIN_CKD_OPT_BIP32_XPRV (1)
#define	DN_BCHAIN_CKD_OPT_BIP32_ED25519_XPRV (2)
#define	DN_BCHAIN_CKD_OPT_BIP32_P256_XPRV (3)

Functions
int AAP_API	DBchainCreateXPrv(HSESSIONCTX hSession, BYTE bType, DWORD dwAttributes, const char *szId, const BYTE *pcbData, DWORD dwDataLen, DWORD dwReserved)
int AAP_API	DBchainCreateBip32Ckd(HSESSIONCTX hSession, BYTE bVersion, DWORD dwIndex, DWORD dwAttributes, const char *cszPar, const char *cszDst, DN_BCHAIN_KEY_INFO *pKeyInfo, DWORD dwReserved)
int AAP_API	DBchainCreateCkd (HSESSIONCTX hSession, DWORD dwOpt, const BYTE *pbIn, BYTE *pbOut, DWORD dwReserved)
int AAP_API	DBchainGetAddress(HSESSIONCTX hSession, BYTE bType, BYTE bVer, const char *cszHrp, const char *cszPk, BYTE *pbAddress, DWORD *pdwAddressLen, DWORD dwReserved)
int AAP_API	DBchainSignHash(HSESSIONCTX hSession, BYTE bType, BYTE bHashMode, BYTE *pbHash, DWORD dwHashLen, const char *cszPk, BYTE *pbSig, DWORD *pdwSigLen, DWORD dwReserved)
int AAP_API	DBchainVerify(HSESSIONCTX hSession, BYTE bSigType, BYTE bHashMode, const BYTE *pbHash, DWORD dwHashLen, const BYTE *pbSig, DWORD dwSigLen, BYTE bInPbkType, const BYTE *pbInPbk, BYTE bInPbkLen, DWORD dwReserved)
int AAP_API	DBchainEdDsaSign(HSESSIONCTX hSession, BYTE bType, const char *cszCtxStr, BYTE *pbData, DWORD dwDataLen, const char *cszPk, BYTE *pbSig, DWORD *pdwSigLen, DWORD dwReserved)
int AAP_API	DBchainEdDsaVerify(HSESSIONCTX hSession, BYTE bType, const char *cszCtxStr, BYTE *pbData, DWORD dwDataLen, BYTE bPbkType, BYTE *pbPbk, DWORD dwPbkLen, BYTE *pbSig, DWORD dwSigLen, DWORD dwReserved)
int AAP_API	DBchainPkImport(HSESSIONCTX hSession, BYTE bFormat, DWORD dwAttributes, const char *cszId, const BYTE *pcbData, DWORD dwDataLen, DWORD dwReserved)
int AAP_API	DBchainPkExport(HSESSIONCTX hSession, BYTE bFormat, BYTE bVersion, BYTE bCompressed, const char *cszId, BYTE **ppbData, DWORD *pdwDataLen, DWORD dwReserved)
int AAP_API	DBchainGetPubKey(HSESSIONCTX hSession, BYTE bType, const char *cszId, BYTE *pbData, DWORD *pdwDataLen, DWORD dwReserved)
int AAP_API	DBchainRecoverPbkFromSignature(HSESSIONCTX hSession, BYTE bSigType, BYTE bHashMode, const BYTE *pbHash, DWORD dwHashLen, const BYTE *pbSig, DWORD dwSigLen, DN_BCHAIN_PBK *pPbk, DWORD dwReserved)
int AAP_API	DBchainGetKeyInfo(HSESSIONCTX hSession, DWORD dwReserved, const char *cszId, void *pvData, DWORD *pdwDataLen)
int AAP_API	DBchainHashData(HSESSIONCTX hSession, BYTE bMode, BYTE *pbData, DWORD dwDataLen, BYTE *pbHash, DWORD *pdwHashLen, DWORD dwReserved)
int AAP_API	DBchainEd2X(HSESSIONCTX hSession, const char *cszPk, const char *cszTo, DWORD dwAttr, DWORD dwReserved)

Definitions and macros

DN_BCHAIN_CKD_OPT_BIP32_XPRV

#define DN_BCHAIN_CKD_OPT_BIP32_XPRV   (1)

#include <dinamo.h>

Child Key Derivation for BIP32 XPrv.

DN_BCHAIN_CKD_OPT_BIP32_ED25519_XPRV

#define DN_BCHAIN_CKD_OPT_BIP32_ED25519_XPRV   (2)

#include <dinamo.h>

Child Key Derivation for BIP32 Ed25519 XPrv.

Examples

ckd_bchain_ed25519.c.

DN_BCHAIN_CKD_OPT_BIP32_P256_XPRV

#define DN_BCHAIN_CKD_OPT_BIP32_P256_XPRV   (3)

#include <dinamo.h>

Child Key Derivation for BIP32 P-256 XPrv.

Functions

DBchainCreateXPrv()

int AAP_API DBchainCreateXPrv	(	HSESSIONCTX	hSession,
		BYTE	bType,
		DWORD	dwAttributes,
		const char *	szId,
		const BYTE *	pcbData,
		DWORD	dwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Creates an Extended Private Key (XPrv) for the blockchain in the BIP32 standard.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Type of key generation. Value Meaning DN_BCHAIN_BTC_MINIKEY Bitcoin minikey. pcbData must be NULL and dwDataLen must be 0. DN_BCHAIN_BIP32_SEED_XPRV BIP32 seed XPrv. pcbData must contain the DN_BCHAIN_BIP32_SEED_XPRV_DATA structure. DN_BCHAIN_BIP39_SEED_XPRV BIP39 seed XPrv. pcbData must contain the DN_BCHAIN_BIP39_SEED_XPRV_DATA structure. DN_BCHAIN_BIP32_XPRV BIP32 XPrv. dwDataLen must be a BYTE containing the key version. See notes for more details. DN_BCHAIN_BIP32_ED25519_XPRV BIP32 Ed25519 XPrv. dwDataLen must be a BYTE containing the key version. See notes for more details. DN_BCHAIN_BIP32_P256_XPRV BIP32 P-256 XPrv. dwDataLen must be a BYTE containing the key version. See notes for more details.
[in]	dwAttributes	Additional key parameters. See the options in the DGenerateKey() function. This API automatically includes the BCHAIN_KEY flag, which is required for blockchain operations.
[in]	szId	Name of the key in the HSM. Must have a maximum length of MAX_OBJ_ID_FQN_LEN.
[in]	pcbData	Buffer containing the data needed to generate the key. The input data must be passed according to the bType option and the size of the data passed here must be specified in dwDataLen.
[in]	dwDataLen	Size of the data passed in pcbData.
[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

Table of version options for the XPrv key.

Value	Meaning
DN_BCHAIN_VER_BIP32_MAINNET	Mainnet BIP32.
DN_BCHAIN_VER_BIP32_TESTNET	Testnet BIP32.
DN_BCHAIN_VER_BIP32_HTR_MAINNET	Mainnet BIP32 Hathor.
DN_BCHAIN_VER_BIP32_HTR_TESTNET	Testnet BIP32 Hathor.
DN_BCHAIN_VER_BIP32_FPRV1	FPRV1 BIP32 Ed25519.

Examples

ckd_bchain.c, ckd_bchain_ed25519.c, get_key_info_bchain.c, get_pub_key_bchain.c, import_export_bchain.c, and sign_verify_bchain.c.

DBchainCreateBip32Ckd()

int AAP_API DBchainCreateBip32Ckd	(	HSESSIONCTX	hSession,
		BYTE	bVersion,
		DWORD	dwIndex,
		DWORD	dwAttributes,
		const char *	cszPar,
		const char *	cszDst,
		DN_BCHAIN_KEY_INFO *	pKeyInfo,
		DWORD	dwReserved )

#include <dinamo.h>

Performs a Child Key Derivation (CKD) operation. Derives an Extended Private Key (XPrv) for the blockchain in the BIP32 standard.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bVersion	Key version. Value Meaning DN_BCHAIN_VER_BIP32_MAINNET Mainnet BIP32. DN_BCHAIN_VER_BIP32_TESTNET Testnet BIP32. DN_BCHAIN_VER_BIP32_HTR_MAINNET Mainnet BIP32 Hathor. DN_BCHAIN_VER_BIP32_HTR_TESTNET Testnet BIP32 Hathor.
[in]	dwIndex	Index of the key to be derived. Non-hardened keys use an index from 0 to 231-1 and hardened (unrestrictedly secure) keys use indexes from 231 to 232-1, as specified in the BIP32 standard. It is highly recommended to generate hardened keys. Use DN_BCHAIN_SECURE_BIP32_INDEX_BASE as the basis for generating hardened indexes (e.g. DN_BCHAIN_SECURE_BIP32_INDEX_BASE + 1 ...).
[in]	dwAttributes	Additional key parameters. See the options in the DGenerateKey() function. This API automatically includes the BCHAIN_KEY flag, which is required for blockchain operations.
[in]	cszPar	Name of the parent key in the HSM. Must have a maximum size of MAX_OBJ_ID_FQN_LEN. Must be an XPrv key(DN_BCHAIN_BIP32_XPRV etc.). See DBchainCreateXPrv().
[in]	cszDst	Name of the key that will be derived in the HSM. It must have a maximum size of MAX_OBJ_ID_FQN_LEN.
[out]	pKeyInfo	Pointer to the DN_BCHAIN_KEY_INFO structure that will contain the information of the generated key.
[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

An attempt to derive a BIP32 private key may fail if the selected index generates an invalid key; in such scenarios, the function may return D_ERR_INVALID_KEY or D_ERR_OPERATION_FAILED, and it is up to the caller to retry using other indexes, according to the policy and key hierarchy defined by the client itself.

Examples

ckd_bchain.c.

DBchainCreateCkd()

int AAP_API DBchainCreateCkd	(	HSESSIONCTX	hSession,
		DWORD	dwOpt,
		const BYTE *	pbIn,
		BYTE *	pbOut,
		DWORD	dwReserved )

#include <dinamo.h>

Performs a Child Key Derivation (CKD) operation. Derives an Extended Private Key (XPrv) for the blockchain.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	dwOpt	Key derivation options. Value Meaning pbIn pbOut DN_BCHAIN_CKD_OPT_BIP32_XPRV Derive a key in the BIP32 standard. DN_BCHAIN_BIP32_CKD_IN_INFO DN_BCHAIN_KEY_INFO DN_BCHAIN_CKD_OPT_BIP32_ED25519_XPRV Derives an ED25519 key in theBIP32/SLIP-0010 standard and variations such as FPRV1. DN_BCHAIN_BIP32_ED25519_CKD_IN_INFO DN_BCHAIN_KEY_INFO DN_BCHAIN_CKD_OPT_BIP32_P256_XPRV Derive a P-256 key in theBIP32/SLIP-0010 standard. DN_BCHAIN_BIP32_P256_CKD_IN_INFO DN_BCHAIN_KEY_INFO
[in]	pbIn	Buffer containing the input structure for key derivation. The structure must be chosen according to the dwOpt option.
[out]	pbOut	Buffer that will receive the output structure with the generated key information. The structure must be chosen according to the dwOpt option.
[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

An attempt to derive a BIP32 private key may fail if the selected index generates an invalid key; in such scenarios, the function may return D_ERR_INVALID_KEY or D_ERR_OPERATION_FAILED, and it is up to the caller to retry using other indexes, according to the policy and key hierarchy defined by the client itself. In the case of SLIP-0010, although failure is also possible (albeit highly unlikely), the algorithm automatically performs these internal retries and, if it is not possible to obtain a valid key, it will also return one of these errors.

Examples

ckd_bchain_ed25519.c.

DBchainGetAddress()

int AAP_API DBchainGetAddress	(	HSESSIONCTX	hSession,
		BYTE	bType,
		BYTE	bVer,
		const char *	cszHrp,
		const char *	cszPk,
		BYTE *	pbAddress,
		DWORD *	pdwAddressLen,
		DWORD	dwReserved )

#include <dinamo.h>

Retrieves the address of a key using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Type of address to be generated. It can be one of the values below. Value Meaning DN_BCHAIN_AT_BTC_P2PKH P2PKH address. bVer must be DN_BCHAIN_VER_BTC_A1_MAIN_NET, DN_BCHAIN_VER_BTC_A3_MAIN_NET, DN_BCHAIN_VER_BTC_AMN_TEST_NET, DN_BCHAIN_VER_HTR_MAINNET or DN_BCHAIN_VER_HTR_TESTNET. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_BTC_P2SH P2SH address BIP13. bVer must be DN_BCHAIN_VER_BTC_A1_MAIN_NET, DN_BCHAIN_VER_BTC_A3_MAIN_NET, DN_BCHAIN_VER_BTC_AMN_TEST_NET, DN_BCHAIN_VER_HTR_MAINNET or DN_BCHAIN_VER_HTR_TESTNET. cszHrp must be DN_BCHAIN_HRP_UNUSED. cszPk must be the script-hash. DN_BCHAIN_AT_BTC_P2WPKH Address Address BIP173, version 0. bVer must be DN_BCHAIN_VER_BTC_B32_WITVER. cszHrp can be DN_BCHAIN_HRP_BTC_MAIN_NET or DN_BCHAIN_HRP_BTC_TEST_NET. DN_BCHAIN_AT_BTC_P2WSH Address Address BIP173, version 0. bVer must be DN_BCHAIN_VER_BTC_A1_MAIN_NET, DN_BCHAIN_VER_BTC_A3_MAIN_NET, DN_BCHAIN_VER_BTC_AMN_TEST_NET, DN_BCHAIN_VER_HTR_MAINNET, or DN_BCHAIN_VER_HTR_TESTNET. cszHrp must be DN_BCHAIN_HRP_UNUSED. cszPk must be the script-hash. DN_BCHAIN_AT_ETH_EOA ETH EOA address. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_ETH_EOA_MC_CKS Address ETH EOA MC CKS. EIP55. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_ETH_EOA_ICAP ETH EOA ICAP address. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_ALGORAND Algorand address. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_TRON_HEX Hexadecimal TRON address. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_TRON_B58 TRON Base 58 address. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_XRP XRP Ledger/Ripple address. bVer must be DN_BCHAIN_VER_XRP_CLASSIC. cszHrp must be DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_SOL Solana address. bVer must be DN_BCHAIN_VER_UNUSED. cszHrp must be DN_BCHAIN_HRP_UNUSED.

DN_BCHAIN_AT_XLM | Endereço Stellar SEP-23.

bVer deve ser DN_BCHAIN_VER_UNUSED.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_ADA_PKH | Endereço Cardano CIP-0019, Shelley, Header type: 0110 (6).

bVer deve ser DN_BCHAIN_VER_ADA_MAINNET ou DN_BCHAIN_VER_ADA_TESTNET.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_ADA_SH | Endereço Cardano CIP-0019, Shelley, Header type: 0111 (7).

bVer deve ser DN_BCHAIN_VER_ADA_MAINNET ou DN_BCHAIN_VER_ADA_TESTNET.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED.
cszPk deve ser o script-hash. DN_BCHAIN_AT_LUNC | Endereço Terra Classic.

bVer deve ser DN_BCHAIN_VER_UNUSED.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_SS58 | Endereço SS58.

bVer deve ser DN_BCHAIN_VER_SS58_POLKADOT ou DN_BCHAIN_VER_SS58_GEN_SUBST.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_XTZ | Endereço Tezos.

bVer deve ser DN_BCHAIN_VER_UNUSED.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_TON | Endereço Toncoin TEP-2.

bVer deve ser DN_BCHAIN_VER_TON_MN_BWORK, DN_BCHAIN_VER_TON_MN_MCHAIN, DN_BCHAIN_VER_TON_TN_BWORK ou DN_BCHAIN_VER_TON_TN_MCHAIN.
cszHrp deve ser DN_BCHAIN_HRP_TON_BNCBLE ou DN_BCHAIN_HRP_TON_NBNCBLE. DN_BCHAIN_AT_TON_SH | Endereço Toncoin TEP-2 SH.

bVer deve ser DN_BCHAIN_VER_TON_MN_BWORK, DN_BCHAIN_VER_TON_MN_MCHAIN, DN_BCHAIN_VER_TON_TN_BWORK ou DN_BCHAIN_VER_TON_TN_MCHAIN.
cszHrp deve ser DN_BCHAIN_HRP_TON_BNCBLE ou DN_BCHAIN_HRP_TON_NBNCBLE.
cszPk deve ser o script-hash. DN_BCHAIN_AT_ATOM | Endereço Atom ADR-028.

bVer deve ser DN_BCHAIN_VER_UNUSED.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_BTC_P2TR | Endereço BTC BIP350, version 1-16.

bVer deve ser DN_BCHAIN_VER_BTC_SEGWIT1 ou DN_BCHAIN_VER_LTC_SEGWIT1.
cszHrp deve ser DN_BCHAIN_HRP_BTC_MAIN_NET, DN_BCHAIN_HRP_BTC_TEST_NET, DN_BCHAIN_HRP_LTC_MAINNET ou DN_BCHAIN_HRP_LTC_TESTNET. DN_BCHAIN_AT_LTC_P2PKH | Endereço LTC P2PKH.

bVer deve ser DN_BCHAIN_VER_BTC_A1_MAIN_NET, DN_BCHAIN_VER_BTC_A3_MAIN_NET, DN_BCHAIN_VER_BTC_AMN_TEST_NET, DN_BCHAIN_VER_HTR_MAINNET ou DN_BCHAIN_VER_HTR_TESTNET.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED. DN_BCHAIN_AT_LTC_P2SH | Endereço LTC P2SH BIP13.

bVer deve ser DN_BCHAIN_VER_BTC_A1_MAIN_NET, DN_BCHAIN_VER_BTC_A3_MAIN_NET, DN_BCHAIN_VER_BTC_AMN_TEST_NET, DN_BCHAIN_VER_HTR_MAINNET ou DN_BCHAIN_VER_HTR_TESTNET.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED.
cszPk deve ser o script-hash. DN_BCHAIN_AT_LTC_P2WPKH | Endereço LTC P2WPKH BIP173.

bVer deve ser DN_BCHAIN_VER_BTC_B32_WITVER.
cszHrp pode ser DN_BCHAIN_HRP_BTC_MAIN_NET ou DN_BCHAIN_HRP_BTC_TEST_NET. DN_BCHAIN_AT_LTC_P2WSH | Endereço LTC P2WSH BIP173.

bVer deve ser DN_BCHAIN_VER_BTC_A1_MAIN_NET, DN_BCHAIN_VER_BTC_A3_MAIN_NET, DN_BCHAIN_VER_BTC_AMN_TEST_NET, DN_BCHAIN_VER_HTR_MAINNET ou DN_BCHAIN_VER_HTR_TESTNET.
cszHrp deve ser DN_BCHAIN_HRP_UNUSED.
cszPk deve ser o script-hash. DN_BCHAIN_AT_LTC_P2TR | Endereço LTC BIP350, version 1-16.

bVer deve ser DN_BCHAIN_VER_BTC_SEGWIT1 ou DN_BCHAIN_VER_LTC_SEGWIT1.
cszHrp deve ser DN_BCHAIN_HRP_BTC_MAIN_NET, DN_BCHAIN_HRP_BTC_TEST_NET, DN_BCHAIN_HRP_LTC_MAINNET ou DN_BCHAIN_HRP_LTC_TESTNET.

Parameters

[in]	bVer	Address version. Value Meaning DN_BCHAIN_VER_UNUSED Parameter not used. DN_BCHAIN_VER_BTC_A1_MAIN_NET Bitcoin A1 mainnet. DN_BCHAIN_VER_BTC_AMN_TEST_NET Bitcoin P2PKH testnet. DN_BCHAIN_VER_BTC_A3_MAIN_NET Bitcoin A3 mainnet. DN_BCHAIN_VER_BTC_B32_WITVER Bitcoin B32 witver. DN_BCHAIN_VER_BTC_SEGWIT0 Bitcoin SEGWIT0 DN_BCHAIN_VER_BTC_SEGWIT1 Bitcoin SEGWIT1 DN_BCHAIN_VER_HTR_MAINNET Hathor mainnet. DN_BCHAIN_VER_HTR_TESTNET Hathor testnet. DN_BCHAIN_VER_HTR_P2SH_MAINNET Hathor P2SH mainnet. DN_BCHAIN_VER_HTR_P2SH_TESTNET Hathor P2SH testnet. DN_BCHAIN_VER_XRP_CLASSIC XRP Ledger/Ripple Classic. DN_BCHAIN_VER_LTC_SEGWIT0 Litecoin SEGWIT0 DN_BCHAIN_VER_LTC_SEGWIT1 Litecoin SEGWIT1 DN_BCHAIN_VER_LTC_AL_MAINNET Litecoin AL mainnet. DN_BCHAIN_VER_LTC_Amn_TESTNET Litecoin Amn testnet. DN_BCHAIN_VER_LTC_AM_MAINNET Litecoin AM mainnet. DN_BCHAIN_VER_LTC_AQ_TESTNET Litecoin AQ testnet. DN_BCHAIN_VER_ADA_MAINNET Cardano mainnet. DN_BCHAIN_VER_ADA_TESTNET Cardano testnet. DN_BCHAIN_VER_SS58_POLKADOT Polkadot SS58. DN_BCHAIN_VER_SS58_GEN_SUBST Generic Substrate SS58. DN_BCHAIN_VER_TON_MN_BWORK Toncoin wallet v4r2; mainnet; basic workchain. DN_BCHAIN_VER_TON_MN_MCHAIN Toncoin wallet v4r2; mainnet; masterchain. DN_BCHAIN_VER_TON_TN_BWORK Toncoin wallet v4r2; testnet; basic workchain. DN_BCHAIN_VER_TON_TN_MCHAIN Toncoin wallet v4r2; testnet; masterchain.
[in]	cszHrp	HRP (Human Readable Part) of the key. The values in the table are accepted. It must have a maximum size of DN_BCHAIN_MAX_HRP. Value Meaning DN_BCHAIN_HRP_UNUSED Parameter not used. DN_BCHAIN_HRP_BTC_MAIN_NET Bitcoin mainnet. DN_BCHAIN_HRP_BTC_TEST_NET Bitcoin testnet. DN_BCHAIN_HRP_LTC_MAINNET Litecoin mainnet. DN_BCHAIN_HRP_LTC_TESTNET Litecoin testnet. DN_BCHAIN_HRP_TON_BNCBLE Toncoin bounceable. DN_BCHAIN_HRP_TON_NBNCBLE Toncoin non-bounceable.
[in]	cszPk	Private key that will generate the address or the script-hash. If using script-hash pass a buffer of size MAX_OBJ_ID_FQN_LEN with script-hash with zero padding.
[in,out]	pbAddress	Buffer that will receive the address. It can be NULL to obtain the required size. It is recommended to use the maximum size of DN_BCHAIN_MAX_ADDR_LEN.
[in,out]	pdwAddressLen	Size of the pbAddress buffer. If the pbAddress buffer is NULL, this parameter will be assigned the required size.
[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

ckd_bchain.c and ckd_bchain_ed25519.c.

DBchainSignHash()

int AAP_API DBchainSignHash	(	HSESSIONCTX	hSession,
		BYTE	bType,
		BYTE	bHashMode,
		BYTE *	pbHash,
		DWORD	dwHashLen,
		const char *	cszPk,
		BYTE *	pbSig,
		DWORD *	pdwSigLen,
		DWORD	dwReserved )

#include <dinamo.h>

Sign a hash using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Type of subscription to be generated. It can be one of the values below. Value Meaning DN_BCHAIN_SIG_DER_ECDSA DER signature, in the format v || DER. SECG!SEC1 strict DER with low S as described in BIP62/66, BIP146, EIP2. With 'v' having a size of 1 byte. 'v' is the parity bit of 'r' and can have the values 0 or 1. DN_BCHAIN_SIG_RAW_ECDSA RAW signature, in the format v || r || s. With 'v' having a size of 1 byte and 'r' and 's' each having a size of 32 bytes. 'v' is the parity bit of 'r' and can have the values 0 or 1. DN_BCHAIN_SIG_BIP340 Signature BIP340 - Schnorr 64 bytes. DN_BCHAIN_DER_RFC_6979_ECDSA RFC-6979 standard deterministic ECDSA signature. DER type in the format v || DER, with 'v' having a size of 1 byte. 'v' is the parity bit of 'r' and can have the values 0 or 1 DN_BCHAIN_RAW_RFC_6979_ECDSA RFC-6979 standard deterministic ECDSA signature. RAW type in the format v || r || s, with 'v' having a size of 1 byte and 'r' and 's' each having a size of 32 bytes. 'v' is the parity bit of 'r' and can have the values 0 or 1.
[in]	bHashMode	Hash type. Value Meaning DN_BCHAIN_HASH_BTC_H160 Bitcoin H160. DN_BCHAIN_HASH_RIPEMD160 RIPEMD160. DN_BCHAIN_HASH_SHA256 SHA256 DN_BCHAIN_HASH_BTC_SHA256_2X Bitcoin SHA256 2x. DN_BCHAIN_HASH_KECCAK256 KECCAK256. DN_BCHAIN_HASH_BLAKE2B224 Blake2b 224. DN_BCHAIN_HASH_BLAKE2B256 Blake2b 256.
[in]	pbHash	Hash calculated according to the information in bHashMode.
[in]	dwHashLen	Hash size entered in pbHash.
[in]	cszPk	Name of the private key.
[in,out]	pbSig	Buffer that will receive the signature.Can be NULL to obtain the required size.It is recommended to use the maximum size of DN_BCHAIN_MAX_SIG_LEN.
[in,out]	pdwSigLen	Size of the pbSig buffer.If the pbSig buffer is NULL, this parameter will be assigned the required size.
[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

sign_verify_bchain.c.

DBchainVerify()

int AAP_API DBchainVerify	(	HSESSIONCTX	hSession,
		BYTE	bSigType,
		BYTE	bHashMode,
		const BYTE *	pbHash,
		DWORD	dwHashLen,
		const BYTE *	pbSig,
		DWORD	dwSigLen,
		BYTE	bInPbkType,
		const BYTE *	pbInPbk,
		BYTE	bInPbkLen,
		DWORD	dwReserved )

#include <dinamo.h>

Verifies a signature using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bSigType	Type of subscription to be generated. It can be one of the values below. Value Meaning DN_BCHAIN_SIG_DER_ECDSA DER signature, in the format v || DER. SECG!SEC1 strict DER with low S as described in BIP62/66, BIP146, EIP2. With 'v' having a size of 1 byte. 'v' is the parity bit of 'r' and can have the values 0 or 1. DN_BCHAIN_SIG_RAW_ECDSA RAW signature, in the format v || r || s. With 'v' having a size of 1 byte and 'r' and 's' each having a size of 32 bytes. 'v' is the parity bit of 'r' and can have the values 0 or 1. DN_BCHAIN_SIG_BIP340 Signature BIP340 - Schnorr 64 bytes.
[in]	bHashMode	Hash type. Value Meaning DN_BCHAIN_HASH_BTC_H160 Bitcoin H160. DN_BCHAIN_HASH_RIPEMD160 RIPEMD160. DN_BCHAIN_HASH_SHA256 SHA256 DN_BCHAIN_HASH_BTC_SHA256_2X Bitcoin SHA256 2x. DN_BCHAIN_HASH_KECCAK256 KECCAK256. DN_BCHAIN_HASH_BLAKE2B224 Blake2b 224. DN_BCHAIN_HASH_BLAKE2B256 Blake2b 256.
[in]	pbHash	Hash calculated according to the information in bHashMode.
[in]	dwHashLen	Hash size entered in pbHash.
[in]	pbSig	Signature according to the information in bSigType.
[in]	dwSigLen	Size of the signature entered in pbSig.
[in]	bInPbkType	Public key format. Can be one of the values below. Value Meaning DN_BCHAIN_PBK_SEC1_UNCOMP ECDSA SEC1 uncompressed. DN_BCHAIN_PBK_SEC1_COMP ECDSA SEC1 compressed. DN_BCHAIN_PBK_BIP340 Schnorr, BIP-340. DN_BCHAIN_PBK_ED25519 Ed25519.
[in]	pbInPbk	Signature according to bInPbkType.
[in]	bInPbkLen	Size of the signature entered in pbInPbk.
[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

sign_verify_bchain.c.

DBchainEdDsaSign()

int AAP_API DBchainEdDsaSign	(	HSESSIONCTX	hSession,
		BYTE	bType,
		const char *	cszCtxStr,
		BYTE *	pbData,
		DWORD	dwDataLen,
		const char *	cszPk,
		BYTE *	pbSig,
		DWORD *	pdwSigLen,
		DWORD	dwReserved )

#include <dinamo.h>

Generates an EdDsa signature using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Type of subscription to be generated. It can be one of the values below. Value Meaning DN_BCHAIN_EDDSA_SIG_PURE EdDsa Pure Signature. DN_BCHAIN_EDDSA_SIG_ALGORAND EdDsa Algorand Signature. DN_BCHAIN_EDDSA_SIG_XRP EdDsa XRP subscription. DN_BCHAIN_EDDSA_SIG_SOL Signature EdDsa Solana. DN_BCHAIN_EdDSA_SIG_XLM EdDsa Stellar signature. DN_BCHAIN_EdDSA_SIG_ADA EdDsa Cardano signature. DN_BCHAIN_EdDSA_SIG_DOT EdDsa Polkadot signature. DN_BCHAIN_EdDSA_SIG_XTZ EdDsa Tezos signature encoded in b58. DN_BCHAIN_EdDSA_SIG_XTZ_PH EdDsa Tezos signature (same as DN_BCHAIN_EdDSA_SIG_XTZ), using blake2b-256 as data.
[in]	cszCtxStr	Context string as defined in RFC-8032 . Can be passed DN_BCHAIN_EDDSA_CSTR_UNUSED.
[in]	pbData	Data to be signed.
[in]	dwDataLen	Size of the data to be signed.
[in]	cszPk	Name of the private key.
[in,out]	pbSig	Buffer that will receive the signature. It can be NULL to obtain the required size. It is recommended to use the maximum size of DN_BCHAIN_MAX_SIG_LEN.
[in,out]	pdwSigLen	Size of the pbSig buffer. If the pbSig buffer is NULL, this parameter will be assigned the required size.
[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.

DBchainEdDsaVerify()

int AAP_API DBchainEdDsaVerify	(	HSESSIONCTX	hSession,
		BYTE	bType,
		const char *	cszCtxStr,
		BYTE *	pbData,
		DWORD	dwDataLen,
		BYTE	bPbkType,
		BYTE *	pbPbk,
		DWORD	dwPbkLen,
		BYTE *	pbSig,
		DWORD	dwSigLen,
		DWORD	dwReserved )

#include <dinamo.h>

Verifies an EdDsa signature using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Type of signature to be verified. It can be one of the values below. Value Meaning DN_BCHAIN_EDDSA_SIG_PURE EdDsa Pure Signature. DN_BCHAIN_EDDSA_SIG_ALGORAND EdDsa Algorand Signature. DN_BCHAIN_EDDSA_SIG_XRP EdDsa XRP subscription. DN_BCHAIN_EDDSA_SIG_SOL Signature EdDsa Solana. DN_BCHAIN_EdDSA_SIG_XLM EdDsa Stellar signature. DN_BCHAIN_EdDSA_SIG_ADA EdDsa Cardano signature. DN_BCHAIN_EdDSA_SIG_DOT EdDsa Polkadot signature. DN_BCHAIN_EdDSA_SIG_XTZ EdDsa Tezos signature encoded in b58. DN_BCHAIN_EdDSA_SIG_XTZ_PH EdDsa Tezos signature (same as DN_BCHAIN_EdDSA_SIG_XTZ), using blake2b-256 as data.
[in]	cszCtxStr	Context string as defined in RFC-8032 of maximum length DN_BCHAIN_EDDSA_MAX_CSTRL. Can be passed DN_BCHAIN_EDDSA_CSTR_UNUSED.
[in]	pbData	Data to be verified.
[in]	dwDataLen	Size of the data to be checked.
[in]	bPbkType	Public key format. Can be one of the values below. Value Meaning DN_BCHAIN_PBK_ED25519 Ed25519. DN_BCHAIN_PBK_AT_ALGORAND Algorand. DN_BCHAIN_PBK_BIP32_XPUB BIP32 XPub. DN_BCHAIN_PBK_AT_SOL Solana. DN_BCHAIN_PBK_AT_XLM Stellar Lumens. DN_BCHAIN_PBK_ADA_VK Cardano CIP-0016 / CIP-0005; DN_BCHAIN_PBK_AT_SS58 SS58. DN_BCHAIN_PBK_TON TEP-2 "User-friendly"/"armored."
[in]	pbPbk	Public key used for verification.
[in]	dwPbkLen	Size of the public key.
[in]	pbSig	Signature to be verified.
[in]	dwSigLen	Signature size.
[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.

DBchainPkImport()

int AAP_API DBchainPkImport	(	HSESSIONCTX	hSession,
		BYTE	bFormat,
		DWORD	dwAttributes,
		const char *	cszId,
		const BYTE *	pcbData,
		DWORD	dwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Import a private key using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bFormat	Format of the key to be imported. Can be one of the values below. Value Meaning DN_BCHAIN_KEY_WIF Wallet Import Format (WIF). DN_BCHAIN_KEY_MINI Bitcoin minikey. DN_BCHAIN_KEY_HEX Private key scale in hexadecimal. Imported as a key of type ALG_ECC_SECP256K1. DN_BCHAIN_KEY_SEC1 SEC1. DN_BCHAIN_KEY_XPRIV XPriv. DN_BCHAIN_KEY_ED25519_B64 Ed25519 in Base 64 format. DN_BCHAIN_KEY_ED25519_XPRIV Ed25519 in XPriv format. DN_BCHAIN_KEY_Ed25519_SKPK Ed25519 in SEP-23 format. DN_BCHAIN_KEY_Ed25519_SK Ed25519 in CIP-0016/CIP-0005 format. DN_BCHAIN_KEY_Ed25519_XTZ Ed25519 in Tezos format. DN_BCHAIN_KEY_P256_XPRIV P-256 in XPriv format.
[in]	dwAttributes	Additional key parameters. See the options in the DGenerateKey() function. This API automatically includes the BCHAIN_KEY flag, which is required for blockchain operations.
[in]	cszId	Name of the private key.
[in]	pcbData	Private key in the format specified in bFormat. The size of this buffer must be entered in dwDataLen.
[in]	dwDataLen	Size of the pcbData buffer.
[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

import_export_bchain.c.

DBchainPkExport()

int AAP_API DBchainPkExport	(	HSESSIONCTX	hSession,
		BYTE	bFormat,
		BYTE	bVersion,
		BYTE	bCompressed,
		const char *	cszId,
		BYTE **	ppbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Export a private key using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bFormat	Format of the key to be exported. Can be one of the values below. Value Meaning DN_BCHAIN_KEY_WIF Wallet Import Format (WIF). bVersion can be DN_BCHAIN_VER_WIF_MAIN_NET or DN_BCHAIN_VER_WIF_TEST_NET. DN_BCHAIN_KEY_MINI Bitcoin minikey. bVersion must be DN_BCHAIN_VER_UNUSED. DN_BCHAIN_KEY_HEX Private key scale in hexadecimal. bVersion must be DN_BCHAIN_VER_UNUSED. DN_BCHAIN_KEY_SEC1 SEC1. bVersion must be DN_BCHAIN_VER_UNUSED. DN_BCHAIN_KEY_XPRIV XPriv. bVersion must be DN_BCHAIN_VER_UNUSED. DN_BCHAIN_KEY_ED25519_B64 Ed25519 in Base 64 format. bVersion must be DN_BCHAIN_VER_UNUSED and the bCompressed parameter is ignored. DN_BCHAIN_KEY_ED25519_XPRIV Ed25519 in XPriv format. bVersion must be DN_BCHAIN_VER_UNUSED and the bCompressed parameter is ignored. DN_BCHAIN_KEY_Ed25519_SKPK Ed25519 in SEP-23 format. bVersion must be DN_BCHAIN_VER_UNUSED and the bCompressed parameter is ignored. DN_BCHAIN_KEY_Ed25519_SK Ed25519 in CIP-0016/CIP-0005 format. bVersion must be DN_BCHAIN_VER_UNUSED, and the bCompressed parameter is ignored. DN_BCHAIN_KEY_Ed25519_XTZ Ed25519 in Tezos format. bVersion must be DN_BCHAIN_VER_UNUSED and the bCompressed parameter is ignored. DN_BCHAIN_KEY_P256_XPRIV P-256 in XPriv format. bVersion must be DN_BCHAIN_VER_UNUSED.
[in]	bVersion	Key version. Value Meaning DN_BCHAIN_VER_UNUSED Parameter not used. DN_BCHAIN_VER_WIF_MAIN_NET WIF main net. DN_BCHAIN_VER_WIF_TEST_NET WIF test net. DN_BCHAIN_VER_WIF_LTC_MAINNET WIF LTC main net.
[in]	bCompressed	0 to export the key in uncompressed format and 1 for compressed format.
[in]	cszId	Name of the private key.
[out]	ppbData	Private key. The size of this buffer will be entered in pdwDataLen. This buffer must be freed with the DFree() API.
[out]	pdwDataLen	Size of the ppcbData buffer.
[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

import_export_bchain.c.

DBchainGetPubKey()

int AAP_API DBchainGetPubKey	(	HSESSIONCTX	hSession,
		BYTE	bType,
		const char *	cszId,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Recover a public key from a private key using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bType	Format of the public key to be exported. Can be one of the values below. Value Meaning DN_BCHAIN_PBK_SEC1_UNCOMP ECDSA SEC1 uncompressed. DN_BCHAIN_PBK_SEC1_COMP ECDSA SEC1 compressed. DN_BCHAIN_PBK_BIP340 Schnorr, BIP-340. DN_BCHAIN_PBK_ED25519 Ed25519. DN_BCHAIN_PBK_AT_ALGORAND Algorand. DN_BCHAIN_PBK_BIP32_XPUB BIP32 XPub. DN_BCHAIN_PBK_AT_SOL Solana. DN_BCHAIN_PBK_AT_XLM Stellar Lumens. DN_BCHAIN_PBK_ADA_VK Cardano CIP-0016 / CIP-0005. DN_BCHAIN_PBK_AT_SS58 SS58. DN_BCHAIN_PBK_TON TEP-2 "User-friendly"/"armored." DN_BCHAIN_PBK_E_UNCOMP | SEC1_UNCOMP without the 0x04 prefix (X || Y). Only alt_bn128 (EIPs 196/197).
[in]	cszId	Name of the private key.
[out]	pbData	Public key. NULL can be passed to receive the expected size in pdwDataLen. The maximum size of this buffer is DN_BCHAIN_MAX_PBK_LEN.
[in,out]	pdwDataLen	Size of the pcbData buffer. Will contain, at the end of the call, the amount of data written to pcbData.
[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

get_pub_key_bchain.c.

DBchainRecoverPbkFromSignature()

int AAP_API DBchainRecoverPbkFromSignature	(	HSESSIONCTX	hSession,
		BYTE	bSigType,
		BYTE	bHashMode,
		const BYTE *	pbHash,
		DWORD	dwHashLen,
		const BYTE *	pbSig,
		DWORD	dwSigLen,
		DN_BCHAIN_PBK *	pPbk,
		DWORD	dwReserved )

#include <dinamo.h>

Retrieves a public key (PBK) from an ECDSA-type signature.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bSigType	Type of subscription to be generated. It can be one of the values below. Value Meaning DN_BCHAIN_SIG_DER_ECDSA DER signature, in the format v || DER. SECG!SEC1 strict DER with low S as described in BIP62/66, BIP146, EIP2. With 'v' having a size of 1 byte. 'v' is the parity bit of 'r' and can have the values 0 or 1. DN_BCHAIN_SIG_RAW_ECDSA RAW signature, in the format v || r || s. With 'v' having a size of 1 byte and 'r' and 's' each having a size of 32 bytes. 'v' is the parity bit of 'r' and can have the values 0 or 1.
[in]	bHashMode	Hash type. Value Meaning DN_BCHAIN_HASH_BTC_H160 Bitcoin H160. DN_BCHAIN_HASH_RIPEMD160 RIPEMD160. DN_BCHAIN_HASH_SHA256 SHA256 DN_BCHAIN_HASH_BTC_SHA256_2X Bitcoin SHA256 2x. DN_BCHAIN_HASH_KECCAK256 KECCAK256. DN_BCHAIN_HASH_BLAKE2B224 Blake2b 224. DN_BCHAIN_HASH_BLAKE2B256 Blake2b 256.
[in]	pbHash	Hash calculated according to the information in bHashMode.
[in]	dwHashLen	Hash size entered in pbHash.
[in]	pbSig	Signature according to the information in bSigType.
[in]	dwSigLen	Size of the signature entered in pbSig.
[out]	pPbk	Public key to be retrieved. Enter a structure of type DN_BCHAIN_PBK.
[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

sign_verify_bchain.c.

DBchainGetKeyInfo()

int AAP_API DBchainGetKeyInfo	(	HSESSIONCTX	hSession,
		DWORD	dwReserved,
		const char *	cszId,
		void *	pvData,
		DWORD *	pdwDataLen )

#include <dinamo.h>

Retrieves the properties of a key using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	dwReserved	Reserved for future use (must be 0).
[in]	cszId	Name of the private key.
[out]	pvData	Key properties. Receives a DN_BCHAIN_KEY_INFO structure. Can be passed NULL to receive the expected size in pdwDataLen.
[in,out]	pdwDataLen	Size of the pcbData buffer. Will contain, at the end of the call, the amount of data written to pcbData.

Return

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

Examples

get_key_info_bchain.c.

DBchainHashData()

int AAP_API DBchainHashData	(	HSESSIONCTX	hSession,
		BYTE	bMode,
		BYTE *	pbData,
		DWORD	dwDataLen,
		BYTE *	pbHash,
		DWORD *	pdwHashLen,
		DWORD	dwReserved )

#include <dinamo.h>

Calculates a hash using the blockchain module.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bMode	Hash type. Value Meaning DN_BCHAIN_HASH_BTC_H160 Bitcoin H160. DN_BCHAIN_HASH_RIPEMD160 RIPEMD160. DN_BCHAIN_HASH_SHA256 SHA256 DN_BCHAIN_HASH_BTC_SHA256_2X Bitcoin SHA256 2x. DN_BCHAIN_HASH_KECCAK256 KECCAK256. DN_BCHAIN_HASH_BLAKE2B224 Blake2b 224. DN_BCHAIN_HASH_BLAKE2B256 Blake2b 256.
[in]	pbData	Data to be processed. The size of this buffer must be entered in dwDataLen. Maximum size of DN_BCHAIN_MAX_HDATA_LEN.
[in]	dwDataLen	Buffer size pbData.
[out]	pbHash	Receives the calculated hash. Can be passed NULL to get the expected size in pdwHashLen.
[in,out]	pdwHashLen	Size of the pbHash buffer. At the end of the call, it will contain the amount of data written to pbHash.
[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

This API is available for implementation validation. We recommend generating the hash by software for better performance and better use of HSM resources.

Examples

sign_verify_bchain.c.

DBchainEd2X()

int AAP_API DBchainEd2X	(	HSESSIONCTX	hSession,
		const char *	cszPk,
		const char *	cszTo,
		DWORD	dwAttr,
		DWORD	dwReserved )

#include <dinamo.h>

Converts an Edwards (Ed) key to Montgomery (x) format. Currently converts Ed25519 keys to X25519.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	cszPk	Name of the private key in Edwards format that exists in the HSM.
[in]	cszTo	Name of the private key in Montgomery format that will be created in the HSM.
[in]	dwAttr	Key attributes. See dwAttr in DGenerateKey() for details on key attributes. The attributes are added to the current attributes of the cszPk source key.
[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.

Observation

Keys must be marked with the BCHAIN_KEY flag to be converted.