SPB

The SPB module APIs are designed for encoding and decoding (encode and decode) messages in the SPB (Brazilian Payment System) standard, as per the Security Manual of the RSFN (National Financial System Network) published by BACEN (Central Bank of Brazil).

Info

The current implementation complies with version 5.0 of the RSFN Security Manual, published by BACEN in June 2021.

The (SPB) Brazilian Payment System operates using a message queuing system for exchanges between financial institutions over a private network called RSFN. Standards are defined and published by the Central Bank. All exchanged messages are encrypted and digitally signed, employing a digital envelope scheme. The SPB module will primarily address the security of these messages.

Info

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 complete, regardless of which HSM was used by the application in each operation.

The SPB module essentially performs three functions: Encode and Decode for SPB messages, and SPB certificate management.

The Encode operation is performed on messages destined for the output queue and consists of:

Sign the message content (hash) with the private key corresponding to the institution's own certificate (origin);
Generate a symmetric session key;
Encrypt the message with the symmetric key;
Encrypt the symmetric key with the public key from the message recipient institution's certificate;
Assemble the security header;
Deliver the resulting header + encrypted message to the application, which will place everything in an output queue;

The Decode process performs the inverse operation, acting upon messages arriving in the input queue;

Receives the encrypted message and the SPB header;
Decrypts the symmetric key with the private key of the institution itself (destination);
Decrypts the message with the symmetric key;
Verifies the digital signature with the public key from the sender institution's certificate (origin);
Delivers the plaintext message to the application;

All operations involving public and private keys are linked to the use of X.509 certificates; therefore, in addition to Encode and Decode, the SPB module also needs to have some certificate management capabilities.

Each institution is identified in the SPB by the ISPB code (8 digits) and can exchange messages in the 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 message encryption as defined by BACEN. Furthermore, the SPB communication structure can be leveraged by other systems among financial institutions, driven by the emergence of new applications within BACEN's purview, for example:

SPB operates the STR - Funds Transfer System (STR01)
MES operates Sisbacen (MES01, MES02)
CIP operates the SCG - Collateral 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 ISBP code.

Certificate Storage

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-16BE format

The BACEN manual specifies that XML messages must be represented in Unicode UTF-16BE format. It doesn't matter for HSM, since the content that will be signed and encrypted in Encode will be exactly that sent by the user.

Attention

HSM does not perform automatic format conversion, either at the Encode input or at the Decode output.

Special treatment

The 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 UTF-16BE 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 sent messages are signed, and some may be for public use, without a specified recipient.

C04	Recipient	Encode	Decode
0
1		uses certificate not yet activated	uses certificate not yet activated
2	public	accepts blank destination	accepts blank destination
3
4
6	public	accepts blank destination	accepts blank destination
8		must already be received zipped	performs automatic decompression
10	public	must already be received zipped	performs automatic decompression

Automatic Certificate Exchange

According to Bacen's definition, SPB certificate exchanges and activations are performed internally 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 decode of GEN0007 (certificate update notice via BACEN broadcast) and the response to a GEN0008 (a query to the digital certificate, whose response is a GEN0008R1), as well as 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, this message (and also the GEN0006R1 response) is not treated specially, as it does not require changes to the local base.

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 performed by leveraging the institutions' ISPB codes, providing a natural approach for calling applications, as opposed to the common model of using native key and certificate identifiers.

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.

Key nomenclature

To facilitate usage, a naming convention is defined for these objects.

Nomes de chaves: k_<ISPB>_<dom>_<yyyymmddhhmmss>
k: 01 character, literal
<ISBP>: 08 caracteres, código ISPB
<dom>: até 05 caracteres, domínio
<yyyymmddhhmmss>: 14 caracteres, timestamp GMT-0 do momento de geração da chave.

Total: up to 31 characters, e.g.: k_12345678_str01_20131029110223

Nomes de certificados: c_<ISPB>_<dom>_<yyyymmddhhmmss>
c: 01 character, literal
<ISBP>: 08 caracteres, código ISPB
<dom>: até 05 caracteres, domínio
<yyyymmddhhmmss>: 14 caracteres, timestamp GMT-0 do momento de importação do certificado.

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.

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 a size of 2, representing one byte.
The SN must be 32 characters long and should be left-padded with zeros (according to SPB 3.2 security manual) if the certificate's SN length is less than 32.
The CA+SN concatenation must be performed without including NULL terminators.

Os maps de certificados ativos serão identificados como <ISPB>_<dom> na base do HSM, e a aplicação vai se referenciar a eles como ISPB@dom. O @ é adotado para melhorar a nomenclatura no cliente, internamente no firmware @ é traduzido para _.

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 reference the 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 a Fully Qualified Name (FQN), meaning the certificate and key can reside in different partitions. In any case, the map must always exist in the connected user's partition, even if the IDs referenced in the slots are in another partition. Primarily, the best practice is to keep all certificates and keys for an ISPB within the same partition, without references to remote partitions.

To facilitate object identification and ISPB lookup, active certificates and certificate+private key pairs are associated with a MAP using 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, which serves as the institution's identifier, can be one of two types:

CA@SN
- CA (Certificate Authority) and SN (Serial Number) of the certificate.
- An MD5 hash of this data is performed, and the result is the MAP name.
- 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@Domain
- A specific map name is generated using the ISPB and the DOMAIN.
- The domain is not mandatory. Identifiers can be created with ISPB only.
- 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 specifies whether both types of identifiers are accepted or only one of them.

Multiple Partitions

To use objects in other users' partitions, the partition ID must be specified in the identifier.

This is indicated by adding the name of the partition where the objects are located at the beginning of the identifier, separated by /.

Exemplo: usuario/12345678@MES01

Encode

The sequence of APIs DSPBEncodeInit(), DSPBEncodeCont() and DSPBEncodeEnd() perform an SPB message encoding operation.

The call structure employing the init/cont/end sequence enables the calling application to utilize the API with messages of any size, including large files.

The use of parameters with source and destination ISBP identifiers in the APIs aims to increase the level of consistency between what the application actually possesses (the SPB message) and what it presumes to have (the API parameters).

The encoding operation does not alter the message's representation format; therefore, the application must send the message according to the Central Bank's definition (e.g., UTF-16BE). The message will be encrypted and signed exactly as received.

Decode

The sequence of APIs DSPBDecodeInit(), DSPBDecodeCont( ) and DSPBDecodeEnd() perform an SPB message decoding operation.

The init/cont/end call sequence structure allows the calling application to use the API with any message size.

The use of source and destination ISBP parameters in the APIs aims to increase the level of conformance between what the application actually possesses (the SPB message) and what it believes 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 alter the message's representation format. The message will be passed to the application exactly as it was deciphered.

Graphical Console

To facilitate management and abstract away the more complex details of the SPB module, the HSM manufacturer provides a graphical console (SPBSec 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.

See the Downloads page for the SPB module's graphical console (SPBSec Console).

The following displays some screenshots of the interfaces.

Trade Name

See the Modules topic for the current commercial name of the module; it will be used in presentations, marketing and promotional material, commercial proposals, and contracts.

License

See the Licenses and Modules topics for information on whether a specific license is required to use the module's APIs and what the name of this license is.

API SPB

Specific API documentation for the SPB module, with functions, classes and examples.

C/C++

API C/C++
Java

Java API
.NET

NET API