Encode and Decode operations according to the SPB standard.
The APIs of the SPB module are intended for encoding and decoding messages in the SPB (Brazilian Payment System) standard, in accordance with the RSFN (National Financial System Network) Security Manual published by BACEN (Central Bank of Brazil).
- Observation
- The current implementation is in line with version 5.0 of the RSFN Security Manual published by BACEN in June 2021.
The Brazilian Payment System (SPB) works on a system of message exchanges between financial institutions, on a private network called RSFN. The standards are defined and published by the Central Bank. All messages exchanged are encrypted and digitally signed, using a digital envelope scheme. The SPB module is responsible for handling message security.
- Observation
- The use of the SPB module in a scenario with several HSMs must be done with the HSM replication mechanism configured and operational, so that the certificate base in the HSMs is always synchronized and intact, regardless of which HSM was used by the application in each operation.
The SPB module basically performs three functions: Encode and Decode in SPB messages, and management of SPB certificates.
Encode is performed on the messages going to the output queue and consists of:
- Sign the content (hash) of the message with the private key corresponding to the institution's own certificate (origin);
- Generate a symmetric session key;
- Cipher the message with the symmetric key;
- Cipher the symmetric key with the public key in the certificate of the institution receiving the message;
- Set up the security header;
- Deliver the result header+encrypted message to the application, which will put everything in an output queue;
Decode does the reverse process, acting on messages that arrive in the input queue;
- It receives the encrypted message and the SPB header;
- Decrypts the symmetric key with the institution's own private key (destination)
- Decrypts the message with the symmetric key;
- Verifies the digital signature with the public key in the certificate of the sending institution (origin)
- Delivers the open message to the application;
Every operation with public and private keys is linked to the use of X.509 certificates, so in addition to Encode and Decode the SPB module also needs to have some certificate management.
Each institution is identified in the SPB by its ISPB code (8 digits) and can exchange messages in so-called message domains, each of which requires a different certificate. Each institution can only have one active certificate at a time in a domain.
In the SPB module, institutions (and their equivalent certificates) can only be identified by the ISPB code.
The SPB module is responsible for encrypting messages in accordance with BACEN definitions, and the SPB communication structure can be used by other systems between financial institutions motivated by the emergence of new applications within BACEN, for example:
- SPB operates the STR - Resource Transfer System (STR01)
- MES operates Sisbacen (MES01, MES02)
- CIP operates the SCG - Guarantee Control System and C3 - Central Credit Assignment System. Each of these systems can have a key/certificate and will be treated as a domain in the messaging control application. If the institution operates more than one ISPB, each of them must access a separate key partition within the HSM. There are cases where an institution can operate MES/SPB with the same key/certificate.
In HSM, certificate management is done using Maps, which are pointing and reference objects. All references in the SPB module are to Maps, not to keys and certificates.
Regarding the internal naming described below, the idea is that keys, certificates and maps are managed by the specialized SPB functions of the HSM client library, so that these naming rules are completely transparent to the application, which only needs to search for the ISPB code.
Keeping Certificates
If the Encode and Decode functions only needed to handle messages using active certificates, it would be enough to keep these certificates in the base, but there are cases, such as an auditing process, where the application needs to open or verify the signature of an old message that was generated using a certificate that has already been deactivated (or will still be activated in the future). This is why HSM needs to keep and accumulate all the certificates in the base, both its own and those of third parties, as they are imported, activated and deactivated.
UTF-16 BE format in XML
The BACEN manual specifies that XML messages must be represented in Unicode UTF-16 BE format. For mod_SPB it doesn't matter, since the content that will be signed and encrypted in the Encode will be exactly that sent by the user, the HSM does not perform automatic text conversion either in the Encode or the Decode.
Special treatment indication flags in the SPB header
The BACEN manual mentions messages and file pointers that can be included in the content of an SPB message. The difference is that XML messages must be represented in UTF16-BE format, while files do not have this requirement.
This distinction between message and file is important for the caller, as they will decide whether they need to convert the format or not before sending it to the HSM.
In the case of messages indicating compressed content, the premise of the implementation is that the sender has the necessary compression infrastructure, so the HSM signs and encrypts what the application passes in Encode, while in the case of the recipient the premise is that they may not have the decompression infrastructure at hand, so the HSM decompresses the content in Decode and delivers the decompressed content, including automatically detecting whether the standard used is gzip or pkzip.
All messages sent are signed, and some may be for public use, with no specified recipient.
C04 | Message | Archive | Signed | Ciphered | Zipped | Recipient | Encode | Decode |
0 | x | | x | x | | | | |
1 | x | | x | x | | | use cert not yet activated | use cert not yet activated |
2 | x | | x | | | public | accepts blank destination | accepts blank destination |
3 | x | | x | | | | | |
4 | | x | x | | | | | |
6 | | x | x | | | public | accepts blank destination | accepts blank destination |
8 | | x | x | x | x | | you should already receive it zipped | unzips automatically |
10 | | x | x | | x | public | you should already receive it zipped | unzips automatically |
Automatic SPB message handling for certificate exchange
By Bacen's definition, the exchange and activation of SPB certificates is done within the system using specific messages.
The HSM can detect this type of message in Decode and promote the exchange of the certificate on the HSM's base automatically, without the application having to explicitly call the certificate activation API.
This is a parameterization option for the Decode call.
The HSM will handle the GEN0007 decode (certificate update notice via BACEN broadcast), the response to a GEN0008 (a digital certificate query, the response to which is a GEN0008R1), the response to a GEN0006 as well as the GEN0018 (BACEN certificate). For HSM, GEN0007 and the answer to GEN0008 are equivalent. In the case of GEN0018, the certificate in the message is imported, but it is not activated automatically, because the manual specifies that BACEN sends the messages at least 03 days before activation; so the application is responsible for controlling the time between receipt and activation; and to activate it is enough to inform CA and NS, because the certificate will already be imported into the HSM base.
The GEN0006 message is used by institutions to inform BACEN of the activation or update of the status of a certificate. In the HSM, the response to this message (GEN0006R1) has special treatment to promote the activation of the certificate (as of firmware version 5.0.16).
The normal operation flow for activating a new certificate involves a GEN0006 message from the institution to BACEN, which then sends a GEN0007 broadcast message informing all participants that the institution's certificate must be changed. As the institution itself also receives this GEN0007, it is at this point (during Decode) that the application can instruct the HSM to automatically activate the new certificate in its local base.
Certificate format
Internally, HSM only operates, imports and exports certificates in DER (binary) format, but in the library the certificate import operations support both DER and PEM (base64) format, with automatic detection.
Nomenclature
The HSM SPB module allows you to perform encoding and decoding operations on SPB messages using keys and certificates within the HSM.
This means that the entire base of certificates and private keys of the institution itself and of the institutions with which the bank communicates will be stored and centralized in the HSM, without the need for external control.
The identification of the keys and certificates to be used is done using the ISPB code of the institutions in a way that is natural for the calling applications, instead of the common model of using the native identifiers of the keys and certificates.
To make this relationship of ISPB with keys and certificates, an object in the HSM called map was used, which simply links an ISPB to a private key and/or a certificate. This makes it possible to pass only the ISPB to an SPB encoding call instead of a key name.
Internal nomenclature for keys and certificates
In order to make it easier to use, a formation law is defined for the names of these objects.
For the key names:
k_<ISPB>_<dom>_<yyyymmddhhmmss>
k:
01 character, literal
<ISPB>
: 08 characters, ISPB code
<dom>
: up to 05 characters, domain
<yyyyymmddhhmmss>
: 14 characters, GMT timestamp when the key was generated.
Total: up to 31 characters, e.g: k_12345678_str01_20131029110223
For certificate names:
c_<ISPB>_<dom>_<yyyymmddhhmmss>
c:
01 character, literal
<ISPB>
: 08 characters, ISPB code
<dom>
: up to 05 characters, domain
<yyyymmddhhmmss>
: 14 characters, GMT timestamp when the certificate was imported.
Total: up to 31 characters, e.g: c_12345678_spb_20131101120334
The same training law applies to third-party certificates.
Map
The map is simply an internal HSM object that stores the Ids of two other objects. In the case of the SPB module, it stores the Id of the certificate and the Id of the private key. Each Id occupies a position within the map called a slot.
SPB internal map nomenclature
Since every message involves certificate processing, the SPB module needs a way of uniquely identifying each certificate for each institution in each domain. According to the Bacen standard, each certificate has a serial number (SN) of up to 32 bytes, defined by the Certificate Authority (CA) that issues it, but there is no guarantee that serial numbers are globally unique, so the identification of the certificate needs to include information on the CA (each CA in the SPB has an identification byte) and the NS, which exceeds the 32-character limit for HSM identifiers; RFC 3280 also makes this distinction to uniquely identify a certificate. The Ids of the certificate maps used in the SPB module use a name compression scheme.
The solution adopted is an MD5 hash, which is exactly 16 bytes long (32 characters) and does not produce a collision for this use case. The definition of what will go into the composition of the hash is (CA+NS), where CA and SN are composed of uppercase hexadecimal characters.
- CA has size 2, representing one byte.
- SN has size 32 and must be completed with zero padding to the left (according to SPB security manual 3.2) when the SN size of the certificate is less than 32.
- CA+SN concatenation must be done without counting NULL terminators. Active certificate maps will be identified as <ISPB>_<dom> in the HSM base, and the application will refer to them as
ISPB@dom
. O @
is adopted to improve naming on the client, internally in the firmware @
is translated into _
.
The use of @dom by the calling application is optional; the institution may not use application domains.
From the point of view of the calling application, it can refer to maps as ISPB@dom
or CA@NS
to use the same Encode/Decode API. The HSM library detects this automatically.
Maps allow slots to point to an FQN, meaning that the certificate and key can be in different partitions. In any case, the map must always exist in the partition of the logged-in user, even if the ids pointed to in the slots are in another partition. In principle, the best way to use it is to keep all the certificates and keys of an ISPB on the same partition, without references to remote partitions.
To make it easier to identify objects and search for ISPBs, active certificates and certificate+private key pairs have a MAP with the ISPB identifier.
All certificates and certificate+private key pairs, regardless of whether they are active or not, have a MAP with MD5 id (CA+SN) for identification and history, where CA is the identifier of the Certificate Authority and SN is the certificate's serial number.
The name of the map object is the identifier of the institution, which can be of 2 types:
- CA@SN
- CA (Certificate Authority) and NS (Serial Number) of the certificate.
- An MD5 hash is made of this data and the result is the name of the MAP.
- This map is automatically generated for all certificates and certificate + private key pairs when imported via SPB APIs (e.g. DSPBImportCertificate(), ...).
- Example:
03@00000000000000000000000087654321
- ISPB@Dominio
- A map-specific name is generated using ISPB and DOMINIO.
- The domain is not mandatory. Identifiers can only be created with ISPB.
- This type of map is only generated for active certificates and certificate+key pairs.
- Removing this map makes the corresponding certificate inactive.
- Example:
12345678@MES01
The API documentation states whether both types of identifier are accepted or just one of them.
Multiple partitions
If you want to use objects in other users' partitions, you must specify the partition id in the identifier.
The indication is made by adding the name of the partition where the objects are located at the beginning of the identifier, separated by /
.
Example: usuario/12345678@MES01
Encode
The sequence of APIs DSPBEncodeInit(), DSPBEncodeCont() and DSPBEncodeEnd() perform an SPB message encoding operation.
The call structure with init/cont/end sequence allows the calling application to use the API with any message size, including large files.
The use of parameters with source and destination ISPB identifiers in APIs aims to increase the level of verification between what the application actually has (the SPB message) and what it thinks it has (the API parameters).
The encryption operation does not change the message representation format, so the application must send the message as defined by the Central Bank (e.g. UTF-16BE). The message will be encrypted and signed as it is received.
Decode
The sequence of APIs DSPBDecodeInit(), DSPBDecodeCont() and DSPBDecodeEnd() perform an SPB message decoding operation.
The call structure with init/cont/end sequence allows the calling application to use the API with any message size.
The use of source and destination ISPB parameters in APIs is intended to increase the level of verification between what the application actually has (the SPB message) and what it thinks it has (the API parameters).
During the decode, the HSM firmware is able to detect that the message is about a certificate change and perform this update and activation automatically (without the need for further action by the application), so the bAutoUpdateCert flag must be set.
The decoding operation does not change the message representation format. The message will be passed to the application as it was deciphered.
SPB Module Graphical Management Console
To facilitate management and abstract away the more complex details of the SPB module, the HSM manufacturer provides a graphical console. Through it, all operations relating to loading and activating certificates, generating keys and certificate requests, creating and viewing domains, permitting partitions and many others can be easily carried out.
Check with your supplier about the availability of the HSM SPB Management Console.
More details in the equipment documentation.
|
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.
|
|
◆ SPBListObjects()
Lists objects of a certain type (key, certificate, etc.).
- Parameters
-
- 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. Only accepts 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()
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.