SPB

Detailed description

Encode and Decode operations according to the SPB standard.

See the HSM technical documentation.

Functions
void	SPBActivateCertificate (String szDomain, byte bCA, String szSN) throws TacException
	Activates a certificate that has already been imported into HSM.
void	SPBActivateCertificate (String szDomain, byte bCA, String szSN, int dwParam) throws TacException
	Activates a certificate that has already been imported into HSM.
void	SPBSetISPBMap (String strISPB, String strKeyId, String strCertId) throws TacException
	Creates a map with the institution's key and certificate in a slot.
byte[]	SPBGenerateCSR (String sPrivateKeyName, String sRazaoSocial, String sISPB, String sSISBACEN, int iSequencial, boolean bProducao, String sCidade, String sUF) throws TacException
	Generates a new CSR based on an existing key (RSA 2048).
byte[]	SPBGenerateCSR (String sPrivateKeyName, String sSubject) throws TacException
	Generates a new CSR based on an existing key (RSA 2048).
byte[]	generatePKCS10CSR (String szKeyId, String szDN, int dwOutType) throws TacException
	It generates a CSR.
void	SPBImportCertificate (String szDomain, byte[] bCertificate) throws TacException
	Import a certificate into an HSM namespace.
void	SPBImportCertificate (String szDomain, byte[] bCertificate, boolean isActive) throws TacException
	Import a certificate into an HSM namespace.
void	SPBImportCertificate (String szDomain, byte[] bCertificate, boolean isActive, int dwParam) throws TacException
	Import a certificate into an HSM namespace.
void	SPBImportPKCS12 (String path, String pass, String domain, boolean isActivate, int dwFlags) throws TacException
	Imports a certificate from a PKCS#12 container into the HSM.
byte[]	SPBGetCertificate (String strIdCertificate) throws TacException
	Retrieves a certificate stored in a namespace in the HSM.
byte[]	SPBDecode (String szSrcISPB, String szDstISPB, byte[] pbMsgIn, boolean bAcceptExpiredCert, boolean bAutoUpdateCert) throws TacSPBException, IOException
	Decodes a message in the SPB standard, checking signatures, decrypting, but does not check encoding.
byte[]	SPBDecode (String szSrcISPB, String szDstISPB, byte[] pbMsgIn, boolean bAcceptExpiredCert, boolean bAutoUpdateCert, boolean bEncodingCheck) throws TacSPBException, IOException
	Decrypts a message in the SPB standard, checking signatures and decrypting.
byte[]	SPBDecode (String szSrcISPB, String szDstISPB, byte[] pbMsgIn, boolean bAcceptExpiredCert, boolean bAutoUpdateCert, boolean bEncodingCheck, int dwFlags) throws TacSPBException, IOException
	Decrypts a message in the SPB standard, checking signatures and decrypting.
byte[]	SPBDecode (String szSrcISPB, String szDstISPB, byte[] pbMsgIn) throws TacException, IOException
byte[]	SPBEncode (String szSrcISPB, String szDstISPB, byte[] pbMsgIn, byte bSpecialTreatment) throws TacException
	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, int dwFlags) throws TacException
	Encodes a message with the SPB header, signing, encrypting and including all the header fields defined in the RSFN security manual.

Functions

SPBActivateCertificate() [1/2]

void SPBActivateCertificate	(	String	szDomain,
		byte	bCA,
		String	szSN ) throws TacException

Activates a certificate that has already been imported into 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	SPB operating domain
bCA	number of the CA that issued the certificate
szSN	Serial number of the certificate to be activated.

Exceptions

TacException

SPBActivateCertificate() [2/2]

void SPBActivateCertificate	(	String	szDomain,
		byte	bCA,
		String	szSN,
		int	dwParam ) throws TacException

Activates a certificate that has already been imported into 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	SPB operating domain
bCA	number of the CA that issued the certificate
szSN	Serial number of the certificate to be activated.
dwParam	The following table of flags is supported. Value Meaning 0 It uses the SPB (Brazilian Payment System) standard. TacNDJavaLib.ND_SPB_USE_CIP1 It uses the CIP (Camara Interbancaria de Pagamentos)/C3 Nuclea standard.

Exceptions

TacException

SPBSetISPBMap()

void SPBSetISPBMap	(	String	strISPB,
		String	strKeyId,
		String	strCertId ) throws TacException

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

Parameters

strISPB	- Map identification (can be ISPB)
strKeyId	- Key identification
strCertId	- Certificate identification

Exceptions

TacException

Throws exception in case of signature errors

SPBGenerateCSR() [1/2]

byte[] SPBGenerateCSR	(	String	sPrivateKeyName,
		String	sRazaoSocial,
		String	sISPB,
		String	sSISBACEN,
		int	iSequencial,
		boolean	bProducao,
		String	sCidade,
		String	sUF ) throws TacException

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

Parameters

sPrivateKeyName	Key id in the HSM.
sRazaoSocial	Name of the entity's corporate name, in accordance with the RSFN Security Manual.
sISPB	ISPB code (08 digits). This is the institution's CNPJ base number.
sSISBACEN	The institution's SISBACEN code (05 characters).
iSequencial	Unique sequential numbering for generating the key pair, in accordance with the RSFN Security Manual.
bProducao	True to indicate a production environment certificate and false to indicate a homologation environment certificate.
sCidade	City name. Optional parameter, can indicate NUL.
sUF	State name (02 characters). Optional parameter, can indicate NUL.

Return

Byte array with CSR. Just direct it to a file.

Exceptions

TacException

SPBGenerateCSR() [2/2]

byte[] SPBGenerateCSR	(	String	sPrivateKeyName,
		String	sSubject ) throws TacException

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

Parameters

sPrivateKeyName	Key id in the HSM.
sSubject	DN (Dinstinguished Name) of the CSR to generate the Subject field of the certificate. The DN fields must be separated by '/'.

Return

Byte array with CSR. Just direct it to a file.

Exceptions

TacException

generatePKCS10CSR()

byte[] generatePKCS10CSR	(	String	szKeyId,
		String	szDN,
		int	dwOutType ) throws TacException

It generates a CSR.

Parameters

szKeyId	key name
szDN	String ending in zero of maximum length CORE_P10_CSR_DN_MAX_LEN, containing the DN (Dinstinguished Name) for generating the CSR. DN fields must be separated by '/'.
dwOutType	Output Format P10_CSR_DER(1) or P10_CSR_PEM(2)

Exceptions

TacException

SPBImportCertificate() [1/3]

void SPBImportCertificate	(	String	szDomain,
		byte[]	bCertificate ) throws TacException

Import a certificate into an HSM namespace.

Parameters

szDomain	name of the domain the certificate will be imported into
bCertificate	byte array containing the certificate (PEM or DER format)

Exceptions

TacException

SPBImportCertificate() [2/3]

void SPBImportCertificate	(	String	szDomain,
		byte[]	bCertificate,
		boolean	isActive ) throws TacException

Import a certificate into an HSM namespace.

Parameters

szDomain	name of the domain the certificate will be imported into
bCertificate	byte array containing the certificate (PEM or DER format)
isActive	activates certificate after import

Exceptions

TacException

SPBImportCertificate() [3/3]

void SPBImportCertificate	(	String	szDomain,
		byte[]	bCertificate,
		boolean	isActive,
		int	dwParam ) throws TacException

Import a certificate into an HSM namespace.

Parameters

szDomain	name of the domain the certificate will be imported into
bCertificate	byte array containing the certificate (PEM or DER format)
isActive	activates certificate after import
dwParam	The following table of flags is supported. Value Meaning 0 It uses the SPB (Brazilian Payment System) standard. TacNDJavaLib.ND_SPB_USE_CIP1 It uses the CIP (Camara Interbancaria de Pagamentos)/C3 Nuclea standard. TacNDJavaLib.ND_SPB_USE_ANY Accepts the CIP/C3 Nuclea and SPB standard. Detection is done internally.

Exceptions

TacException

SPBImportPKCS12()

void SPBImportPKCS12	(	String	path,
		String	pass,
		String	domain,
		boolean	isActivate,
		int	dwFlags ) throws TacException

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

Parameters

path	File path
pass	Password
dwFlags	Additional key parameters. Value Meaning TacNDJavaLib.NONEXPORTABLE_KEY The key cannot leave the HSM. TacNDJavaLib.EXPORTABLE_KEY The key can be exported from the HSM. TacNDJavaLib.TEMPORARY_KEY The key will only exist while the session is active. It will be destroyed after the session is closed.
domain	Domain for import
isActivate	Activates the certificate during import

Exceptions

TacException

SPBGetCertificate()

byte[] SPBGetCertificate

(

String

strIdCertificate

)

throws TacException

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

Exceptions

TacException

SPBDecode() [1/4]

byte[] SPBDecode	(	String	szSrcISPB,
		String	szDstISPB,
		byte[]	pbMsgIn,
		boolean	bAcceptExpiredCert,
		boolean	bAutoUpdateCert ) throws TacSPBException, IOException

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
bAcceptExpiredCert	true if the HSM should accept expired certificates in certificate exchange messages
bAutoUpdateCert	true to indicate that the HSM should automatically update the certificate of the institution that sent an SPB certificate exchange message

Return

Byte array with the decoded message.

Exceptions

TacException	Error in HSM operation.
IOException	Writing error in the decoding memory (streams).

SPBDecode() [2/4]

byte[] SPBDecode	(	String	szSrcISPB,
		String	szDstISPB,
		byte[]	pbMsgIn,
		boolean	bAcceptExpiredCert,
		boolean	bAutoUpdateCert,
		boolean	bEncodingCheck ) throws TacSPBException, IOException

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
bAcceptExpiredCert	true if the HSM should accept expired certificates in certificate exchange messages
bAutoUpdateCert	true to indicate that the HSM should automatically update the certificate of the institution that sent an SPB certificate exchange message
bEncodingCheck	turns on coding range validation

Return

Byte array with the decoded message.

Exceptions

TacException	Error in HSM operation.
IOException	Writing error in the decoding memory (streams).

SPBDecode() [3/4]

byte[] SPBDecode	(	String	szSrcISPB,
		String	szDstISPB,
		byte[]	pbMsgIn,
		boolean	bAcceptExpiredCert,
		boolean	bAutoUpdateCert,
		boolean	bEncodingCheck,
		int	dwFlags ) throws TacSPBException, IOException

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
bAcceptExpiredCert	true if the HSM should accept expired certificates in certificate exchange messages
bAutoUpdateCert	true to indicate that the HSM should automatically update the certificate of the institution that sent an SPB certificate exchange message
bEncodingCheck	turns on coding range validation
dwFlags	Defines decoding details, and can take on the following values described in the table below. Value Meaning TacNDJavaLib.ND_SPB_OUT_NO_PADDING Removes padding from the end of the SPB message after decryption. TacNDJavaLib.ND_SPB_OUT_WITH_PADDING Keeps the padding at the end of the SPB message after decryption. TacNDJavaLib.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. TacNDJavaLib.ND_SPB_RAW Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for szSrcISPB e szDstISPB.

Return

Byte array with the decoded message.

Exceptions

TacException	Error in HSM operation.
IOException	Writing error in the decoding memory (streams).

SPBDecode() [4/4]

byte[] SPBDecode	(	String	szSrcISPB,
		String	szDstISPB,
		byte[]	pbMsgIn ) throws TacException, IOException

This is a method provided for convenience. It differs from the above method only in the list of arguments that must be used.

SPBEncode() [1/2]

byte[] SPBEncode	(	String	szSrcISPB,
		String	szDstISPB,
		byte[]	pbMsgIn,
		byte	bSpecialTreatment ) throws TacException

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. Item 5.6 of the RSFN security header manual.

Return

Exceptions

TacException

SPBEncode() [2/2]

byte[] SPBEncode	(	String	szSrcISPB,
		String	szDstISPB,
		byte[]	pbMsgIn,
		byte	bSpecialTreatment,
		int	dwFlags ) throws TacException

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. Item 5.6 of the RSFN security header manual.
dwFlags	Defines decoding details, and can take on the following values described in the table below. Value Meaning TacNDJavaLib.ND_SPB_ENCODE_GEN_01 Generates a GEN 01 message. TacNDJavaLib.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. TacNDJavaLib.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. TacNDJavaLib.ND_SPB_RAW Mode without SPB-specific checks. Only accepts the use of the MAP name as parameters for szSrcISPB e szDstISPB.

Return

Exceptions

TacException