Detailed description

Encode and Decode operations according to the SPB standard.

Functions
int AAP_API	DSPBEncodeInit (HSESSIONCTX hSession, char szSrcISPB, char szDstISPB, DWORD dwTotalDataLen, BYTE bErrorCode, BYTE bSpecialTreatment, HSPBCTX *hSPBCtx, DWORD dwFlags)

int AAP_API	DSPBEncodeCont (HSPBCTX hSPBCtx, BYTE pbDataIn, DWORD dwDataInLen, BYTE pbDataOut, DWORD *pdwDataOutLen)

int AAP_API	DSPBEncodeEnd (HSPBCTX hSPBCtx, BYTE pbSPBHeader, DWORD *pdwSPBHeaderLen)

int AAP_API	DSPBDecodeInit (HSESSIONCTX hSession, char szSrcISPB, char szDstISPB, BYTE pbHeader, DWORD dwHeaderLen, BYTE bAcceptExpiredCert, BYTE bAutoUpdateCert, DWORD dwMessageDataLen, HSPBCTX hSPBCtx, DWORD dwFlags)

int AAP_API	DSPBDecodeCont (HSPBCTX hSPBCtx, BYTE pbDataIn, DWORD dwDataInLen, BYTE ppbDataOut, DWORD pdwDataOutLen)

int AAP_API	DSPBDecodeEnd (HSPBCTX *hSPBCtx)

int AAP_API	DSPBGenerateKey (HSESSIONCTX hSession, char szID, char szPrivateKeyName, DWORD dwKeyParam, DWORD dwParam)

int AAP_API	DSPBGenerateCSR (HSESSIONCTX hSession, char szPrivateKeyName, BYTE bVersion, char szSPBSubject, DWORD dwOutType, DWORD pdwCSRLen, BYTE *ppbCSR, DWORD dwParam)

int AAP_API	DSPBImportCertificate (HSESSIONCTX hSession, BYTE bActivate, const char szUser, BYTE pbCertificate, DWORD dwCertificateLen, const char *szDomain, DWORD dwParam)

int AAP_API	DSPBImportPKCS12 (HSESSIONCTX hSession, BYTE bActivate, const char szUser, const char szPkcs12File, const char szPkcs12Pwd, const char szDomain, DWORD dwKeyAttr)

int AAP_API	DSPBExportPKCS12 (const HSESSIONCTX hSession, const char szPkcs12Pwd, const char szISPB, const char szReserved, BYTE ppbPkcs12, DWORD pdwPkcs12Len, DWORD dwReserved)

int AAP_API	DSPBActivateCertificate (HSESSIONCTX hSession, const char szIdCert, const char szDomain, DWORD dwParam)

int AAP_API	DSPBGetCertificate (HSESSIONCTX hSession, const char szIdCert, BYTE ppbCertificate, DWORD pdwCertificateLen, DWORD dwParam)

int AAP_API	DSPBCalculateObjectId (char szISPB, char szDomain, DWORD dwKeyType, char *szOutObjName, DWORD dwParam)

int AAP_API	DSPBMapInfo (HSESSIONCTX hSession, const char szIdCert, EXT_MAP_2_OBJ_INFO pstExtMap, DWORD dwParam)

int AAP_API	DSPBSetISPBMap (HSESSIONCTX hSession, char szISPB, char szKeyId, char *szCertId, DWORD dwParam)

Functions

◆ DSPBEncodeInit()

int AAP_API DSPBEncodeInit	(	HSESSIONCTX	hSession,
		char *	szSrcISPB,
		char *	szDstISPB,
		DWORD	dwTotalDataLen,
		BYTE	bErrorCode,
		BYTE	bSpecialTreatment,
		HSPBCTX *	hSPBCtx,
		DWORD	dwFlags )

#include <dinamo.h>

Starts an SPB message encoding operation.

Parameters

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

[in] szSrcISPB Source institution identifier with maximum size MAX_OBJ_ID_FQN_LEN.
The source identifier must have the following format: ISPB@DOMINIO, with the domain part being optional.
The exact size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN.
Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN.
The name of the corresponding map, outside the SPB module naming standard, can also be passed on in specific cases, see dwFlags.

[in] szDstISPB Destination institution identifier maximum size MAX_OBJ_ID_FQN_LEN.
The destination identifier must have the following format: ISPB@DOMINIO, with the domain part being optional.
The size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN.
Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN.
The name of the corresponding map, outside the SPB module naming standard, can also be passed on in specific cases, see dwFlags.

[in] dwTotalDataLen Total size in bytes of the message to be encoded.

[in] bErrorCode Message error code to be placed in the security header, usually in reply messages.

[in] bSpecialTreatment Special message handling code, according to the Central Bank manual.

[out] hSPBCtx Pointer to the context of the SPB encoding operation. After use, it must be freed with the DSPBEncodeEnd() function.

[in]

dwFlags

Defines coding details and can take on the following values described in the table below.

Value	Meaning
0	It uses the SPB (Brazilian Payment System) standard.
ND_SPB_ENCODE_GEN_01	Generates a GEN 01 message.
ND_SPB_USE_CIP1	Uses the CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea standard. When this flag is not set, the SPB (Brazilian Payment System) standard is used. Compatible with C3 Nuclea.
ND_SPB_USE_ANY	Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.
ND_SPB_ENCODE_HEADER_V3	Encodes the message using the security header version 3. In future this option will be set by default. The V3 header is available from version 5.0.16 of the HSM firmware.
ND_SPB_RAW	Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for `szSrcISPB` e `szDstISPB`.

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

Notes: DSPBEncodeCont() and DSPBEncodeEnd() must be called to send the message and finish coding. Even in the event of an error, always release the operation context using DSPBEncodeEnd().
Certificate types:
SPB - The OU must contain the ISPB in the prefix format "ISPB-" + 8 digits. E.g.: ISPB-11111111.
CIP1 - The OU must contain the ISPB in 8-digit format. E.g.: 11111111.

Examples: spb_enc_dec.c.

◆ DSPBEncodeCont()

int AAP_API DSPBEncodeCont	(	HSPBCTX	hSPBCtx,
		BYTE *	pbDataIn,
		DWORD	dwDataInLen,
		BYTE *	pbDataOut,
		DWORD *	pdwDataOutLen )

#include <dinamo.h>

Sends parts or all of the message for encoding in the HSM.

Parameters

[in]	hSPBCtx	Context acquired through the DSPBEncodeInit() function.
[in]	pbDataIn	Buffer containing part or all of the message to be encoded. The size per call is DN_SPB_MAX_NOTIFY_DATA_SEG bytes. Smaller sizes can be sent if it is the last or only piece of the message.
[in]	dwDataInLen	Buffer size in bytes `pbDataIn`.
[out]	pbDataOut	Buffer that will receive the encoded message data. It must be equal to or greater than `pbDataIn`. If it is the last piece, add space in the size for possible padding/tag. We recommend using a minimum size of DN_SPB_MAX_RCV_NOTIFY_DATA_SEG bytes to ensure that all returned data is received.
[in,out]	pdwDataOutLen	Pointer to a DWORD that contains the size of `pbDataOut`. The input must contain the size of the buffer pointed to by pbDataOut, the output contains the size of the data that was encoded in pbDataOut.

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

Notes: Even in the event of an error, always release the operation context using DSPBEncodeEnd().

Examples: spb_enc_dec.c.

◆ DSPBEncodeEnd()

int AAP_API DSPBEncodeEnd	(	HSPBCTX *	hSPBCtx,
		BYTE *	pbSPBHeader,
		DWORD *	pdwSPBHeaderLen )

#include <dinamo.h>

Completes an SPB encryption operation and receives the security header.

Parameters

[in]	hSPBCtx	Pointer to the context acquired through the DSPBEncodeInit() function.
[out]	pbSPBHeader	Buffer containing the security header of the encoded message. It must have a size equal to or greater than DN_SPB_MSG_HEADER_V2_LEN bytes.
[in,out]	pdwSPBHeaderLen	Pointer to a DWORD that on input should contain the size of the buffer pointed to by pbSPBHeader, and on output will contain the size of the header written in pbSPBHeader.

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

Examples: spb_enc_dec.c.

◆ DSPBDecodeInit()

int AAP_API DSPBDecodeInit	(	HSESSIONCTX	hSession,
		char *	szSrcISPB,
		char *	szDstISPB,
		BYTE *	pbHeader,
		DWORD	dwHeaderLen,
		BYTE	bAcceptExpiredCert,
		BYTE	bAutoUpdateCert,
		DWORD	dwMessageDataLen,
		HSPBCTX *	hSPBCtx,
		DWORD	dwFlags )

#include <dinamo.h>

Starts an SPB message decoding operation.

Parameters

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

[in] szSrcISPB Source institution identifier with maximum size MAX_OBJ_ID_FQN_LEN. The source identifier must have the following format: ISPB@DOMINIO, with the domain part being optional. The exact length for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN. You can also pass the name of the corresponding map, outside the SPB module's naming standard in specific cases, see dwFlags.

[in] szDstISPB Destination institution identifier with maximum size MAX_OBJ_ID_FQN_LEN. The destination identifier must have the following format: ISPB@DOMINIO. The size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN. You can also pass the name of the corresponding map, outside the SPB module's naming standard in specific cases, see dwFlags.

[in] pbHeader Buffer containing the security header of the SPB message to be decoded.

[in] dwHeaderLen Size in bytes of the pbHeader buffer.

[in] bAcceptExpiredCert Byte to accept expired certificates when decoding the message. Pass 1 to accept and 0 to not accept.

[in] bAutoUpdateCert Enables or disables the automatic updating of certificates in the HSM database if the message is about a certificate change. The following messages are currently handled: GEN0006 (reply), GEN0007, GEN0008 (reply) and GEN0018. The certificate is imported and activated automatically, except in the case of GEN0018 (Central Bank certificate), where the certificate is imported but not activated. Enter 1 for enabled and 0 for disabled.

[in] dwMessageDataLen Total size of the SPB message to be decoded.

[out] hSPBCtx Pointer to the context of the SPB decode operation. After use, it must be released with the DSPBDecodeEnd() function.

[in]

dwFlags

Defines decoding details, and can take on the following values described in the table below.

Value	Meaning
0	It uses the SPB (Brazilian Payment System) standard.
ND_SPB_OUT_NO_PADDING	Removes padding from the end of the SPB message after decryption.
ND_SPB_OUT_WITH_PADDING	Keeps the padding at the end of the SPB message after decryption.
ND_SPB_USE_CIP1	Uses the CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea standard. When this flag is not set, the SPB (Brazilian Payment System) standard is used.
ND_SPB_USE_ANY	Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.
ND_SPB_RAW	Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for `szSrcISPB` e `szDstISPB`.

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

Notes: DSPBDecodeCont() and DSPBDecodeEnd() must be called to send the message and finish coding. Even in the event of an error, always release the operation context using DSPBDecodeEnd(). The handling of GEN0006R1 (GEN0006 response) is available from firmware version 5.0.16.
Certificate types:
SPB - The OU must contain the ISPB in the prefix format "ISPB-" + 8 digits. E.g.: ISPB-11111111.
CIP1 - The OU must contain the ISPB in 8-digit format. E.g.: 11111111.

Examples: spb_enc_dec.c.

◆ DSPBDecodeCont()

int AAP_API DSPBDecodeCont	(	HSPBCTX	hSPBCtx,
		BYTE *	pbDataIn,
		DWORD	dwDataInLen,
		BYTE **	ppbDataOut,
		DWORD *	pdwDataOutLen )

#include <dinamo.h>

Sends parts or all of the message for decoding in the HSM.

Parameters

[in]	hSPBCtx	Context acquired through the DSPBDecodeInit function.
[in]	pbDataIn	Buffer containing part or all of the message to be decoded. The size per call is ND_SPB_MAX_NOTIFY_DATA_SEG bytes. Smaller sizes can be sent if it is the last or only piece of the message.
[in]	dwDataInLen	Buffer size in bytes `pbDataIn`.
[out]	ppbDataOut	Pointer that will receive the encoded data. The size of the allocated buffer is available via pdwDataOutLen. Memory allocation is done internally. Deallocation is done in the next call to DSPBDecodeCont() or DSPBDecodeEnd().
[out]	pdwDataOutLen	Pointer to the size of the buffer allocated internally in ppbDataOut.

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

Examples: spb_enc_dec.c.

◆ DSPBDecodeEnd()

int AAP_API DSPBDecodeEnd ( HSPBCTX * hSPBCtx )

#include <dinamo.h>

Completes an SPB decoding operation and receives the security header.

Parameters

[in] hSPBCtx Pointer to the context acquired via the DSPBDecodeInit() function.

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

Examples: spb_enc_dec.c.

◆ DSPBGenerateKey()

int AAP_API DSPBGenerateKey	(	HSESSIONCTX	hSession,
		char *	szID,
		char *	szPrivateKeyName,
		DWORD	dwKeyParam,
		DWORD	dwParam )

#include <dinamo.h>

Generates a private key in the SPB standard. This is a specialized function of the HSM key generation API.
The application generates the key (RSA 2048 or as established in the updated Bacen manual) with the identification following the internal formation law, described in the SPB module presentation.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szID	Identifier of the institution for which the private key is intended. The institution identifier must have the following format: "ISPB@DOMINIO", with the domain part being optional. The exact length for ISPB is ND_SPB_ISPB_LEN and the maximum length for DOMINIO is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the DOMAIN identifier.
[out]	szPrivateKeyName	Buffer of size MAX_OBJ_ID_FQN_LEN or more. This buffer will receive a string containing the identifier of the key pair generated within the HSM. This identifier must be kept by the application for later use in DSPBGenerateCSR() and/or others.
[in]	dwKeyParam	Additional key parameters. See the options in the DGenerateKey() function.
[in]	dwParam	Reserved for future use (must be 0).

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

Examples: spb_gen_key_csr.c.

◆ DSPBGenerateCSR()

int AAP_API DSPBGenerateCSR	(	HSESSIONCTX	hSession,
		char *	szPrivateKeyName,
		BYTE	bVersion,
		char *	szSPBSubject,
		DWORD	dwOutType,
		DWORD *	pdwCSRLen,
		BYTE **	ppbCSR,
		DWORD	dwParam )

#include <dinamo.h>

Generates a CSR (Certificate Signing Request) for SPB. This is a specialized function of HSM's PKCS#10 CSR generation API.
There are no validation rules for SPB certificates; this is up to the application, which can generate CSRs for different systems, such as SPB and CIP.

Parameters

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

[in] szPrivateKeyName Identifier of the private key.
Normally the string generated in DSPBGenerateKey().

[in]

bVersion

CSR version PKCS#10. The following table is supported.

Value	Meaning
CORE_P10_CSR_VERSION1	PKCS#10 CSR version 1.

[in] szSPBSubject DN (Dinstinguished Name), for generating the CSR, with a maximum size of CORE_P10_CSR_DN_MAX_LEN. DN fields must be separated by '/'.

[in]

dwOutType

CSR output type. The following table is supported.

Value	Meaning
P10_CSR_DER	Exports the CSR in DER format.
P10_CSR_PEM	Exports the CSR in PEM format.

[out] pdwCSRLen Pointer to the size of the buffer allocated in ppbCSR.

[out] ppbCSR Pointer that will receive the CSR.
The size of the allocated buffer will be available via pdwCSRLen.
Memory allocation is done internally.
The calling application is responsible for freeing the allocated memory using the DFree() API.

[in]

dwParam

Additional parameters. The following table is supported.

Value	Meaning
0	Uses the standard HSM hash in the CSR signature.
CORE_P10_HASH_SHA1	It uses SHA-1 in the CSR signature.
CORE_P10_HASH_SHA224	It uses SHA-224 in the CSR signature.
CORE_P10_HASH_SHA256	It uses SHA-256 in the CSR signature.
CORE_P10_HASH_SHA384	It uses SHA-384 in the CSR signature.
CORE_P10_HASH_SHA512	It uses SHA-512 in the CSR signature.

Notes: DN field examples.
/CN=BANCO TESTE S/A P001/OU=SISBACEN-00888/OU=ISPB-54444619/O=ICP-Brasil/L=Sao Paulo/S=Sao Paulo/C=BR

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

Examples: spb_gen_key_csr.c.

◆ DSPBImportCertificate()

int AAP_API DSPBImportCertificate	(	HSESSIONCTX	hSession,
		BYTE	bActivate,
		const char *	szUser,
		BYTE *	pbCertificate,
		DWORD	dwCertificateLen,
		const char *	szDomain,
		DWORD	dwParam )

#include <dinamo.h>

It imports an SPB certificate and associates it with a key pair within the HSM (via a map object), if such a key exists.

: The application does not need to state whether it is its own certificate or that of a third party; the HSM searches for a private key corresponding to the public key in the certificate and, if it finds one, associates it with the appropriate map. When no corresponding private key is found, it is assumed that the certificate belongs to a third party. This internal search by the HSM makes the operation faster, more atomic and more secure, since the library doesn't need to perform export operations and local searches.

: The certificate is created in the HSM base with the name formation law defined. HSM parses the certificate to retrieve fields such as ISPB.

: If the HSM finds the private key, a map is created identified by MD5(CA+NS), placing the id of the key in slot1 and the id of the newly imported certificate in slot2. It returns an error if the map already exists. This is the case for an own certificate.

: If the firmware doesn't find the private key, a map is created identified by MD5(CA+NS), leaving slot1 empty and slot2 with the id of the newly imported certificate. It returns an error if the map already exists. This is the case with a third-party certificate.

Parameters

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

[in] bActivate Automatically activates the certificate when importing.
Enter 1 to activate and 0 to import without activating the certificate.

[in] szUser User name, for importing the certificate, with maximum length(MAX_USR_LEN+1).
It can be NULL if the import is made from the user's current session.

[in] pbCertificate Buffer containing the certificate to be imported. The certificate can be in PEM or DER format.

[in] dwCertificateLen Size of the buffer pointed to by pbCertificate.

[in] szDomain Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1).
Can be NULL if no domain is defined.

[in]

dwParam

The following table of flags is supported.

Value	Meaning
0	It uses the SPB (Brazilian Payment System) standard.
ND_SPB_USE_CIP1	It uses the CIP (Camara Interbancaria de Pagamentos) standard.
ND_SPB_USE_ANY	Accepts the CIP and SPB standard. Detection is done internally.

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

Notes: Certificate types:
SPB - The OU must contain the ISPB in the prefix format "ISPB-" + 8 digits. E.g.: ISPB-11111111.
CIP1 - The OU must contain the ISPB in 8-digit format. E.g.: 11111111.

Examples: spb_gen_key_csr.c.

◆ DSPBImportPKCS12()

int AAP_API DSPBImportPKCS12	(	HSESSIONCTX	hSession,
		BYTE	bActivate,
		const char *	szUser,
		const char *	szPkcs12File,
		const char *	szPkcs12Pwd,
		const char *	szDomain,
		DWORD	dwKeyAttr )

#include <dinamo.h>

Import a key pair and a certificate from a PKCS#12 file.

: The certificate and private key are created in the HSM base with the name formation law defined. The HSM parses the certificate to retrieve fields such as CA and NS.

: In the import process a map is created identified by MD5(CA+NS), in slot1 goes the key id and in slot2 the certificate id. It returns an error if the map already exists, i.e. if the certificate and private key already exist in the HSM database.

: This API automatically detects whether it is an SPB or CIP certificate.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bActivate	Automatically activates the certificate when importing. Enter 1 to activate and 0 to import without activating the certificate.
[in]	szUser	Name of the user where the key will be created. Can be NULL if the key is created on the authenticated user.
[in]	szPkcs12File	PKCS#12 file name for import.
[in]	szPkcs12Pwd	PKCS#12 file password for import.
[in]	szDomain	Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1). cMay be NULL if no domain is defined.
[in]	dwKeyAttr	Additional key parameters. See the options in the DGenerateKey() function.

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

Examples: spb_activate_cert.c, spb_enc_dec.c, spb_get_cert. c and spb_import_p12.c.

◆ DSPBExportPKCS12()

int AAP_API DSPBExportPKCS12	(	const HSESSIONCTX	hSession,
		const char *	szPkcs12Pwd,
		const char *	szISPB,
		const char *	szReserved,
		BYTE **	ppbPkcs12,
		DWORD *	pdwPkcs12Len,
		DWORD	dwReserved )

#include <dinamo.h>

Exports a key pair and a certificate in PKCS#12 format from an HSM.

: This call accepts certificate/private key identifiers in CA@SN and ISPB@DOM formats.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function. .
[in]	szPkcs12Pwd	Password for PKCS#12 file. Pass NULL to generate PKCS#12 without password.
[in]	szISPB	Certificate identifier/private key in CA@SN, ISPB or ISPB@DOM format.
[in]	szReserved	Reserved for future use (must be NULL).
[out]	ppbPkcs12	Pointer to a pointer that will contain the generated PKCS#12. This data area will be allocated internally and must be freed using DFree().
[out]	pdwPkcs12Len	Pointer to the size of the data written in `ppbPkcs12`.
[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.

◆ DSPBActivateCertificate()

int AAP_API DSPBActivateCertificate	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		const char *	szDomain,
		DWORD	dwParam )

#include <dinamo.h>

Activates an SPB certificate in the HSM.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIdCert	Identifier of the certificate to be activated. The certificate identifier must have the following format: CA@SN. The size for CA is ND_SPB_CA_LEN and the size for SN is ND_SPB_SN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 03@12345678 where 03 is the CA identifier and 12345678 is the certificate serial number.
[in]	szDomain	Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1). Can be NULL if no domain is defined.
[in]	dwParam	Reserved for future use.

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

Examples: spb_activate_cert.c.

◆ DSPBGetCertificate()

int AAP_API DSPBGetCertificate	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		BYTE **	ppbCertificate,
		DWORD *	pdwCertificateLen,
		DWORD	dwParam )

#include <dinamo.h>

Activates an SPB certificate in the HSM.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIdCert	Identification of the certificate to be recovered. The certificate identifier can have the following formats: ID, CA@SN or ISPB@DOMINIO. The exact size for CA is ND_SPB_CA_LEN and the maximum size for SN is ND_SPB_SN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 03@12345678 where 03 is the CA identifier and 12345678 is the institution's ISPB. The exact size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMINIO is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the DOMAIN identifier.
[out]	ppbCertificate	Pointer that will receive the certificate. The size of the allocated buffer will be available through pdwCertificateLen. Memory allocation is done internally by the library. The calling application is responsible for freeing the allocated memory using the DFree() API.
[out]	pdwCertificateLen	Pointer to the buffer size pointed to by ppbCertificate.
[in]	dwParam	Reserved for future use (must be 0).

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

Examples: spb_get_cert.c.

◆ DSPBCalculateObjectId()

int AAP_API DSPBCalculateObjectId	(	char *	szISPB,
		char *	szDomain,
		DWORD	dwKeyType,
		char *	szOutObjName,
		DWORD	dwParam )

#include <dinamo.h>

Auxiliary API that calculates (locally) an object name in the SPB module's standard format.

Parameters

[in] szISPB ISPB of the institution. It must have a size of(ND_SPB_ISPB_LEN +1).

[in] szDomain Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1).
Can be NULL if no domain is defined.

[in]

dwKeyType

Type of name to be generated. The values in the following table will be accepted.

Value	Meaning
SPB_GENERATE_KEY_NAME	Generates a name for a key.
SPB_GENERATE_CER_NAME	Generates a name for a certificate.

[out] szOutObjName Buffer of size MAX_OBJ_ID_FQN_LEN that will contain the calculated object name.

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

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

◆ DSPBMapInfo()

int AAP_API DSPBMapInfo	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		EXT_MAP_2_OBJ_INFO *	pstExtMap,
		DWORD	dwParam )

#include <dinamo.h>

Auxiliary API that retrieves information from a MAP SPB.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szIdCert	Identification of the certificate to be recovered. The certificate identifier can have the following formats: ID, CA@SN or ISPB@DOMINIO. The exact size for CA is ND_SPB_CA_LEN and the maximum size for SN is ND_SPB_SN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 03@12345678 where 03 is the CA identifier and 12345678 is the certificate serial number. The exact size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the DOMAIN identifier.
[out]	pstExtMap	Pointer to an EXT_MAP_2_OBJ_INFO that will contain the information of the requested MAP.
[in]	dwParam	Reserved for future use (must be 0).

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

Examples: spb_get_cert.c.

◆ DSPBSetISPBMap()

int AAP_API DSPBSetISPBMap	(	HSESSIONCTX	hSession,
		char *	szISPB,
		char *	szKeyId,
		char *	szCertId,
		DWORD	dwParam )

#include <dinamo.h>

Auxiliary API that creates or modifies an SPB map. The map is identified from the CA and NS data of the certificate provided.

Parameters

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

[in] szISPB ISPB of the institution. It must have a maximum size of MAX_OBJ_ID_FQN_LEN.

[in] szKeyId Name of the institution's private key. Must have a maximum length of MAX_OBJ_ID_FQN_LEN.
Can be NULL if you are only defining the certificate.

[in] szCertId Name of the institution's certificate. Must have a maximum length of MAX_OBJ_ID_FQN_LEN.

[in]

dwParam

The following table of flags is supported.

Value	Meaning
0	It uses the SPB (Brazilian Payment System) standard.
ND_SPB_USE_CIP1	It uses the CIP (Camara Interbancaria de Pagamentos) standard.
ND_SPB_USE_ANY	Accepts the CIP and SPB standard. Detection is done internally.

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