 |
C/C++ API
HSM Dinamo
|
|
C/C++ API
HSM Dinamo
|
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).
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.
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:
Decode does the reverse process, acting on messages that arrive in the input queue;
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:
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.
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.
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.
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 |
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.
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.
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.
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.
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.
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.
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@NSto 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:
03@00000000000000000000000087654321 12345678@MES01 The API documentation states whether both types of identifier are accepted or just one of them.
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
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.
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.
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.
Encode and Decode operations according to the SPB standard. More...
Functions | |
| int AAP_API | DSPBEncodeInit(HSESSIONCTX hSession, char *szSrcISPB, char *szDstISPB, DWORD dwTotalDataLen, BYTE bErrorCode, BYTE bSpecialTreatment, HSPBCTX *hSPBCtx, DWORD dwFlags) |
| int AAP_API | DSPBEncodeCont(HSPBCTX hSPBCtx, BYTE *pbDataIn, DWORD dwDataInLen, BYTE *pbDataOut, DWORD *pdwDataOutLen) |
| int AAP_API | DSPBEncodeEnd(HSPBCTX *hSPBCtx, BYTE *pbSPBHeader, DWORD *pdwSPBHeaderLen) |
| int AAP_API | DSPBDecodeInit(HSESSIONCTX hSession, char *szSrcISPB, char *szDstISPB, BYTE *pbHeader, DWORD dwHeaderLen, BYTE bAcceptExpiredCert, BYTE bAutoUpdateCert, DWORD dwMessageDataLen, HSPBCTX * hSPBCtx, DWORD dwFlags) |
| int AAP_API | DSPBDecodeCont(HSPBCTX hSPBCtx, BYTE *pbDataIn, DWORD dwDataInLen, BYTE **ppbDataOut, DWORD *pdwDataOutLen) |
| int AAP_API | DSPBDecodeEnd(HSPBCTX *hSPBCtx) |
| int AAP_API | DSPBGenerateKey(HSESSIONCTX hSession, char *szID, char *szPrivateKeyName, DWORD dwKeyParam, DWORD dwParam) |
| int AAP_API | DSPBGenerateCSR(HSESSIONCTX hSession, char *szPrivateKeyName, BYTE bVersion, char *szSPBSubject, DWORD dwOutType, DWORD *pdwCSRLen, BYTE **ppbCSR, DWORD dwParam) |
| int AAP_API | DSPBImportCertificate(HSESSIONCTX hSession, BYTE bActivate, const char *szUser, BYTE *pbCertificate, DWORD dwCertificateLen, const char *szDomain, DWORD dwParam) |
| int AAP_API | DSPBImportPKCS12(HSESSIONCTX hSession, BYTE bActivate, const char *szUser, const char *szPkcs12File, const char *szPkcs12Pwd, const char *szDomain, DWORD dwKeyAttr) |
| int AAP_API | DSPBExportPKCS12 (const HSESSIONCTX hSession, const char *szPkcs12Pwd, const char *szISPB, const char *szReserved, BYTE **ppbPkcs12, DWORD *pdwPkcs12Len, DWORD dwReserved) |
| int AAP_API | DSPBActivateCertificate(HSESSIONCTX hSession, const char *szIdCert, const char *szDomain, DWORD dwParam) |
| int AAP_API | DSPBGetCertificate(HSESSIONCTX hSession, const char *szIdCert, BYTE **ppbCertificate, DWORD *pdwCertificateLen, DWORD dwParam) |
| int AAP_API | DSPBCalculateObjectId (char *szISPB, char *szDomain, DWORD dwKeyType, char *szOutObjName, DWORD dwParam) |
| int AAP_API | DSPBMapInfo(HSESSIONCTX hSession, const char *szIdCert, EXT_MAP_2_OBJ_INFO *pstExtMap, DWORD dwParam) |
| int AAP_API | DSPBSetISPBMap(HSESSIONCTX hSession, char *szISPB, char *szKeyId, char *szCertId, DWORD dwParam) |
| int AAP_API DSPBEncodeInit | ( | HSESSIONCTX | hSession, |
| char * | szSrcISPB, | ||
| char * | szDstISPB, | ||
| DWORD | dwTotalDataLen, | ||
| BYTE | bErrorCode, | ||
| BYTE | bSpecialTreatment, | ||
| HSPBCTX * | hSPBCtx, | ||
| DWORD | dwFlags ) |
#include <dinamo.h>
Starts an SPB message encoding operation.
| [in] | hSession | Context acquired through the DOpenSession() function. | ||||||||||||||
| [in] | szSrcISPB | Source institution identifier with maximum size MAX_OBJ_ID_FQN_LEN. The source identifier must have the following format: ISPB@DOMINIO, with the domain part being optional. The exact size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN. The name of the corresponding map, outside the SPB module naming standard, can also be passed on in specific cases, see dwFlags. | ||||||||||||||
| [in] | szDstISPB | Destination institution identifier maximum size MAX_OBJ_ID_FQN_LEN. The destination identifier must have the following format: ISPB@DOMINIO, with the domain part being optional. The size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN. The name of the corresponding map, outside the SPB module naming standard, can also be passed on in specific cases, see dwFlags. | ||||||||||||||
| [in] | dwTotalDataLen | Total size in bytes of the message to be encoded. | ||||||||||||||
| [in] | bErrorCode | Message error code to be placed in the security header, usually in reply messages. | ||||||||||||||
| [in] | bSpecialTreatment | Special message handling code, according to the Central Bank manual. | ||||||||||||||
| [out] | hSPBCtx | Pointer to the context of the SPB encoding operation. After use, it must be freed with the DSPBEncodeEnd() function. | ||||||||||||||
| [in] | dwFlags | Defines coding details and can take on the following values described in the table below.
|
| int AAP_API DSPBEncodeCont | ( | HSPBCTX | hSPBCtx, |
| BYTE * | pbDataIn, | ||
| DWORD | dwDataInLen, | ||
| BYTE * | pbDataOut, | ||
| DWORD * | pdwDataOutLen ) |
#include <dinamo.h>
Sends parts or all of the message for encoding in the HSM.
| [in] | hSPBCtx | Context acquired through the DSPBEncodeInit() function. |
| [in] | pbDataIn | Buffer containing part or all of the message to be encoded. The size per call is DN_SPB_MAX_NOTIFY_DATA_SEG bytes. Smaller sizes can be sent if it is the last or only piece of the message. |
| [in] | dwDataInLen | Buffer size in bytes pbDataIn. |
| [out] | pbDataOut | Buffer that will receive the encoded message data. It must be equal to or greater than pbDataIn.If it is the last piece, add space in the size for possible padding/tag. We recommend using a minimum size of DN_SPB_MAX_RCV_NOTIFY_DATA_SEG bytes to ensure that all returned data is received. |
| [in,out] | pdwDataOutLen | Pointer to a DWORD that contains the size of pbDataOut.The input must contain the size of the buffer pointed to by pbDataOut, the output contains the size of the data that was encoded in pbDataOut. |
#include <dinamo.h>
Completes an SPB encryption operation and receives the security header.
| [in] | hSPBCtx | Pointer to the context acquired through the DSPBEncodeInit() function. |
| [out] | pbSPBHeader | Buffer containing the security header of the encoded message. It must have a size equal to or greater than DN_SPB_MSG_HEADER_V2_LEN bytes. |
| [in,out] | pdwSPBHeaderLen | Pointer to a DWORD that on input should contain the size of the buffer pointed to by pbSPBHeader, and on output will contain the size of the header written in pbSPBHeader. |
| int AAP_API DSPBDecodeInit | ( | HSESSIONCTX | hSession, |
| char * | szSrcISPB, | ||
| char * | szDstISPB, | ||
| BYTE * | pbHeader, | ||
| DWORD | dwHeaderLen, | ||
| BYTE | bAcceptExpiredCert, | ||
| BYTE | bAutoUpdateCert, | ||
| DWORD | dwMessageDataLen, | ||
| HSPBCTX * | hSPBCtx, | ||
| DWORD | dwFlags ) |
#include <dinamo.h>
Starts an SPB message decoding operation.
| [in] | hSession | Context acquired through the DOpenSession() function. | ||||||||||||||
| [in] | szSrcISPB | Source institution identifier with maximum size MAX_OBJ_ID_FQN_LEN. The source identifier must have the following format: ISPB@DOMINIO, with the domain part being optional. The exact length for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN. You can also pass the name of the corresponding map, outside the SPB module's naming standard in specific cases, see dwFlags. | ||||||||||||||
| [in] | szDstISPB | Destination institution identifier with maximum size MAX_OBJ_ID_FQN_LEN. The destination identifier must have the following format: ISPB@DOMINIO. The size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the identifier of the DOMAIN. You can also pass the name of the corresponding map, outside the SPB module's naming standard in specific cases, see dwFlags. | ||||||||||||||
| [in] | pbHeader | Buffer containing the security header of the SPB message to be decoded. | ||||||||||||||
| [in] | dwHeaderLen | Size in bytes of the pbHeader buffer. | ||||||||||||||
| [in] | bAcceptExpiredCert | Byte to accept expired certificates when decoding the message. Pass 1 to accept and 0 to not accept. | ||||||||||||||
| [in] | bAutoUpdateCert | Enables or disables the automatic updating of certificates in the HSM database if the message is about a certificate change. The following messages are currently handled: GEN0006 (reply), GEN0007, GEN0008 (reply) and GEN0018. The certificate is imported and activated automatically, except in the case of GEN0018 (Central Bank certificate), where the certificate is imported but not activated. Enter 1 for enabled and 0 for disabled. | ||||||||||||||
| [in] | dwMessageDataLen | Total size of the SPB message to be decoded. | ||||||||||||||
| [out] | hSPBCtx | Pointer to the context of the SPB decode operation. After use, it must be released with the DSPBDecodeEnd() function. | ||||||||||||||
| [in] | dwFlags | Defines decoding details, and can take on the following values described in the table below.
|
| int AAP_API DSPBDecodeCont | ( | HSPBCTX | hSPBCtx, |
| BYTE * | pbDataIn, | ||
| DWORD | dwDataInLen, | ||
| BYTE ** | ppbDataOut, | ||
| DWORD * | pdwDataOutLen ) |
#include <dinamo.h>
Sends parts or all of the message for decoding in the HSM.
| [in] | hSPBCtx | Context acquired through the DSPBDecodeInit function. |
| [in] | pbDataIn | Buffer containing part or all of the message to be decoded. The size per call is ND_SPB_MAX_NOTIFY_DATA_SEG bytes. Smaller sizes can be sent if it is the last or only piece of the message. |
| [in] | dwDataInLen | Buffer size in bytes pbDataIn. |
| [out] | ppbDataOut | Pointer that will receive the encoded data. The size of the allocated buffer is available via pdwDataOutLen. Memory allocation is done internally. Deallocation is done in the next call to DSPBDecodeCont() or DSPBDecodeEnd(). |
| [out] | pdwDataOutLen | Pointer to the size of the buffer allocated internally in ppbDataOut. |
#include <dinamo.h>
Completes an SPB decoding operation and receives the security header.
| [in] | hSPBCtx | Pointer to the context acquired via the DSPBDecodeInit() function. |
| int AAP_API DSPBGenerateKey | ( | HSESSIONCTX | hSession, |
| char * | szID, | ||
| char * | szPrivateKeyName, | ||
| DWORD | dwKeyParam, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Generates a private key in the SPB standard. This is a specialized function of the HSM key generation API.
The application generates the key (RSA 2048 or as established in the updated Bacen manual) with the identification following the internal formation law, described in the SPB module presentation.
| [in] | hSession | Context acquired through the DOpenSession() function. |
| [in] | szID | Identifier of the institution for which the private key is intended. The institution identifier must have the following format: "ISPB@DOMINIO", with the domain part being optional. The exact length for ISPB is ND_SPB_ISPB_LEN and the maximum length for DOMINIO is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the DOMAIN identifier. |
| [out] | szPrivateKeyName | Buffer of size MAX_OBJ_ID_FQN_LEN or more. This buffer will receive a string containing the identifier of the key pair generated within the HSM. This identifier must be kept by the application for later use in DSPBGenerateCSR() and/or others. |
| [in] | dwKeyParam | Additional key parameters. See the options in the DGenerateKey() function. |
| [in] | dwParam | Reserved for future use (must be 0). |
| int AAP_API DSPBGenerateCSR | ( | HSESSIONCTX | hSession, |
| char * | szPrivateKeyName, | ||
| BYTE | bVersion, | ||
| char * | szSPBSubject, | ||
| DWORD | dwOutType, | ||
| DWORD * | pdwCSRLen, | ||
| BYTE ** | ppbCSR, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Generates a CSR (Certificate Signing Request) for SPB. This is a specialized function of HSM's PKCS#10 CSR generation API.
There are no validation rules for SPB certificates; this is up to the application, which can generate CSRs for different systems, such as SPB and CIP.
| [in] | hSession | Context acquired through the DOpenSession() function. | ||||||||||||||
| [in] | szPrivateKeyName | Identifier of the private key. Normally the string generated in DSPBGenerateKey(). | ||||||||||||||
| [in] | bVersion | CSR version PKCS#10. The following table is supported.
| ||||||||||||||
| [in] | szSPBSubject | DN (Dinstinguished Name), for generating the CSR, with a maximum size of CORE_P10_CSR_DN_MAX_LEN. DN fields must be separated by '/'. | ||||||||||||||
| [in] | dwOutType | CSR output type. The following table is supported.
| ||||||||||||||
| [out] | pdwCSRLen | Pointer to the size of the buffer allocated in ppbCSR. | ||||||||||||||
| [out] | ppbCSR | Pointer that will receive the CSR. The size of the allocated buffer will be available via pdwCSRLen. Memory allocation is done internally. The calling application is responsible for freeing the allocated memory using the DFree() API. | ||||||||||||||
| [in] | dwParam | Additional parameters. The following table is supported.
|
| int AAP_API DSPBImportCertificate | ( | HSESSIONCTX | hSession, |
| BYTE | bActivate, | ||
| const char * | szUser, | ||
| BYTE * | pbCertificate, | ||
| DWORD | dwCertificateLen, | ||
| const char * | szDomain, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
It imports an SPB certificate and associates it with a key pair within the HSM (via a map object), if such a key exists.
| [in] | hSession | Context acquired through the DOpenSession() function. | ||||||||
| [in] | bActivate | Automatically activates the certificate when importing. Enter 1 to activate and 0 to import without activating the certificate. | ||||||||
| [in] | szUser | User name, for importing the certificate, with maximum length(MAX_USR_LEN+1). It can be NULL if the import is made from the user's current session. | ||||||||
| [in] | pbCertificate | Buffer containing the certificate to be imported. The certificate can be in PEM or DER format. | ||||||||
| [in] | dwCertificateLen | Size of the buffer pointed to by pbCertificate. | ||||||||
| [in] | szDomain | Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1). Can be NULL if no domain is defined. | ||||||||
| [in] | dwParam | The following table of flags is supported.
|
| int AAP_API DSPBImportPKCS12 | ( | HSESSIONCTX | hSession, |
| BYTE | bActivate, | ||
| const char * | szUser, | ||
| const char * | szPkcs12File, | ||
| const char * | szPkcs12Pwd, | ||
| const char * | szDomain, | ||
| DWORD | dwKeyAttr ) |
#include <dinamo.h>
Import a key pair and a certificate from a PKCS#12 file.
| [in] | hSession | Context acquired through the DOpenSession() function. |
| [in] | bActivate | Automatically activates the certificate when importing. Enter 1 to activate and 0 to import without activating the certificate. |
| [in] | szUser | Name of the user where the key will be created. Can be NULL if the key is created on the authenticated user. |
| [in] | szPkcs12File | PKCS#12 file name for import. |
| [in] | szPkcs12Pwd | PKCS#12 file password for import. |
| [in] | szDomain | Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1). cMay be NULL if no domain is defined. |
| [in] | dwKeyAttr | Additional key parameters. See the options in the DGenerateKey() function. |
| int AAP_API DSPBExportPKCS12 | ( | const HSESSIONCTX | hSession, |
| const char * | szPkcs12Pwd, | ||
| const char * | szISPB, | ||
| const char * | szReserved, | ||
| BYTE ** | ppbPkcs12, | ||
| DWORD * | pdwPkcs12Len, | ||
| DWORD | dwReserved ) |
#include <dinamo.h>
Exports a key pair and a certificate in PKCS#12 format from an HSM.
| [in] | hSession | Context acquired through the DOpenSession() function. . |
| [in] | szPkcs12Pwd | Password for PKCS#12 file. Pass NULL to generate PKCS#12 without password. |
| [in] | szISPB | Certificate identifier/private key in CA@SN, ISPB or ISPB@DOM format. |
| [in] | szReserved | Reserved for future use (must be NULL). |
| [out] | ppbPkcs12 | Pointer to a pointer that will contain the generated PKCS#12. This data area will be allocated internally and must be freed using DFree(). |
| [out] | pdwPkcs12Len | Pointer to the size of the data written in ppbPkcs12. |
| [in] | dwReserved | Reserved for future use (must be 0). |
| int AAP_API DSPBActivateCertificate | ( | HSESSIONCTX | hSession, |
| const char * | szIdCert, | ||
| const char * | szDomain, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Activates an SPB certificate in the HSM.
| [in] | hSession | Context acquired through the DOpenSession() function. |
| [in] | szIdCert | Identifier of the certificate to be activated. The certificate identifier must have the following format: CA@SN. The size for CA is ND_SPB_CA_LEN and the size for SN is ND_SPB_SN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 03@12345678 where 03 is the CA identifier and 12345678 is the certificate serial number. |
| [in] | szDomain | Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1). Can be NULL if no domain is defined. |
| [in] | dwParam | Reserved for future use. |
| int AAP_API DSPBGetCertificate | ( | HSESSIONCTX | hSession, |
| const char * | szIdCert, | ||
| BYTE ** | ppbCertificate, | ||
| DWORD * | pdwCertificateLen, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Activates an SPB certificate in the HSM.
| [in] | hSession | Context acquired through the DOpenSession() function. |
| [in] | szIdCert | Identification of the certificate to be recovered. The certificate identifier can have the following formats: ID, CA@SN or ISPB@DOMINIO. The exact size for CA is ND_SPB_CA_LEN and the maximum size for SN is ND_SPB_SN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 03@12345678 where 03 is the CA identifier and 12345678 is the institution's ISPB. The exact size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMINIO is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the DOMAIN identifier. |
| [out] | ppbCertificate | Pointer that will receive the certificate. The size of the allocated buffer will be available through pdwCertificateLen. Memory allocation is done internally by the library. The calling application is responsible for freeing the allocated memory using the DFree() API. |
| [out] | pdwCertificateLen | Pointer to the buffer size pointed to by ppbCertificate. |
| [in] | dwParam | Reserved for future use (must be 0). |
| int AAP_API DSPBCalculateObjectId | ( | char * | szISPB, |
| char * | szDomain, | ||
| DWORD | dwKeyType, | ||
| char * | szOutObjName, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Auxiliary API that calculates (locally) an object name in the SPB module's standard format.
| [in] | szISPB | ISPB of the institution. It must have a size of(ND_SPB_ISPB_LEN +1). | ||||||
| [in] | szDomain | Message domain of the certificate to be activated. Must have a maximum size of(ND_SPB_DOMAIN_MAX_LEN + 1). Can be NULL if no domain is defined. | ||||||
| [in] | dwKeyType | Type of name to be generated. The values in the following table will be accepted.
| ||||||
| [out] | szOutObjName | Buffer of size MAX_OBJ_ID_FQN_LEN that will contain the calculated object name. | ||||||
| [in] | dwParam | Reserved for future use (must be 0). |
| int AAP_API DSPBMapInfo | ( | HSESSIONCTX | hSession, |
| const char * | szIdCert, | ||
| EXT_MAP_2_OBJ_INFO * | pstExtMap, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Auxiliary API that retrieves information from a MAP SPB.
| [in] | hSession | Context acquired through the DOpenSession() function. |
| [in] | szIdCert | Identification of the certificate to be recovered. The certificate identifier can have the following formats: ID, CA@SN or ISPB@DOMINIO. The exact size for CA is ND_SPB_CA_LEN and the maximum size for SN is ND_SPB_SN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 03@12345678 where 03 is the CA identifier and 12345678 is the certificate serial number. The exact size for ISPB is ND_SPB_ISPB_LEN and the maximum size for DOMAIN is ND_SPB_DOMAIN_MAX_LEN. The maximum size for the identifier is ND_SPB_ID_MAX_LEN. Example: 12345678@MES01 where 12345678 is the institution's ISPB and MES01 is the DOMAIN identifier. |
| [out] | pstExtMap | Pointer to an EXT_MAP_2_OBJ_INFO that will contain the information of the requested MAP. |
| [in] | dwParam | Reserved for future use (must be 0). |
| int AAP_API DSPBSetISPBMap | ( | HSESSIONCTX | hSession, |
| char * | szISPB, | ||
| char * | szKeyId, | ||
| char * | szCertId, | ||
| DWORD | dwParam ) |
#include <dinamo.h>
Auxiliary API that creates or modifies an SPB map. The map is identified from the CA and NS data of the certificate provided.
| [in] | hSession | Context acquired through the DOpenSession() function. | ||||||||
| [in] | szISPB | ISPB of the institution. It must have a maximum size of MAX_OBJ_ID_FQN_LEN. | ||||||||
| [in] | szKeyId | Name of the institution's private key. Must have a maximum length of MAX_OBJ_ID_FQN_LEN. Can be NULL if you are only defining the certificate. | ||||||||
| [in] | szCertId | Name of the institution's certificate. Must have a maximum length of MAX_OBJ_ID_FQN_LEN. | ||||||||
| [in] | dwParam | The following table of flags is supported.
|