Detailed description

Encode and Decode operations according to the SPB standard.

Functions
void	SPBListObjects (OBJTYPE type, DinamoApi.ListCallbackFilter filterCallBack, IntPtr param)
	Lists objects of a certain type (key, certificate, etc.).

byte[]	SPBGetCertificate (string strIdCertificate)
	Retrieves a certificate stored in a namespace in the HSM.

string	SPBGenerateKey (string ISPB, string domain, bool isExportable)
	Generates RSA 2048 key in the SPB standard. This function will always adhere to the SPB requirements, according to the RSFN security manual. DinamoClient.GenerateKey(string, KEY_ALG, bool)

byte[]	SPBGenerateCSR (string sPrivateKeyName, string sSubject)
	Generates a new CSR based on an existing key (RSA 2048).

byte[]	SPBEncode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, byte bSpecialTreatment)
	Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

byte[]	SPBEncode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, byte bSpecialTreatment, byte bErrorCode, UInt32 dwFlags)
	Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

void	SPBEncode (string szSrcISPB, string szDstISPB, Stream sMsgIn, Stream sMsgOut, byte bErrorCode, byte bSpecialTreatment, UInt32 dwFlags)
	Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

byte[]	SPBDecode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn)
	Decodes a message in the SPB standard, checking signatures, decrypting, but does not check encoding.

byte[]	SPBDecode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, bool AcceptExpiredCert, bool AutoUpdateCert)
	Decrypts a message in the SPB standard, checking signatures and decrypting.

byte[]	SPBDecode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, bool AcceptExpiredCert, bool AutoUpdateCert, UInt32 dwFlags)
	Decrypts a message in the SPB standard, checking signatures and decrypting.

void	SPBDecode (string szSrcISPB, string szDstISPB, Stream sMsgIn, Stream sMsgOut, bool AcceptExpiredCert, bool AutoUpdateCert, UInt32 dwFlags)
	Decrypts a message in the SPB standard, checking signatures and decrypting.

string	SPBMapInfoCert (string sIdCert)
	Creates a map with the institution's certificate in a slot.

void	SPBSetISPBMap (string sIdMap, string sIdKey, string sIdCert)
	Creates a map with the institution's key and certificate in a slot.

void	SPBImportPKCS12 (string szPkcs12File, string szPkcs12Pwd, string szNamespace, string szDomain, int dwKeyAttr)
	Imports a certificate from a PKCS#12 container into the HSM.

void	SPBImportPKCS12 (string szPkcs12File, string szPkcs12Pwd, string szNamespace, string szDomain, int dwKeyAttr, bool isActivate)
	Imports a certificate from a PKCS#12 container into the HSM.

void	SPBImportCertificate (string szDomain, byte[] bCertificate)
	Import a certificate into an HSM namespace.

void	SPBImportCertificate (string szDomain, byte[] bCertificate, bool isCIPCertificate=false)
	Import a certificate into an HSM namespace.

void	SPBActivateCertificate (string szDomain, string szCA, string szSN, bool isCIPCertificate=false)
	Activates a certificate that has already been imported into the HSM. If another certificate is active, it will be inactivated. Only one certificate will remain active per institution, per domain within an HSM namespace.

void	SPBImportCertificate (string szNamespace, string szDomain, byte[] bCertificate, bool isCIPCertificate=false)
	Activates a certificate that has already been imported into the HSM. If another certificate is active, it will be inactivated. Only one certificate will remain active per institution, per domain within an HSM namespace.

void	SPBActivateCertificate (string szNamespace, string szDomain, string szCA, string szSN, bool isCIPCertificate=false)
	Activates a certificate that has already been imported into the HSM. If another certificate is active, it will be inactivated. Only one certificate will remain active per institution, per domain within an HSM namespace.

string	SPBCalculateObjectId (string szISPB, string szDomain, KEYNAME dwKeyType)
	Function to help format the identification of internal HSM objects according to the standard used in theSPB module.

DinamoApi.SPB_CERT_X509_INFO	SPBGetCertificateInfo (byte[] certificate)
	Retrieves information from the certificate.

Functions

◆ SPBListObjects()

void SPBListObjects	(	OBJTYPE	type,
		DinamoApi.ListCallbackFilter	filterCallBack,
		IntPtr	param )

inline

Lists objects of a certain type (key, certificate, etc.).

Parameters

filterCallBack	Callback function called for each object in the interaction
param	Parameters
type	Object type Dinamo.Hsm.DinamoClient.OBJTYPE

Exceptions

DinamoException.DinamoException In case of error

◆ SPBGetCertificate()

byte[] SPBGetCertificate ( string strIdCertificate )

inline

Retrieves a certificate stored in a namespace in the HSM.

Parameters

strIdCertificate identificação do certificado no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".

Return: Return of the certificate in DER format as a byte array

Exceptions

DinamoException.DinamoException In case of error

Examples: spb_import_activate.cs.

◆ SPBGenerateKey()

string SPBGenerateKey	(	string	ISPB,
		string	domain,
		bool	isExportable )

inline

Generates RSA 2048 key in the SPB standard. This function will always adhere to the SPB requirements, according to the RSFN security manual. DinamoClient.GenerateKey(string, KEY_ALG, bool)

Parameters

ISPB	ISBP number
domain	Domain
isExportable	True to generate an exportable key

Return: Label of the generated key

Exceptions

DinamoException.DinamoException In case of error

◆ SPBGenerateCSR()

byte[] SPBGenerateCSR	(	string	sPrivateKeyName,
		string	sSubject )

inline

Generates a new CSR based on an existing key (RSA 2048).

Parameters

sPrivateKeyName	Key identification in the HSM
sSubject	Description of the CSR's DN (Dinstinguished Name) certificate subject for generating the certificate's Subject field. DN fields must be separated by '/'.

Return: Label of the generated key

Exceptions

DinamoException.DinamoException In case of error

◆ SPBEncode() [1/3]

byte[] SPBEncode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		byte	bSpecialTreatment )

inline

Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

Parameters

szSrcISPB	Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDstISPB	Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
pbMsgIn	Message passed as an array of bytes. HSM does not perform automatic format conversion. In the SPB standard, the defined format is UTF16-BE, and it is up to the API caller to ensure that the message is using the correct format.
bSpecialTreatment	Special treatment indicator. See C04 in the SPB security manual.

Return: Message signed.

Exceptions

DinamoException.DinamoException In case of error

Examples: spb.cs and spb_file_cip.cs.

◆ SPBEncode() [2/3]

byte[] SPBEncode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		byte	bSpecialTreatment,
		byte	bErrorCode,
		UInt32	dwFlags )

inline

Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

Parameters

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

pbMsgIn Message passed as an array of bytes. HSM does not perform automatic format conversion. In the SPB standard, the defined format is UTF16-BE, and it is up to the API caller to ensure that the message is using the correct format.

bSpecialTreatment Special treatment indicator. See C04 in the SPB security manual.

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

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.
DinamoApi.ND_SPB_ENCODE_GEN_01	Generates a GEN 01 message.
DinamoApi.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.
DinamoApi.ND_SPB_USE_ANY	Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.
DinamoApi.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.

DinamoApi.ND_SPB_RAW

Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for szSrcISPB e szDstISPB.

Return: Message signed.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBEncode() [3/3]

void SPBEncode	(	string	szSrcISPB,
		string	szDstISPB,
		Stream	sMsgIn,
		Stream	sMsgOut,
		byte	bErrorCode,
		byte	bSpecialTreatment,
		UInt32	dwFlags )

inline

Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

Parameters

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

sMsgIn Message to be encoded. The Stream passed must support the Length property. HSM does not perform automatic format conversion. In the SPB standard, the defined format is UTF16-BE, and it is up to the API caller to ensure that the message is using the correct format.

sMsgOut Stream that will receive the encoded output message. The Stream passed in must support the Length property and the Seek method. HSM does not perform automatic format conversion. In the SPB standard, the defined format is UTF16-BE, and it is up to the API caller to ensure that the message is using the correct format.

bSpecialTreatment Special treatment indicator. See C04 in the SPB security manual.

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

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.
DinamoApi.ND_SPB_ENCODE_GEN_01	Generates a GEN 01 message.
DinamoApi.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.
DinamoApi.ND_SPB_USE_ANY	Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.
DinamoApi.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.

DinamoApi.ND_SPB_RAW

Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for szSrcISPB e szDstISPB.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBDecode() [1/4]

byte[] SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn )

inline

Decodes a message in the SPB standard, checking signatures, decrypting, but does not check encoding.

Parameters

szSrcISPB	Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDstISPB	Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
pbMsgIn	Message encoded in the SPB standard passed as an array of bytes.

Return: Message decoded.

Exceptions

DinamoException.DinamoException In case of error

Examples: spb.cs and spb_file_cip.cs.

◆ SPBDecode() [2/4]

byte[] SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		bool	AcceptExpiredCert,
		bool	AutoUpdateCert )

inline

Decrypts a message in the SPB standard, checking signatures and decrypting.

Parameters

szSrcISPB	Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDstISPB	Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
pbMsgIn	Message encoded in the SPB standard passed as an array of bytes.
AcceptExpiredCert	It accepts operations even with an expired certificate.
AutoUpdateCert	It interprets certificate exchange messages and automatically performs the operation internally.

Return: Message decoded.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBDecode() [3/4]

byte[] SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		bool	AcceptExpiredCert,
		bool	AutoUpdateCert,
		UInt32	dwFlags )

inline

Decrypts a message in the SPB standard, checking signatures and decrypting.

Parameters

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

pbMsgIn Message encoded in the SPB standard passed as an array of bytes.

AcceptExpiredCert It accepts operations even with an expired certificate.

AutoUpdateCert It interprets certificate exchange messages and automatically performs the operation internally.

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.
DinamoApi.ND_SPB_OUT_NO_PADDING	Removes padding from the end of the SPB message after decryption.
DinamoApi.ND_SPB_OUT_WITH_PADDING	Keeps the padding at the end of the SPB message after decryption.
DinamoApi.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.
DinamoApi.ND_SPB_USE_ANY	Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.

Return: Message decoded.

DinamoApi.ND_SPB_RAW | Mode without SPB-specific checks. Accepts only the use of the MAP name as parameters for szSrcISPB e szDstISPB.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBDecode() [4/4]

void SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		Stream	sMsgIn,
		Stream	sMsgOut,
		bool	AcceptExpiredCert,
		bool	AutoUpdateCert,
		UInt32	dwFlags )

inline

Decrypts a message in the SPB standard, checking signatures and decrypting.

Parameters

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

sMsgIn Message encoded in the SPB standard. The Stream passed must support the Length property. HSM does not perform automatic format conversion. In the SPB standard, the defined format is UTF16-BE, and it is up to the API caller to ensure that the message is using the correct format.

sMsgOut Stream that will receive the encoded output message. The Stream passed in must support the Length property and the Seek method. HSM does not perform automatic format conversion. In the SPB standard, the defined format is UTF16-BE, and it is up to the API caller to ensure that the message is using the correct format.

AcceptExpiredCert It accepts operations even with an expired certificate.

AutoUpdateCert It interprets certificate exchange messages and automatically performs the operation internally.

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.
DinamoApi.ND_SPB_OUT_NO_PADDING	Removes padding from the end of the SPB message after decryption.
DinamoApi.ND_SPB_OUT_WITH_PADDING	Keeps the padding at the end of the SPB message after decryption.
DinamoApi.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.
DinamoApi.ND_SPB_USE_ANY	Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.

DinamoApi.ND_SPB_RAW

Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for szSrcISPB e szDstISPB.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBMapInfoCert()

string SPBMapInfoCert ( string sIdCert )

inline

Creates a map with the institution's certificate in a slot.

Parameters

sIdCert Identification/label of the certificate in the HSM

Return: Name of the map object created in HSM.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBSetISPBMap()

void SPBSetISPBMap	(	string	sIdMap,
		string	sIdKey,
		string	sIdCert )

inline

Creates a map with the institution's key and certificate in a slot.

Parameters

sIdMap	Map identification (can be ISPB)
sIdKey	Key identification
sIdCert	Certificate identification

Exceptions

DinamoException.DinamoException Throws exception in case of signature errors

◆ SPBImportPKCS12() [1/2]

void SPBImportPKCS12	(	string	szPkcs12File,
		string	szPkcs12Pwd,
		string	szNamespace,
		string	szDomain,
		int	dwKeyAttr )

inline

Imports a certificate from a PKCS#12 container into the HSM.

Parameters

szPkcs12File Path and file name.

szPkcs12Pwd Password

szNamespace Partition where the object is located. If the object is in the same partition as the logged one, you can pass null.

szDomain Mastery of the SPB.

dwKeyAttr

Additional key parameters.

Value	Meaning
DinamoApi.NONEXPORTABLE_KEY	The key cannot leave the HSM.
DinamoApi.EXPORTABLE_KEY	The key can be exported from the HSM.
DinamoApi.TEMPORARY_KEY	The key will only exist while the session is active. It will be destroyed after the session is closed.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBImportPKCS12() [2/2]

void SPBImportPKCS12	(	string	szPkcs12File,
		string	szPkcs12Pwd,
		string	szNamespace,
		string	szDomain,
		int	dwKeyAttr,
		bool	isActivate )

inline

Imports a certificate from a PKCS#12 container into the HSM.

Parameters

szPkcs12File Path and file name.

szPkcs12Pwd Password.

szNamespace Partition where the object is located. If the object is in the same partition as the logged one, you can pass null.

szDomain Mastery of the SPB.

dwKeyAttr

Additional key parameters.

Value	Meaning
DinamoApi.NONEXPORTABLE_KEY	The key cannot leave the HSM.
DinamoApi.EXPORTABLE_KEY	The key can be exported from the HSM.
DinamoApi.TEMPORARY_KEY	The key will only exist while the session is active. It will be destroyed after the session is closed.

isActivate Activates the certificate during import

Exceptions

DinamoException.DinamoException In case of error

◆ SPBImportCertificate() [1/3]

void SPBImportCertificate	(	string	szDomain,
		byte[]	bCertificate )

inline

Import a certificate into an HSM namespace.

Parameters

szDomain	Mastery of the SPB.
bCertificate	SPB certificate in the SPB standard as an array of bytes.

Exceptions

DinamoException.DinamoException In case of error

Examples: spb_import_activate.cs.

◆ SPBImportCertificate() [2/3]

void SPBImportCertificate	(	string	szDomain,
		byte[]	bCertificate,
		bool	isCIPCertificate = false )

inline

Import a certificate into an HSM namespace.

Parameters

szDomain	Mastery of the SPB.
bCertificate	SPB certificate in the SPB standard as an array of bytes.
isCIPCertificate	True if the certificate is in the CIP standard.

Exceptions

DinamoException Throws exception in case of error.

◆ SPBActivateCertificate() [1/2]

void SPBActivateCertificate	(	string	szDomain,
		string	szCA,
		string	szSN,
		bool	isCIPCertificate = false )

inline

Activates a certificate that has already been imported into the HSM. If another certificate is active, it will be inactivated. Only one certificate will remain active per institution, per domain within an HSM namespace.

Parameters

szDomain	Mastery of the SPB.
szCA	CA identification (CA number).
szSN	Certificate serial number in hexadecimal format
isCIPCertificate	True if the certificate is in the CIP standard.

The existing CA numbers can be found in the RSFN safety manual.

Exceptions

DinamoException.DinamoException In case of error

Examples: spb_import_activate.cs.

◆ SPBImportCertificate() [3/3]

void SPBImportCertificate	(	string	szNamespace,
		string	szDomain,
		byte[]	bCertificate,
		bool	isCIPCertificate = false )

inline

Activates a certificate that has already been imported into the HSM. If another certificate is active, it will be inactivated. Only one certificate will remain active per institution, per domain within an HSM namespace.

Parameters

szNamespace	Partition where the object is located. If the object is in the same partition as the logged one, you can pass `null`.
szDomain	Mastery of the SPB.
bCertificate	SPB certificate in the SPB standard as an array of bytes.
isCIPCertificate	True if the certificate is in the CIP standard.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBActivateCertificate() [2/2]

void SPBActivateCertificate	(	string	szNamespace,
		string	szDomain,
		string	szCA,
		string	szSN,
		bool	isCIPCertificate = false )

inline

Activates a certificate that has already been imported into the HSM. If another certificate is active, it will be inactivated. Only one certificate will remain active per institution, per domain within an HSM namespace.

Parameters

szNamespace	Partition where the object is located. If the object is in the same partition as the logged one, you can pass `null`.
szDomain	Mastery of the SPB.
szCA	CA identification (CA number).
szSN	Certificate serial number in hexadecimal format
isCIPCertificate	True if the certificate is in the CIP standard.

The existing CA numbers can be found in the RSFN safety manual.

Exceptions

DinamoException.DinamoException In case of error

◆ SPBCalculateObjectId()

string SPBCalculateObjectId	(	string	szISPB,
		string	szDomain,
		KEYNAME	dwKeyType )

inline

Function to help format the identification of internal HSM objects according to the standard used in theSPB module.

Parameters

szISPB	identificação do ISPB no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDomain	Mastery of the SPB.
dwKeyType	Object type. Dinamo.Hsm.DinamoClient.KEYNAME

Return: Name inSPB module format.

◆ SPBGetCertificateInfo()

DinamoApi.SPB_CERT_X509_INFO SPBGetCertificateInfo ( byte[] certificate )

inline

Retrieves information from the certificate.

Parameters

certificate Byte array with the certificate

Return: Certificate information. DinamoApi.SPB_CERT_X509_INFO

Exceptions

DinamoException Throws exception in case of error.

Examples: spb_import_activate.cs.