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 5.0 do Manual de Segurança da RSFN publicado pelo BACEN em junho de 2021.

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 ISPB.

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 a premissa é que ele pode não ter a infra-estrutura 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), a resposta a uma GEN0008 (uma consulta ao certificado digital, cuja resposta é uma GEN0008R1), a resposta a uma GEN0006 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 a resposta a esta mensagem (GEN0006R1) tem tratamento especial para promover a ativação do certificado (a partir de firmwares versão 5.0.16).

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 os nomes de chaves:

k_<ISPB>_<dom>_<yyyymmddhhmmss>
- k: 01 caracter, literal
- <ISPB>: 08 caracteres, código ISPB
- <dom>: até 05 caracteres, domínio
- <yyyyymmddhhmmss>: 14 caracteres, timestamp GMT do momento de geração da chave.
Total: até 31 caracteres, ex: k_12345678_str01_20131029110223
Para os nomes de certificados:

c_<ISPB>_<dom>_<yyyymmddhhmmss>
- c: 01 caracter, literal
- <ISPB>: 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 facilitar 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 Autoridade 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 ISPB 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 ISPB 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.

Mais detalhes na documentação do equipamento.

Funções
void	SPBListObjects (OBJTYPE type, DinamoApi.ListCallbackFilter filterCallBack, IntPtr param)
	Lista os objetos de um determinado tipo (chave, certificado, etc).

byte[]	SPBGetCertificate (string strIdCertificate)
	Recupera um certificado armazenado em um namespace no HSM.

string	SPBGenerateKey (string ISPB, string domain, bool isExportable)
	Gera chave RSA 2048 no padrão SPB. Esta função sempre vai estar aderente aos requisitos do SPB, segundo o manual de segurança da RSFN. DinamoClient.GenerateKey(string, KEY_ALG, bool)

byte[]	SPBGenerateCSR (string sPrivateKeyName, string sSubject)
	Gera uma nova CSR baseada em uma chave existente (RSA 2048).

byte[]	SPBEncode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, byte bSpecialTreatment)
	Codifica uma mensagem com o cabeçalho do SPB, assinando, criptografando e incluindo todos os campos de cabeçalhos definidos no manual de segurança da RSFN.

byte[]	SPBEncode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, byte bSpecialTreatment, byte bErrorCode, UInt32 dwFlags)
	Codifica uma mensagem com o cabeçalho do SPB, assinando, criptografando e incluindo todos os campos de cabeçalhos definidos no manual de segurança da RSFN.

void	SPBEncode (string szSrcISPB, string szDstISPB, Stream sMsgIn, Stream sMsgOut, byte bErrorCode, byte bSpecialTreatment, UInt32 dwFlags)
	Codifica uma mensagem com o cabeçalho do SPB, assinando, criptografando e incluindo todos os campos de cabeçalhos definidos no manual de segurança da RSFN.

byte[]	SPBDecode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn)
	Decodifica uma mensagem no padrão SPB, checando as assinaturas, decriptografando porem não faz a checagem de encoding.

byte[]	SPBDecode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, bool AcceptExpiredCert, bool AutoUpdateCert)
	Decodifica uma mensagem no padrão SPB, checando as assinaturas e decriptografando.

byte[]	SPBDecode (string szSrcISPB, string szDstISPB, byte[] pbMsgIn, bool AcceptExpiredCert, bool AutoUpdateCert, UInt32 dwFlags)
	Decodifica uma mensagem no padrão SPB, checando as assinaturas e decriptografando.

void	SPBDecode (string szSrcISPB, string szDstISPB, Stream sMsgIn, Stream sMsgOut, bool AcceptExpiredCert, bool AutoUpdateCert, UInt32 dwFlags)
	Decodifica uma mensagem no padrão SPB, checando as assinaturas e decriptografando.

string	SPBMapInfoCert (string sIdCert)
	Cria um mapa com o certificado da instituição em um slot.

void	SPBSetISPBMap (string sIdMap, string sIdKey, string sIdCert)
	Cria um mapa com a chave e certificado da instituição em um slot.

void	SPBImportPKCS12 (string szPkcs12File, string szPkcs12Pwd, string szNamespace, string szDomain, int dwKeyAttr)
	Importa um certificado de um container PKCS#12 para o HSM.

void	SPBImportPKCS12 (string szPkcs12File, string szPkcs12Pwd, string szNamespace, string szDomain, int dwKeyAttr, bool isActivate)
	Importa um certificado de um container PKCS#12 para o HSM.

void	SPBImportCertificate (string szDomain, byte[] bCertificate)
	Importa um certificado para um namespace do HSM.

void	SPBImportCertificate (string szDomain, byte[] bCertificate, bool isCIPCertificate=false)
	Importa um certificado para um namespace do HSM.

void	SPBActivateCertificate (string szDomain, string szCA, string szSN, bool isCIPCertificate=false)
	Ativa um certificado que já foi importado para o HSM. Se houver um outro certificado ativo, ele será inativado.Somente um certificado permanecerá ativo por instituição, por domínio dentro de um namespace do HSM.

void	SPBImportCertificate (string szNamespace, string szDomain, byte[] bCertificate, bool isCIPCertificate=false)
	Ativa um certificado que já foi importado para o HSM. Se houver um outro certificado ativo, ele será inativado.Somente um certificado permanecerá ativo por instituição, por domínio dentro de um namespace do HSM.

void	SPBActivateCertificate (string szNamespace, string szDomain, string szCA, string szSN, bool isCIPCertificate=false)
	Ativa um certificado que já foi importado para o HSM. Se houver um outro certificado ativo, ele será inativado.Somente um certificado permanecerá ativo por instituição, por domínio dentro de um namespace do HSM.

string	SPBCalculateObjectId (string szISPB, string szDomain, KEYNAME dwKeyType)
	Função para auxiliar a formatação da identificação de objetos internos do HSM segundo o padrão utilizado no móduloSPB.

DinamoApi.SPB_CERT_X509_INFO	SPBGetCertificateInfo (byte[] certificate)
	Recupera informações do certificado.

Funções

◆ SPBListObjects()

void SPBListObjects	(	OBJTYPE	type,
		DinamoApi.ListCallbackFilter	filterCallBack,
		IntPtr	param )

inline

Lista os objetos de um determinado tipo (chave, certificado, etc).

Parâmetros

filterCallBack	Função de callback chamada para cada objeto da interação
param	Parämetro
type	Tipo de objeto Dinamo.Hsm.DinamoClient.OBJTYPE

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBGetCertificate()

byte[] SPBGetCertificate ( string strIdCertificate )

inline

Recupera um certificado armazenado em um namespace no HSM.

Parâmetros

strIdCertificate identificação do certificado no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".

Retorna: Retorno do certificado no formato DER como array de bytes

Exceções

DinamoException.DinamoException Em caso de erro

Exemplos: spb_import_activate.cs.

◆ SPBGenerateKey()

string SPBGenerateKey	(	string	ISPB,
		string	domain,
		bool	isExportable )

inline

Gera chave RSA 2048 no padrão SPB. Esta função sempre vai estar aderente aos requisitos do SPB, segundo o manual de segurança da RSFN. DinamoClient.GenerateKey(string, KEY_ALG, bool)

Parâmetros

ISPB	Número ISBP
domain	Domínio
isExportable	Verdadeiro para gerar uma chave exportável

Retorna: Label da chave gerada

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBGenerateCSR()

byte[] SPBGenerateCSR	(	string	sPrivateKeyName,
		string	sSubject )

inline

Gera uma nova CSR baseada em uma chave existente (RSA 2048).

Parâmetros

sPrivateKeyName	Identificação da chave no HSM
sSubject	Descriçáo do subject do certificado DN (Dinstinguished Name) do CSR para a geração do campo Subject do certificado. Os campos de DN deverão ser separados por '/'.

Retorna: Label da chave gerada

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBEncode() [1/3]

byte[] SPBEncode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		byte	bSpecialTreatment )

inline

Codifica uma mensagem com o cabeçalho do SPB, assinando, criptografando e incluindo todos os campos de cabeçalhos definidos no manual de segurança da RSFN.

Parâmetros

szSrcISPB	Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDstISPB	Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
pbMsgIn	Mensagem passada como um array de bytes. O HSM Não faz conversão automática de formato. No padrão do SPB o formato definido é o UTF16-BE, e cabe ao chamador da API garantir que a mensagem esteja usando o formato correto.
bSpecialTreatment	Indicador de tratamento especial. Vide C04 no manual de segurança do SPB.

Retorna: Mensagem assinada.

Exceções

DinamoException.DinamoException Em caso de erro

Exemplos: spb.cs e spb_file_cip.cs.

◆ SPBEncode() [2/3]

byte[] SPBEncode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		byte	bSpecialTreatment,
		byte	bErrorCode,
		UInt32	dwFlags )

inline

Codifica uma mensagem com o cabeçalho do SPB, assinando, criptografando e incluindo todos os campos de cabeçalhos definidos no manual de segurança da RSFN.

Parâmetros

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

pbMsgIn Mensagem passada como um array de bytes. O HSM Não faz conversão automática de formato. No padrão do SPB o formato definido é o UTF16-BE, e cabe ao chamador da API garantir que a mensagem esteja usando o formato correto.

bSpecialTreatment Indicador de tratamento especial. Vide C04 no manual de segurança do SPB.

bErrorCode Código de erro da mensagem para ser colocado no cabeçalho de segurança, normalmente em mensagens de resposta.

dwFlags

Define detalhes da codificação, podendo assumir os seguintes valores descritos na tabela abaixo.

Valor	Signficado
0	Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro).
DinamoApi.ND_SPB_ENCODE_GEN_01	Gera uma mensagem GEN 01.
DinamoApi.ND_SPB_USE_CIP1	Utiliza o padrão CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea. Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado.
DinamoApi.ND_SPB_USE_ANY	Aceita o padrão CIP/C3 Nuclea e SPB. A detecção é feita internamente.
DinamoApi.ND_SPB_ENCODE_HEADER_V3	Codifica a mensagem utilizando o cabeçalho de segurança versão 3. No futuro esta opção será definida por padrão. O cabeçalho V3 está disponível a partir da versão 5.0.16 do firmware do HSM.

DinamoApi.ND_SPB_RAW

Modo sem verificações específicas de SPB. Aceita apenas o uso do nome do MAP como parâmetros de szSrcISPB e szDstISPB.

Retorna: Mensagem assinada.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBEncode() [3/3]

void SPBEncode	(	string	szSrcISPB,
		string	szDstISPB,
		Stream	sMsgIn,
		Stream	sMsgOut,
		byte	bErrorCode,
		byte	bSpecialTreatment,
		UInt32	dwFlags )

inline

Codifica uma mensagem com o cabeçalho do SPB, assinando, criptografando e incluindo todos os campos de cabeçalhos definidos no manual de segurança da RSFN.

Parâmetros

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

sMsgIn Mensagem que será codificada. O Stream passado deve suportar a propriedade Length. O HSM Não faz conversão automática de formato. No padrão do SPB o formato definido é o UTF16-BE, e cabe ao chamador da API garantir que a mensagem esteja usando o formato correto.

sMsgOut Stream que receberá a mensagem de saída codificada. O Stream passado deve suportar a propriedade Length e o método Seek. O HSM Não faz conversão automática de formato. No padrão do SPB o formato definido é o UTF16-BE, e cabe ao chamador da API garantir que a mensagem esteja usando o formato correto.

bSpecialTreatment Indicador de tratamento especial. Vide C04 no manual de segurança do SPB.

bErrorCode Código de erro da mensagem para ser colocado no cabeçalho de segurança, normalmente em mensagens de resposta.

dwFlags

Define detalhes da codificação, podendo assumir os seguintes valores descritos na tabela abaixo.

Valor	Signficado
0	Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro).
DinamoApi.ND_SPB_ENCODE_GEN_01	Gera uma mensagem GEN 01.
DinamoApi.ND_SPB_USE_CIP1	Utiliza o padrão CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea. Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado.
DinamoApi.ND_SPB_USE_ANY	Aceita o padrão CIP/C3 Nuclea e SPB. A detecção é feita internamente.
DinamoApi.ND_SPB_ENCODE_HEADER_V3	Codifica a mensagem utilizando o cabeçalho de segurança versão 3. No futuro esta opção será definida por padrão. O cabeçalho V3 está disponível a partir da versão 5.0.16 do firmware do HSM.

DinamoApi.ND_SPB_RAW

Modo sem verificações específicas de SPB. Aceita apenas o uso do nome do MAP como parâmetros de szSrcISPB e szDstISPB.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBDecode() [1/4]

byte[] SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn )

inline

Decodifica uma mensagem no padrão SPB, checando as assinaturas, decriptografando porem não faz a checagem de encoding.

Parâmetros

szSrcISPB	Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDstISPB	Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
pbMsgIn	Mensagem codificada no padrão SPB passada como um array de bytes.

Retorna: Mensagem decodificada.

Exceções

DinamoException.DinamoException Em caso de erro

Exemplos: spb.cs e spb_file_cip.cs.

◆ SPBDecode() [2/4]

byte[] SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		bool	AcceptExpiredCert,
		bool	AutoUpdateCert )

inline

Decodifica uma mensagem no padrão SPB, checando as assinaturas e decriptografando.

Parâmetros

szSrcISPB	Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDstISPB	Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
pbMsgIn	Mensagem codificada no padrão SPB passada como um array de bytes.
AcceptExpiredCert	Aceita fazer operação mesmo com um certificado expirado.
AutoUpdateCert	Interpreta mensagens de troca de certificado e executa internamente a operação automaticamente.

Retorna: Mensagem decodificada.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBDecode() [3/4]

byte[] SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		byte[]	pbMsgIn,
		bool	AcceptExpiredCert,
		bool	AutoUpdateCert,
		UInt32	dwFlags )

inline

Decodifica uma mensagem no padrão SPB, checando as assinaturas e decriptografando.

Parâmetros

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

pbMsgIn Mensagem codificada no padrão SPB passada como um array de bytes.

AcceptExpiredCert Aceita fazer operação mesmo com um certificado expirado.

AutoUpdateCert Interpreta mensagens de troca de certificado e executa internamente a operação automaticamente.

dwFlags

Define detalhes da decodificação, podendo assumir os seguintes valores descritos na tabela abaixo.

Valor	Signficado
0	Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro).
DinamoApi.ND_SPB_OUT_NO_PADDING	Retira o padding do final da mensagem SPB após a decriptação.
DinamoApi.ND_SPB_OUT_WITH_PADDING	Mantem o padding no final da mensagem SPB após a decriptação.
DinamoApi.ND_SPB_USE_CIP1	Utiliza o padrão CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea. Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado.
DinamoApi.ND_SPB_USE_ANY	Aceita o padrão CIP/C3 Nuclea e SPB. A detecção é feita internamente.

Retorna: Mensagem decodificada.

DinamoApi.ND_SPB_RAW | Modo sem verificações específicas de SPB. Aceita apenas o uso do nome do MAP como parâmetros de szSrcISPB e szDstISPB.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBDecode() [4/4]

void SPBDecode	(	string	szSrcISPB,
		string	szDstISPB,
		Stream	sMsgIn,
		Stream	sMsgOut,
		bool	AcceptExpiredCert,
		bool	AutoUpdateCert,
		UInt32	dwFlags )

inline

Decodifica uma mensagem no padrão SPB, checando as assinaturas e decriptografando.

Parâmetros

szSrcISPB Identificação do ISPB de origem no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

szDstISPB Identificação do ISPB de destino no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR". Também pode ser passado o nome do map correspondente, fora do padrão de nomenclatura do módulo SPB em casos específicos, ver dwFlags.

sMsgIn Mensagem codificada no padrão SPB. O Stream passado deve suportar a propriedade Length. O HSM Não faz conversão automática de formato. No padrão do SPB o formato definido é o UTF16-BE, e cabe ao chamador da API garantir que a mensagem esteja usando o formato correto.

sMsgOut Stream que receberá a mensagem de saída codificada. O Stream passado deve suportar a propriedade Length e o método Seek. O HSM Não faz conversão automática de formato. No padrão do SPB o formato definido é o UTF16-BE, e cabe ao chamador da API garantir que a mensagem esteja usando o formato correto.

AcceptExpiredCert Aceita fazer operação mesmo com um certificado expirado.

AutoUpdateCert Interpreta mensagens de troca de certificado e executa internamente a operação automaticamente.

dwFlags

Define detalhes da decodificação, podendo assumir os seguintes valores descritos na tabela abaixo.

Valor	Signficado
0	Utiliza o padrão SPB(Sistema de Pagamentos Brasileiro).
DinamoApi.ND_SPB_OUT_NO_PADDING	Retira o padding do final da mensagem SPB após a decriptação.
DinamoApi.ND_SPB_OUT_WITH_PADDING	Mantem o padding no final da mensagem SPB após a decriptação.
DinamoApi.ND_SPB_USE_CIP1	Utiliza o padrão CIP(Camara Interbancaria de Pagamentos)/C3 Nuclea. Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado.
DinamoApi.ND_SPB_USE_ANY	Aceita o padrão CIP/C3 Nuclea e SPB. A detecção é feita internamente.

DinamoApi.ND_SPB_RAW

Modo sem verificações específicas de SPB. Aceita apenas o uso do nome do MAP como parâmetros de szSrcISPB e szDstISPB.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBMapInfoCert()

string SPBMapInfoCert ( string sIdCert )

inline

Cria um mapa com o certificado da instituição em um slot.

Parâmetros

sIdCert Identificação/label do certificado no HSM

Retorna: Nome do objeto mapa criado no HSM.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBSetISPBMap()

void SPBSetISPBMap	(	string	sIdMap,
		string	sIdKey,
		string	sIdCert )

inline

Cria um mapa com a chave e certificado da instituição em um slot.

Parâmetros

sIdMap	Identificação do mapa (pode ser o ISPB)
sIdKey	Identificação da chave
sIdCert	Identificação do certificado

Exceções

DinamoException.DinamoException Lança exceção no caso de erros na assinatura

◆ SPBImportPKCS12() [1/2]

void SPBImportPKCS12	(	string	szPkcs12File,
		string	szPkcs12Pwd,
		string	szNamespace,
		string	szDomain,
		int	dwKeyAttr )

inline

Importa um certificado de um container PKCS#12 para o HSM.

Parâmetros

szPkcs12File Caminho e nome do arquivo.

szPkcs12Pwd Senha

szNamespace Partição onde está o objeto.Se o objeto estiver na mesma partição logada, pode passar null.

szDomain Dominio do SPB.

dwKeyAttr

Parâmetros adicionais da chave.

Valor	Significado
DinamoApi.NONEXPORTABLE_KEY	A chave Não poderá sair do HSM.
DinamoApi.EXPORTABLE_KEY	A chave poderá ser exportada do HSM.
DinamoApi.TEMPORARY_KEY	A chave somente existirá enquanto a sessão estiver ativa. Ela será destruída após o encerramento da sessão.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBImportPKCS12() [2/2]

void SPBImportPKCS12	(	string	szPkcs12File,
		string	szPkcs12Pwd,
		string	szNamespace,
		string	szDomain,
		int	dwKeyAttr,
		bool	isActivate )

inline

Importa um certificado de um container PKCS#12 para o HSM.

Parâmetros

szPkcs12File Caminho e nome do arquivo.

szPkcs12Pwd Senha.

szNamespace Partição onde está o objeto.Se o objeto estiver na mesma partição logada, pode passar null.

szDomain Dominio do SPB.

dwKeyAttr

Parâmetros adicionais da chave.

Valor	Significado
DinamoApi.NONEXPORTABLE_KEY	A chave Não poderá sair do HSM.
DinamoApi.EXPORTABLE_KEY	A chave poderá ser exportada do HSM.
DinamoApi.TEMPORARY_KEY	A chave somente existirá enquanto a sessão estiver ativa. Ela será destruída após o encerramento da sessão.

isActivate Ativa o certificado durante a importação

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBImportCertificate() [1/3]

void SPBImportCertificate	(	string	szDomain,
		byte[]	bCertificate )

inline

Importa um certificado para um namespace do HSM.

Parâmetros

szDomain	Dominio do SPB.
bCertificate	Certificado SPB no padrão SPB como um array de bytes.

Exceções

DinamoException.DinamoException Em caso de erro

Exemplos: spb_import_activate.cs.

◆ SPBImportCertificate() [2/3]

void SPBImportCertificate	(	string	szDomain,
		byte[]	bCertificate,
		bool	isCIPCertificate = false )

inline

Importa um certificado para um namespace do HSM.

Parâmetros

szDomain	Dominio do SPB.
bCertificate	Certificado SPB no padrão SPB como um array de bytes.
isCIPCertificate	Verdadeiro se o certificado for no padrão CIP.

Exceções

DinamoException Lança exceção em caso de erro.

◆ SPBActivateCertificate() [1/2]

void SPBActivateCertificate	(	string	szDomain,
		string	szCA,
		string	szSN,
		bool	isCIPCertificate = false )

inline

Ativa um certificado que já foi importado para o HSM. Se houver um outro certificado ativo, ele será inativado.Somente um certificado permanecerá ativo por instituição, por domínio dentro de um namespace do HSM.

Parâmetros

szDomain	Dominio do SPB.
szCA	Identificação da CA (número da CA).
szSN	Número de série do certificado no formato Hexadecimal
isCIPCertificate	Verdadeiro se o certificado for no padrão CIP.

Os números de CA existentes consta no manual de segurança da RSFN.

Exceções

DinamoException.DinamoException Em caso de erro

Exemplos: spb_import_activate.cs.

◆ SPBImportCertificate() [3/3]

void SPBImportCertificate	(	string	szNamespace,
		string	szDomain,
		byte[]	bCertificate,
		bool	isCIPCertificate = false )

inline

Ativa um certificado que já foi importado para o HSM. Se houver um outro certificado ativo, ele será inativado.Somente um certificado permanecerá ativo por instituição, por domínio dentro de um namespace do HSM.

Parâmetros

szNamespace	Partição onde está o objeto.Se o objeto estiver na mesma partição logada, pode passar `null`.
szDomain	Dominio do SPB.
bCertificate	Certificado SPB no padrão SPB como um array de bytes.
isCIPCertificate	Verdadeiro se o certificado for no padrão CIP.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBActivateCertificate() [2/2]

void SPBActivateCertificate	(	string	szNamespace,
		string	szDomain,
		string	szCA,
		string	szSN,
		bool	isCIPCertificate = false )

inline

Ativa um certificado que já foi importado para o HSM. Se houver um outro certificado ativo, ele será inativado.Somente um certificado permanecerá ativo por instituição, por domínio dentro de um namespace do HSM.

Parâmetros

szNamespace	Partição onde está o objeto.Se o objeto estiver na mesma partição logada, pode passar `null`.
szDomain	Dominio do SPB.
szCA	Identificação da CA (número da CA).
szSN	Número de série do certificado no formato Hexadecimal
isCIPCertificate	Verdadeiro se o certificado for no padrão CIP.

Os números de CA existentes consta no manual de segurança da RSFN.

Exceções

DinamoException.DinamoException Em caso de erro

◆ SPBCalculateObjectId()

string SPBCalculateObjectId	(	string	szISPB,
		string	szDomain,
		KEYNAME	dwKeyType )

inline

Função para auxiliar a formatação da identificação de objetos internos do HSM segundo o padrão utilizado no móduloSPB.

Parâmetros

szISPB	identificação do ISPB no formato "<ISPB>@<Dominio>". Por exemplo: "11223344@SPR".
szDomain	Dominio do SPB.
dwKeyType	Tipo de objeto. Dinamo.Hsm.DinamoClient.KEYNAME

Retorna: Nome no formato do móduloSPB.

◆ SPBGetCertificateInfo()

DinamoApi.SPB_CERT_X509_INFO SPBGetCertificateInfo ( byte[] certificate )

inline

Recupera informações do certificado.

Parâmetros

certificate Array de bytes com o certificado

Retorna: Informções do certificado. DinamoApi.SPB_CERT_X509_INFO

Exceções

DinamoException Lança exceção em caso de erro.

Exemplos: spb_import_activate.cs.