Operações de Encode e Decode conforme o padrão SPB. Mais...
Funções | |
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, char *szUser, BYTE *pbCertificate, DWORD dwCertificateLen, char *szDomain, DWORD dwParam) |
int AAP_API | DSPBImportPKCS12 (HSESSIONCTX hSession, BYTE bActivate, char *szUser, char *szPkcs12File, char *szPkcs12Pwd, 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, char *szIdCert, char *szDomain, DWORD dwParam) |
int AAP_API | DSPBGetCertificate (HSESSIONCTX hSession, 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, char *szIdCert, EXT_MAP_2_OBJ_INFO *pstExtMap, DWORD dwParam) |
int AAP_API | DSPBSetISPBMap (HSESSIONCTX hSession, char *szISPB, char *szKeyId, char *szCertId, DWORD dwParam) |
Descrição Detalhada
Operações de Encode e Decode conforme o padrão SPB.
As APIs do módulo SPB são destinadas às operações de codificação e decodificação de mensagens no padrão SPB (Sistema de Pagamentos Brasileiro), conforme o Manual de Segurança da RSFN (Rede do Sistema Financeiro Nacional) publicado pelo BACEN (Banco Central do Brasil).
- Observação
- A implementação atual está de acordo com a versão 3.2 do Manual de Segurança da RSFN publicado pelo BACEN em abril de 2013.
O (SPB) Sistema de Pagamentos Brasileiro funciona num sistema de filas de trocas de mensagens entre as instituições financeiras, numa rede privada chamada RSFN. Os padrões são definidos e publicados pelo Banco Central. Todas as mensagens trocadas são cifradas e digitalmente assinadas, usando um esquema de envelope digital. É no tratamento da segurança das mensagens que o módulo SPB vai atuar.
- Observação
- O uso do módulo SPB em cenário com vários HSMs deve ser feito com a mecanismo de replicação dos HSMs configurado e operacional, para que a base de certificados nos HSM esteja sempre sincronizada e íntegra, independente de qual dos HSMs foi utilizado pela aplicação em cada operação.
O módulo SPB realiza basicamente três funções: Encode e Decode nas mensagens SPB, e gerenciamento dos certificados SPB.
O Encode é executado sobre as mensagens que vão para a fila da saída e consiste em:
- Assinar o conteúdo (hash) da mensagem com a chave privada correspondente ao certificado da própria instituição (origem);
- Gerar um chave simétrica de sessão;
- Cifrar a mensagem com a chave simétrica;
- Cifrar a chave simétrica com a chave pública no certificado da instituição destinatária de mensagem;
- Montar o cabeçalho de segurança;
- Entregar o resultado cabeçalho+mensagem cifrada para a aplicação, que vai colocar tudo num fila de saída;
O Decode faz o processo inverso, atuando sobre mensagens que chegam na fila de entrada;
- Recebe a mensagem cifrada e o cabeçalho SPB;
- Decifra a chave simétrica com a chave privada da própria instituição (destino)
- Decifra a mensagem com a chave simétrica;
- Verifica a assinatura digital com a chave pública no certificado da instituição remetente (origem)
- Entrega a mensagem aberta para a aplicação;
Toda operação com chaves públicas e privadas está ligado ao uso de certificados X.509, portanto além de Encode e Decode o módulo SPB também precisa ter alguma gerência de certificados.
Cada instituição é identificada no SPB pelo código ISPB (8 dígitos) e pode trocar mensagem nos chamados domínios de mensagem, e cada um destes domínios requer um certificado diferente. Cada instituição só pode ter um certificado ativo por vez num domínio.
No módulo SPB as instituições (e seus certificados equivalentes) podem ser identificadas apenas pelo código ISPB.
O módulo SPB é responsável pela criptografia de mensagens conforme as definições do BACEN, e a estrutura de comunicação do SPB pode ser utilizada por outros sistemas entre as instituições financeiras motivadas pelo surgimento de novas aplicações no âmbito do BACEN, como por exemplo:
- SPB opera o STR - Sistema de Transferência de Recursos (STR01)
- MES opera o Sisbacen (MES01, MES02)
- CIP opera o SCG - Sistema de Controle de Garantias e C3 - Sistema Central de Cessões de Crédito. Cada um desses sistemas pode possuir uma chave/certificado e será tratado como um domínio na aplicação de controle da mensageria. Se a instituição operar mais de um ISPB, cada um deles deve acessar uma partição de chaves separada dentro do HSM. Há casos em que uma instituição pode operar MES/SPB com a mesma chave/certificado.
Intermante no HSM o gerenciamento de certificados é feito utilizando Maps, que são objetos de apontamento e referência. Toda as referências no módulo SPB são para Maps, não para chaves e certificados.
Sobre as nomenclaturas internas descritas a seguir, a ideia é que chaves, certificados e maps sejam gerenciados pelas funções especializadas de SPB da biblioteca client do HSM, e assim estas regras de formação de nome ficam totalmente transparentes para a aplicação, que precisa buscar apenas pelo código ISBP.
Guarda de Certificados
Se as funções de Encode e Decode precisassem tratar as mensagens usando apenas os certificados ativos, bastaria manter estes certificados na base, mas há casos, como processo de auditoria, onde a aplicação precisa abrir ou verificar assinatura de uma mensagem antiga, que foi gerada com um certificado já desativado (ou que ainda será ativado no futuro). Por isso o HSM tem a necessidade de manter e acumular todos os certificados na base, tantos os próprios quanto os de terceiros, à medida que eles vão sendo importados, ativados e desativados.
Formato UTF-16 BE no XML
O manual do BACEN especifica que as mensagens XML devem ser representadas no formato Unicode UTF-16 BE. Para o mod_SPB é indiferente, já que o conteúdo que será assinado e cifrado no Encode será exatamente aquele enviado pelo usuário, o HSM não faz conversão automática de texto nem no Encode, nem o Decode.
Flags de indicação de tratamento especial no cabeçalho SPB
O manual do BACEN menciona mensagens e indicativos de arquivos que podem estar no conteúdo de uma mensagem SPB. A diferenciação é que as mensagens XML deve estar representadas em formato UTF16-BE, enquanto os aquivos não tem este requisito.
Esta distinção entre mensagem e arquivo é importante para o chamador, pois ele vai decidir se precisa converter o formato ou não antes de enviar ao HSM.
No caso das mensagens indicando conteúdo compactado, a premissa da implementação é que o emissor possui a infra-estrutura necessária de compactação, assim o HSM assina e cifra o que a aplicação passar no Encode, enquanto no caso do destinatário é premissa é que ele pode não ter a infra-estrtura de descompactação à mão, assim o HSM faz a descompactação do conteúdo em Decode e entrega o conteúdo descompactado, inclusive detectando automaticamente se o padrão usado é gzip ou pkzip.
Todas as mensagens enviadas são assinadas, e algumas podem ser de uso público, sem destinatário especificado.
C04 | Mensagem | Arquivo | Assinado | Cifrado | Zipado | Destinatário | Encode | Decode |
---|---|---|---|---|---|---|---|---|
0 | x | x | x | |||||
1 | x | x | x | usa cert ainda não ativado | usa cert ainda não ativado | |||
2 | x | x | público | aceita destino em branco | aceita destino em branco | |||
3 | x | x | ||||||
4 | x | x | ||||||
6 | x | x | público | aceita destino em branco | aceita destino em branco | |||
8 | x | x | x | x | já deve receber zipado | faz a descompactação autom | ||
10 | x | x | x | público | já deve receber zipado | faz a descompactação autom |
Tratamento automático de mensagem SPB para troca de certificado
Pela definição do Bacen as trocas e ativações de certificados SPB são feitas por dentro do sistema usando mensagens específicas.
O HSM pode detectar este tipo de mensagem no Decode e promover a troca do certificado na base do HSM automaticamente, sem que a aplicação precise chamar explicitamente a API de ativação de certificado.
Esta é uma opção de parametrização da chamada de Decode.
O HSM irá tratar o Decode da GEN0007 (aviso de atualização de certificado via broadcast do BACEN) e a resposta a uma GEN0008 (uma consulta ao certificado digital, cuja resposta é uma GEN0008R1), além da GEN0018 (certificado do BACEN). Para o HSM a GEN0007 e a resposta à GEN0008 são equivalentes. No caso da GEN0018, o certificado na mensagem é importado, mas não é ativado automaticamente, pois o manual especifica que o BACEN envia a mensagens com no mínimo 03 dias de antecedência à ativação; assim a aplicação fica responsável por controlar o tempo entre a recepção e a ativação; e para ativar basta informar CA e NS, pois o certificado já estará importado na base do HSM.
A mensagem GEN0006 é usada pelas instituições para informar ao BACEN a ativação ou atualização da situação de um certificado. No HSM esta mensagem (e também a resposta GEN0006R1) não tem tratamento especial, pois não demanda mudanças na base local.
O fluxo normal da operação de ativação de um novo certificado envolve uma mensagem GEN0006 da instituição para o BACEN, que em seguida envia uma mensagem GEN0007 de broadcast informando a todos os participantes que o certificado da instituição deve ser alterado. Como a própria instituição também recebe esta GEN0007, é neste momento (durante o Decode) que a aplicação pode instruir o HSM para fazer a ativação automática do novo certificado em sua base local.
Formato de certificado
Internamente o HSM opera, importa e exporta certificados apenas no formato DER (binário), mas na biblioteca as operações de importação de certificado suportam tanto o formato DER quanto o formato PEM (base64), com detecção automática.
Nomenclatura
O módulo SPB do HSM permite que se faça operações de codificação e decodificação de mensagens SPB utilizando chaves e certificados dentro do HSM.
Isso significa que toda a base de certificados e chaves privadas da própria instituição e das instituições com quem o banco se comunica estarão guardadas e centralizadas no HSM, sem a necessidade de fazer o controle externo.
A identificação das chaves e certificados que serão utilizadas são feitas utilizando o código ISPB das instituições de uma forma natural para as aplicações chamadoras, ao invés do modelo comum que é utilizar os identificadores nativos das chaves e certificados.
Para fazer este relacionamento de ISPB com chaves e certificados foi utilizado um objeto no HSM chamado map, que simplesmente liga um ISPB a uma chave privada e/ou um certificado. Isso torna possível passar apenas o ISPB para uma chamada de codificação SPB ao invés de um nome de chave.
Nomenclatura interna de chaves e certificados
Com o objetivo de facilitar a utilização, uma lei de formação é definida para os nomes destes objetos..
Para o nomes de chaves é:
k: 01 caracter, literal ISBP: 08 caracteres, código ISPB dom: até 05 caracteres, domínio yyyymmddhhmmss: 14 caracteres, timestamp GMT do momento de geração da chave. Total: até 31 caracteres, ex: k_12345678_str01_20131029110223
Para os certificados:
c: 01 caracter, literal ISBP: 08 caracteres, código ISPB dom: até 05 caracteres, domínio yyyymmddhhmmss: 14 caracteres, timestamp GMT do momento de importação do certificado. Total: até 31 caracteres, ex: c_12345678_spb_20131101120334
Para os certificados de terceiros vale a mesma lei de formação.
Map
O map é simplesmente um objeto interno do HSM que guarda os Ids de dois outros objetos. No caso do módulo SPB guarda o Id do certificado e o Id da chave privada. Cada Id ocupa uma posição dentro do map chamada slot.
Nomenclatura interna de maps SPB
Uma vez que toda mensagem envolve tratamento de certificado é preciso uma forma do módulo SPB identificar unicamente cada certificado de cada instituição em cada domínio. Conforme o padrão do Bacen, cada certificado tem um número de série (SN) de até 32 bytes, definido pela Autoridade Certificadora (CA) que o emite, mas não há garantia que os número de série sejam únicos globalmente, portanto a identificação do certificado precisa incluir informação da CA (cada CA no SPB tem um byte de identificação) e o do NS, o que ultrapassa o limite de 32 caracteres de identificadores do HSM; a RFC 3280 também faz esta distinção para identificar unicamente um certificado. Os Ids dos maps de certificados usados no módulo SPB utilizam um esquema de compactação de nome.
A solução adotada é um hash MD5, que tem exatamente 16 bytes de comprimento (32 caracteres) e não produz colisão para este caso de uso. A definição do que vai entrar na composição do hash é (CA+NS), onde CA e SN são compostos de caracteres hexadecimais em caixa alta.
- CA tem tamanho 2, representando um byte.
- SN tem tamanho 32 e deve ser completado com padding zero a esquerda (de acordo com o manual de segurança SPB 3.2) quando o tamanho do SN do certificado for menor que 32.
- A concatenação CA+SN deverá ser feita sem contar terminadores NULL. 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_
.
O uso de @dom pela aplicação chamadora é opcional; a instituição pode não usar domínios de aplicação.
Do ponto de vista da aplicação chamadora, ela pode referenciar os maps como ISPB@dom
ou CA@NS
, para usar a mesma API de Encode/Decode. A biblioteca do HSM detecta automaticamente.
Os maps permitem que os slots apontem para um FQN, ou seja, o certificado e chave podem estar em partições diferentes. Em todo caso o map sempre deverá existir na partição do usuário conectado, mesmo que os ids apontados nos slots estejam em outra partição. A princípio a melhor forma de uso é manter todos os certificados e chaves de um ISPB numa mesma partição, sem referências a partições remotas.
Para facitilitar a identificação dos objetos e a busca por ISPBs os certificados e pares certificados+chaves privadas ativos tem um MAP com o identificador ISPB.
Todos os certificados e pares certificados+chaves privadas, independente de estarem ativos ou não têm um MAP com id MD5(CA+SN) para identificação e histórico, onde CA é identificador da Autoricade Certificadora e SN é número de série do certificado.
O nome do objeto map é o identificador da instituição que pode ser de 2 tipos:
- CA@SN
- AC (Autoridade Certificadora) e NS(Número de Série) do certificado.
- É feito um hash MD5 destes dados e o resultado é o nome do MAP.
- Este map é gerado automaticamente para todos os certificados e pares certificados + chave privada quando importados via APIs SPB (Ex.: DSPBImportCertificate(), ...).
- Exemplo:
03@00000000000000000000000087654321
- ISPB@Dominio
- É gerado um nome específico do map utilizando o ISPB e o DOMINIO.
- O domínio não é obrigatório. Podem ser criados identificadores apenas com ISPB.
- Este tipo de map só é gerado para certificados e pares certificados+chave ativos.
- Removendo este map o certificado correspondente fica inativo.
- Exemplo:
12345678@MES01
Na documentação das APIs é informado se os dois tipos de identificador são aceitos ou apenas um deles.
Múltiplas partições
Para utilização de objetos em partições de outros usuários é necessário especificar o id da partição no identificador.
A indicação é feita adicionando no início do identificador o nome da partição onde estão os objetos, separado por /
.
Exemplo: usuario/12345678@MES01
Encode
A sequência de APIs DSPBEncodeInit(), DSPBEncodeCont() e DSPBEncodeEnd() realizam uma operação de codificação de mensagem SPB.
A estrutura de chamada com sequência init/cont/end permite que a aplicação chamadora possa utilizar a API com qualquer tamanho de mensagem, incluindo arquivos grandes.
A utilização de parâmetros com identificadores ISBP de origem e destino nas APIs visa aumentar o nível de conferência entre o que a aplicação tem de fato (a mensagem SPB) com o que ela julga ter (os parâmetros da API).
A operação de codificação não altera o formato de representação da mensagem, portanto a aplicação deve enviar a mensagem conforme definição do Banco Central (ex: UTF-16BE). A mensagem será cifrada e assinada tal qual é recebida.
Decode
A sequência de APIs DSPBDecodeInit(), DSPBDecodeCont() e DSPBDecodeEnd() realizam uma operação de decodificação de mensagem SPB.
A estrutura de chamada com sequência init/cont/end permite que a aplicação chamadora possa utilizar a API com qualquer tamanho de mensagem.
A utilização de parâmetros de ISBP de origem e destino nas APIs é no sentido de aumentar o nível de conferência entre o que a aplicação tem de fato (a mensagem SPB) com o que ela julga ter (os parâmetros da API).
Durante o decode o firmware do HSM tem condições de detectar que a mensagem é de troca de certificado e já realizar esta atualização e ativação automaticamente (sem necessidade de posterior ação da aplicação), para isso a flag bAutoUpdateCert deve estar ligada.
A operação de decodificação não altera o formato de representação da mensagem. A mensagem será passada à aplicação tal qual foi decifrada.
Console Gráfica de Gerência do Módulo SPB
Para facilitar a gerência e abstrair os detalhes mais complexos do módulo SPB o fabricante do HSM disponibiliza uma console gráfica. Através dela todas as operações relativas a carregamento e ativação de certificados, geração de chaves e requisições de certificados, criação e visualização de domínios, permissionamento de partições e várias outras podem ser facilmente executadas.
Consulte o seu fornecedor sobre a disponibilidade da Console de Gerência SPB do HSM.
A seguir são exibidos alguns screenshoots com telas da console gráfica.
Funções
int AAP_API DSPBEncodeInit | ( | HSESSIONCTX | hSession, |
char * | szSrcISPB, | ||
char * | szDstISPB, | ||
DWORD | dwTotalDataLen, | ||
BYTE | bErrorCode, | ||
BYTE | bSpecialTreatment, | ||
HSPBCTX * | hSPBCtx, | ||
DWORD | dwFlags | ||
) |
#include <dinamo.h>
Inicia uma operação de codificação de mensagens SPB.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szSrcISPB Identificador da instituição de origem com tamanho máximo MAX_OBJ_ID_FQN_LEN.
O identificador da origem deverá ter o seguinte formato: ISPB@DOMINIO, sendo a parte do domínio opcional.
O tamanho exato para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN. O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO.
Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB.[in] szDstISPB Identificador da instituição de destino tamanho máximo MAX_OBJ_ID_FQN_LEN.
O identificador do destino deverá ter o seguinte formato: ISPB@DOMINIO, sendo a parte do domínio opcional.
O tamanho para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN. O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO.
Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB.[in] dwTotalDataLen Tamanho em bytes total da mensagem a ser codificada. [in] bErrorCode Código de erro da mensagem para ser colocado no cabeçalho de segurança, normalmente em mensagens de resposta. [in] bSpecialTreatment Código de tratamento especial da mensagem, conforme manual do Banco Central. [out] hSPBCtx Ponteiro para contexto da operação de codificação SPB. Depois do seu uso deverá ser liberado com a função DSPBEncodeEnd(). [in] dwFlags Define detalhes da decodificação, podendo assumir os seguintes valores descritos na tabela abaixo. Valor Signficado ND_SPB_ENCODE_GEN_01 Gera uma mensagem GEN 01. ND_SPB_USE_CIP1 Utiliza o padrão CIP(Camara Interbancaria de Pagamentos). Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado.
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Anotações
- Deve-se chamar DSPBEncodeCont() e DSPBEncodeEnd() para envio de mensagem e finalização da codificação. Mesmo em caso de erro, sempre liberar o contexto da operação utilizando DSPBEncodeEnd().
- Exemplos:
- spbencdec.c.
int AAP_API DSPBEncodeCont | ( | HSPBCTX | hSPBCtx, |
BYTE * | pbDataIn, | ||
DWORD | dwDataInLen, | ||
BYTE * | pbDataOut, | ||
DWORD * | pdwDataOutLen | ||
) |
#include <dinamo.h>
Envia partes ou toda a mensagem para codificação no HSM.
- Parâmetros
-
[in] hSPBCtx Contexto adquirido através da função DSPBEncodeInit(). [in] pbDataIn Buffer contendo parte ou toda a mensagem a ser codificada.
O tamanho por chamada é de ND_SPB_MAX_NOTIFY_DATA_SEG bytes.
Pode-se enviar tamanhos menores caso seja o último ou o único pedaço da mensagem.[in] dwDataInLen Tamanho em bytes do buffer pbDataIn
.[out] pbDataOut Buffer que receberá os dados da mensagem codificada.
Deverá ter tamanho igual ou maior apbDataIn
.
Caso seja o último pedaço, adicionar espaço no tamanho para possível padding.[in,out] pdwDataOutLen Ponteiro para um DWORD que contém o tamanho de pbDataOut
.
Na entrada deve conter o tamanho do buffer apontado por pbDataOut, na saída contém o tamanho dos dados que foram codificados em pbDataOut.
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Anotações
- Mesmo em caso de erro, sempre liberar o contexto da operação utilizando DSPBEncodeEnd().
- Exemplos:
- spbencdec.c.
#include <dinamo.h>
Finaliza uma operação de codificação SPB e recebe o cabeçalho de segurança.
- Parâmetros
-
[in] hSPBCtx Ponteiro para o contexto adquirido através da função DSPBEncodeInit(). [out] pbSPBHeader Buffer que conterá o cabeçalho de segurança damensagem codificada.
Deverá ter tamanho igual ou maior a ND_SPB_MSG_HEADER_V2_LEN bytes.[in,out] pdwSPBHeaderLen Ponteiro para um DWORD que na entrada deverá conter o tamanho do buffer apontado por pbSPBHeader, e na saída conterá o tamanho do cabeçalho escrito em pbSPBHeader.
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbencdec.c.
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>
Inicia uma operação de decodificação de mensagens SPB.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szSrcISPB Identificador da instituição de origem com tamanho máximo MAX_OBJ_ID_FQN_LEN. O identificador da origem deverá ter o seguinte formato: ISPB@DOMINIO, sendo a parte do domínio opcional. O tamanho exato para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN. O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN. Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO. Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB. [in] szDstISPB Identificador da instituição de destino com tamanho máximo MAX_OBJ_ID_FQN_LEN. O identificador do destino deverá ter o seguinte formato: ISPB@DOMINIO. O tamanho para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN. O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN. Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO. Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB. [in] pbHeader Buffer contendo o cabeçalho de segurança da mensagem SPB a ser decodificada. [in] dwHeaderLen Tamanho em bytes do buffer pbHeader. [in] bAcceptExpiredCert Byte para aceitar certificados expirados na decodificação da mensagem. Passar 1 para aceitar e 0 para não aceitar. [in] bAutoUpdateCert Habilita ou desabilita a atualização automática de certificados na base do HSM caso a mensagem seja de troca de certificado. Atualmente são tratadas as seguintes mensagens: GEN0007, GEN0008 (resposta) e GEN0018. O certificado é importado e ativado automaticamente, exceto no caso da GEN0018 (certificado do Banco Central), onde o certificado é importado mas não ativado. Passar 1 para habilitado e 0 para desabilitado. [in] dwMessageDataLen Tamanho total da mensagen SPB a ser decodificada. [out] hSPBCtx Ponteiro para o contexto da operação de decodificação SPB. Depois do seu uso deverá ser liberado com a função DSPBDecodeEnd(). [in] dwFlags Define detalhes da decodificação, podendo assumir os seguintes valores descritos na tabela abaixo. Valor Signficado ND_SPB_OUT_NO_PADDING Retira o padding do final da mensagem SPB após a decriptação. ND_SPB_OUT_WITH_PADDING Mantem o padding no final da mensagem SPB após a decriptação. ND_SPB_USE_CIP1 Utiliza o padrão CIP(Camara Interbancaria de Pagamentos). Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado.
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Anotações
- Deve-se chamar DSPBDecodeCont() e DSPBDecodeEnd() para envio de mensagem e finalização da codificação.Mesmo em caso de erro, sempre liberar o contexto da operação utilizando DSPBDecodeEnd().
- Exemplos:
- spbencdec.c.
int AAP_API DSPBDecodeCont | ( | HSPBCTX | hSPBCtx, |
BYTE * | pbDataIn, | ||
DWORD | dwDataInLen, | ||
BYTE ** | ppbDataOut, | ||
DWORD * | pdwDataOutLen | ||
) |
#include <dinamo.h>
Envia partes ou toda a mensagem para decodificacao no HSM.
- Parâmetros
-
[in] hSPBCtx Contexto adquirido atraves da funcao DSPBDecodeInit. [in] pbDataIn Buffer contendo parte ou toda a mensagem a ser decodificada. O tamanho por chamada é de ND_SPB_MAX_NOTIFY_DATA_SEG bytes. Pode-se enviar tamanhos menores caso seja o ultimo ou o unico pedaco da mensagem. [in] dwDataInLen Tamanho em bytes do buffer pbDataIn
.[out] ppbDataOut Ponteiro de ponteiro que ira receber os dados codificados. O tamanho do buffer alocado estara disponivel atraves de pdwDataOutLen.A alocacao de memoria e feita internamente. A desalocacao e feita na proxima chamada a DSPBDecodeCont() ou DSPBDecodeEnd(). [out] pdwDataOutLen Ponteiro para o tamanho do buffer alocado internamente em ppbDataOut.
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbencdec.c.
#include <dinamo.h>
Finaliza uma operacao de decodificacao SPB e recebe o cabecalho de seguranca.
- Parâmetros
-
[in] hSPBCtx Ponteiro para o contexto adquirido atraves da funcao DSPBDecodeInit().
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbencdec.c.
int AAP_API DSPBGenerateKey | ( | HSESSIONCTX | hSession, |
char * | szID, | ||
char * | szPrivateKeyName, | ||
DWORD | dwKeyParam, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
Gera uma chave privada no padrão SPB. É uma função especializada da API de geração de chave do HSM.
A aplicação gera a chave (RSA 2048 ou como estabelecido no manual atualizado do Bacen) com a identificação seguindo a lei de formação interna, descrita na apresentação do módulo SPB.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szID Identificador da instituição à qual se destina a chave privada.
O identificador da instituição deverá ter o seguinte formato: "ISPB@DOMINIO", sendo a parte do domínio opcional.
O tamanho exato para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN.
O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO.[out] szPrivateKeyName Buffer de tamanho de MAX_OBJ_ID_FQN_LEN ou mais.
Este buffer receberá uma string contendo o identificador do par de chaves gerado dentro do HSM.
Este identificador deverá ser mantido pela aplicação para posterior utilização em DSPBGenerateCSR() e/ou outras.[in] dwKeyParam Parâmetros adicionais da chave. Veja as opções na função DGenerateKey(). [in] dwParam Reservado para uso futuro (deve ser 0).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbggenkeycsr.c.
int AAP_API DSPBGenerateCSR | ( | HSESSIONCTX | hSession, |
char * | szPrivateKeyName, | ||
BYTE | bVersion, | ||
char * | szSPBSubject, | ||
DWORD | dwOutType, | ||
DWORD * | pdwCSRLen, | ||
BYTE ** | ppbCSR, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
Gera um CSR (Certificate Signing Request / Requisição de Assinatura de Certificado) para SPB. É uma função especializada da API de geração de CSR PKCS#10 do HSM.
Não há regras de validação de certificados SPB; isto está a cargo da aplicação, que poderá gerar CSRs para sistemas diferentes, como SPB e CIP.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szPrivateKeyName Identificador da chave privada.
Normalmente a string gerada em DSPBGenerateKey().[in] bVersion Versão do CSR PKCS#10. A seguinte tabela é suportada. Valor Significado CORE_P10_CSR_VERSION1 PKCS#10 CSR versão 1. [in] szSPBSubject DN (Dinstinguished Name), para a geração do CSR, com tamanho máximo CORE_P10_CSR_DN_MAX_LEN. Os campos de DN deverão ser separados por '/'. [in] dwOutType Tipo de saída do CSR. A seguinte tabela é suportada, Valor Significado P10_CSR_DER Exporta o CSR no formato DER. P10_CSR_PEM Exporta o CSR no formato PEM. [out] pdwCSRLen Ponteiro para o tamanho do buffer alocado em ppbCSR. [out] ppbCSR Ponteiro de ponteiro que irá receber o CSR.
O tamanho do buffer alocado estará disponível através de pdwCSRLen.
A alocação de memória é feita internamente.
A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree().[in] dwParam Parâmetros adicionais. A seguinte tabela é suportada. Valor Significado 0 Utiliza o hash padrão do HSM na assinatura do CSR. CORE_P10_HASH_SHA1 Utiliza o SHA-1 na assinatura do CSR. CORE_P10_HASH_SHA224 Utiliza o SHA-224 na assinatura do CSR. CORE_P10_HASH_SHA256 Utiliza o SHA-256 na assinatura do CSR. CORE_P10_HASH_SHA384 Utiliza o SHA-384 na assinatura do CSR. CORE_P10_HASH_SHA512 Utiliza o SHA-512 na assinatura do CSR.
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbggenkeycsr.c.
int AAP_API DSPBImportCertificate | ( | HSESSIONCTX | hSession, |
BYTE | bActivate, | ||
char * | szUser, | ||
BYTE * | pbCertificate, | ||
DWORD | dwCertificateLen, | ||
char * | szDomain, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
Importa um certificado SPB e o associa a um par de chaves dentro do HSM (via um objeto map), caso exista tal chave.
- A aplicação não precisa informar se é um certificado próprio ou de terceiro, o HSM se encarrega de fazer uma busca por chave privada correspondente à chave pública no certificado; e se encontrar faz associação no map apropriado. Quando uma chave privada correspondente não é encontrada fica assumido que o certificado é de um terceiro. Esta busca interna pelo HSM deixa a operação mais rápida, atômica e segura, já que a biblioteca não precisa fazer operações de exportação e buscas locais.
- O certificado é criado na base do HSM com a lei de formação de nome definida. O HSM faz o parse no certificado para recuperar campos como ISPB.
- Se o HSM encontrar a chave privada um map é criado identificado por MD5(CA+NS), coloca no slot1 o id da chave e no slot2 o id do certificado recém importado. Retorna erro se já existir o map. Este é o caso de um certificado próprio.
- Se o firmware não encontrar a chave privada um map é criado identificado por MD5(CA+NS), deixa o slot1 vazio e no slot2 o id do certificado recém importado. Retorna erro se já existir o map. Este é o caso de um certificado de terceiro.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] bActivate Ativa automaticamente o certificado no momento da importação.
Passar 1 para ativar e 0 para importar sem ativar o certificado.[in] szUser Nome do usuário, para importação do certificado, com tamanho máximo (MAX_USR_LEN+1).
Pode ser NULL caso a importação seja feita no próprio usuário da sessão corrente.[in] pbCertificate Buffer contendo o certificado a ser importado. O certificado pode estar no formato PEM ou DER. [in] dwCertificateLen Tamanho do buffer apontado por pbCertificate. [in] szDomain Domínio de mensagem do certificado a ser ativado. Deve ter tamanho máximo de (ND_SPB_DOMAIN_MAX_LEN + 1).
Pode ser NULL caso não haja um domínio definido.[in] dwParam A seguinte tabela de flags é suportada. Valor Significado 0 Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro). ND_SPB_USE_CIP1 Utiliza o padrão CIP(Camara Interbancaria de Pagamentos).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbggenkeycsr.c.
int AAP_API DSPBImportPKCS12 | ( | HSESSIONCTX | hSession, |
BYTE | bActivate, | ||
char * | szUser, | ||
char * | szPkcs12File, | ||
char * | szPkcs12Pwd, | ||
char * | szDomain, | ||
DWORD | dwKeyAttr | ||
) |
#include <dinamo.h>
Importa um par de chaves e um certificado a partir de um arquivo PKCS#12.
- O certificado e a chave privada são criados na base do HSM com a lei de formação de nome definida. O HSM faz o parse no certificado para recuperar campos como CA e NS.
- No processo de importação um map é criado identificado por MD5(CA+NS), no slot1 vai o id da chave e no slot2 o id do certificado. Retorna erro se já existir o map, ou seja, se o certificado e a chave privada já existiram na base do HSM.
- Esta API detecta automaticamente se é um certificado SPB ou CIP.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] bActivate Ativa automaticamente o certificado no momento da importação.
Passar 1 para ativar e 0 para importar sem ativar o certificado.[in] szUser Nome do usuário onde a chave será criada. Pode ser NULL caso a chave seja criada no próprio usuário autenticado. [in] szPkcs12File Nome do arquivo PKCS#12 para importação. [in] szPkcs12Pwd Senha do arquivo PKCS#12 para importação. [in] szDomain Domínio de mensagem do certificado a ser ativado. Deve ter tamanho máximo de (ND_SPB_DOMAIN_MAX_LEN + 1).
cPode ser NULL caso não haja um domínio definido.[in] dwKeyAttr Parâmetros adicionais da chave. Veja as opções na função DGenerateKey().
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbimportp12.c.
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>
Exporta um par de chaves e um certificado no formato PKCS#12 a partir de um HSM.
- Esta chamada aceita idenficador de certificado/chave privada nos formatos CA@SN e ISPB@DOM.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession().. [in] szPkcs12Pwd Senha do arquivo PKCS#12. Passar NULL para gerar PKCS#12 sem senha. [in] szISPB Identificador do certificado/chave privada no formato CA@SN, ISPB ou ISPB@DOM. [in] szReserved Reservado para uso futuro (deve ser NULL). [out] ppbPkcs12 Ponteiro para um ponteiro que conterá o PKCS#12 gerado. Esta área de dados será alocada internamente e deve ser liberada utilizando DFree(). [out] pdwPkcs12Len Ponteiro para o tamanho dos dados escritos em ppbPkcs12
.[in] dwReserved Reservado para uso futuro (deve ser 0).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
int AAP_API DSPBActivateCertificate | ( | HSESSIONCTX | hSession, |
char * | szIdCert, | ||
char * | szDomain, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
Ativa um certificado SPB no HSM.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szIdCert Identificador do certificado a ser ativado.
O identificador do certificado deverá ter o seguinte formato: CA@SN.
O tamanho para CA é ND_SPB_CA_LEN e o tamanho para SN é ND_SPB_SN_MAX_LEN.
O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 03@12345678 onde 03 é o identificador da CA e 12345678 é o número de série do certificado.[in] szDomain Domínio de mensagem do certificado a ser ativado. Deve ter tamanho máximo de (ND_SPB_DOMAIN_MAX_LEN + 1).
Pode ser NULL caso não haja um domínio definido.[in] dwParam A seguinte tabela de flags é suportada. Valor Significado 0 Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro). ND_SPB_USE_CIP1 Utiliza o padrão CIP(Camara Interbancaria de Pagamentos).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbactivatecert.c.
int AAP_API DSPBGetCertificate | ( | HSESSIONCTX | hSession, |
char * | szIdCert, | ||
BYTE ** | ppbCertificate, | ||
DWORD * | pdwCertificateLen, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
Ativa um certificado SPB no HSM.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szIdCert Identificação do certificado a ser recuperado.
O identificador do certificado poderá ter os seguintes formatos: ID, CA@SN ou ISPB@DOMINIO.
O tamanho exato para CA é ND_SPB_CA_LEN e o tamanho máximo para SN é ND_SPB_SN_MAX_LEN.
O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN. Exemplo: 03@12345678 onde 03 é o identificador da CA e 12345678 é o ISPB da instituição.
O tamanho exato para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN.
O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO.[out] ppbCertificate Ponteiro de ponteiro que irá receber o certificado.
O tamanho do buffer alocado estará disponível através de pdwCertificateLen.
A alocação de memória é feita internamente pela biblioteca.
A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree().[out] pdwCertificateLen Ponteiro para o tamanho do buffer apontado por ppbCertificate. [in] dwParam Reservado para uso futuro (deve ser 0).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbgetcert.c.
int AAP_API DSPBCalculateObjectId | ( | char * | szISPB, |
char * | szDomain, | ||
DWORD | dwKeyType, | ||
char * | szOutObjName, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
API auxiliar que calcula (localmente) um nome de objeto no formato padrão do módulo SPB.
- Parâmetros
-
[in] szISPB ISPB da instituição. Deve ter tamanho de (ND_SPB_ISPB_LEN +1). [in] szDomain Domínio de mensagem do certificado a ser ativado. Deve ter tamanho máximo de (ND_SPB_DOMAIN_MAX_LEN + 1).
Pode ser NULL caso não haja um domínio definido.[in] dwKeyType Tipo do nome a ser gerado. Os valores da tabela seguinte serão aceitos: Valor Significado SPB_GENERATE_KEY_NAME Gera um nome para uma chave. SPB_GENERATE_CER_NAME Gera um nome para um certificado. [out] szOutObjName Buffer de tamanho MAX_OBJ_ID_FQN_LEN que conterá o nome de objeto calculado. [in] dwParam Reservado para uso futuro (deve ser 0).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
int AAP_API DSPBMapInfo | ( | HSESSIONCTX | hSession, |
char * | szIdCert, | ||
EXT_MAP_2_OBJ_INFO * | pstExtMap, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
API auxiliar que recupera as informações de um MAP SPB.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szIdCert Identificação do certificado a ser recuperado.
O identificador do certificado poderá ter os seguintes formatos: ID, CA@SN ou ISPB@DOMINIO.
O tamanho exato para CA é ND_SPB_CA_LEN e o tamanho máximo para SN é ND_SPB_SN_MAX_LEN.
O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 03@12345678 onde 03 é o identificador da CA e 12345678 é o número de série do certificado.
O tamanho exato para ISPB é ND_SPB_ISPB_LEN e o tamanho máximo para DOMINIO é ND_SPB_DOMAIN_MAX_LEN.
O tamanho máximo para o identificador é ND_SPB_ID_MAX_LEN.
Exemplo: 12345678@MES01 onde 12345678 é o ISPB da instituição e MES01 é o identificador do DOMÍNIO.[out] pstExtMap Ponteiro para um EXT_MAP_2_OBJ_INFO que conterá as informações do MAP requisitado. [in] dwParam Reservado para uso futuro (deve ser 0).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.
- Exemplos:
- spbgetcert.c.
int AAP_API DSPBSetISPBMap | ( | HSESSIONCTX | hSession, |
char * | szISPB, | ||
char * | szKeyId, | ||
char * | szCertId, | ||
DWORD | dwParam | ||
) |
#include <dinamo.h>
API auxiliar que cria ou altera um map SPB. O map é identificado a partir dos dados de CA e NS do certificado fornecido.
- Parâmetros
-
[in] hSession Contexto adquirido através da função DOpenSession(). [in] szISPB ISPB da instituição. Deve ter tamanho máximo de MAX_OBJ_ID_FQN_LEN. [in] szKeyId Nome da chave privada da instituição. Deve ter tamanho máximo de MAX_OBJ_ID_FQN_LEN.
Pode ser NULL caso esteja definindo apenas o certificado.[in] szCertId Nome do certificado da instituição. Deve ter tamanho máximo de MAX_OBJ_ID_FQN_LEN. [in] dwParam A seguinte tabela de flags é suportada. Valor Significado 0 Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro). ND_SPB_USE_CIP1 Utiliza o padrão CIP(Camara Interbancaria de Pagamentos).
- Retorna
- 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.