SPB

Descrição detalhada

Operações de Encode e Decode conforme o padrão SPB.

Consulte a documentação técnica do HSM.

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, 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)

Funções

DSPBEncodeInit()

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 em casos específicos, ver dwFlags.
[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 em casos específicos, ver dwFlags.
[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 codificação, podendo assumir os seguintes valores descritos na tabela abaixo. Valor Signficado 0 Utiliza o padrão SPB (Sistema de Pagamentos Brasileiro). ND_SPB_ENCODE_GEN_01 Gera uma mensagem GEN 01. 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. Compatível com C3 Nuclea. ND_SPB_USE_ANY Aceita o padrão CIP/C3 Nuclea e SPB. A detecção é feita internamente. 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. 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

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().
Tipos de certificados:
SPB - O OU tem que conter o ISPB no formato prefixo "ISPB-" + 8 dígitos. Ex.: ISPB-11111111.
CIP1 - O OU tem que conter o ISPB no formato de 8 dígitos. Ex.: 11111111.

Exemplos

spb_enc_dec.c.

DSPBEncodeCont()

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 DN_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 a pbDataIn. Caso seja o último pedaço, adicionar espaço no tamanho para possível padding/tag. Recomenda-se utilizar um tamanho mínimo de DN_SPB_MAX_RCV_NOTIFY_DATA_SEG bytes para garantir o recebimento de todos os dados retornados.
[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

spb_enc_dec.c.

DSPBEncodeEnd()

int AAP_API DSPBEncodeEnd	(	HSPBCTX *	hSPBCtx,
		BYTE *	pbSPBHeader,
		DWORD *	pdwSPBHeaderLen )

#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 DN_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

spb_enc_dec.c.

DSPBDecodeInit()

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 em casos específicos, ver dwFlags.
[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 em casos específicos, ver dwFlags.
[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: GEN0006 (resposta), 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 0 Utiliza o padrão SPB (Sistema de Pagamentos Brasileiro). 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)/C3 Nuclea. Quando esta flag não está definida o padrão SPB(Sistema de Pagamentos Brasileiro) é utilizado. ND_SPB_USE_ANY Aceita o padrão CIP/C3 Nuclea e SPB. A detecção é feita internamente. 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

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(). O tratamento da GEN0006R1 (resposta da GEN0006) está disponível a partir da versão 5.0.16 do firmware.
Tipos de certificados:
SPB - O OU tem que conter o ISPB no formato prefixo "ISPB-" + 8 dígitos. Ex.: ISPB-11111111.
CIP1 - O OU tem que conter o ISPB no formato de 8 dígitos. Ex.: 11111111.

Exemplos

spb_enc_dec.c.

DSPBDecodeCont()

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

spb_enc_dec.c.

DSPBDecodeEnd()

int AAP_API DSPBDecodeEnd

(

HSPBCTX *

hSPBCtx

)

#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

spb_enc_dec.c.

DSPBGenerateKey()

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

spb_gen_key_csr.c.

DSPBGenerateCSR()

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.

Anotações

Exemplos de campo DN.

/CN=BANCO TESTE S/A P001/OU=SISBACEN-00888/OU=ISPB-54444619/O=ICP-Brasil/L=Sao Paulo/S=Sao Paulo/C=BR

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

spb_gen_key_csr.c.

DSPBImportCertificate()

int AAP_API DSPBImportCertificate	(	HSESSIONCTX	hSession,
		BYTE	bActivate,
		const char *	szUser,
		BYTE *	pbCertificate,
		DWORD	dwCertificateLen,
		const 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). ND_SPB_USE_ANY Aceita o padrão CIP e SPB. A detecção é feita internamente.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Tipos de certificados:
SPB - O OU tem que conter o ISPB no formato prefixo "ISPB-" + 8 dígitos. Ex.: ISPB-11111111.
CIP1 - O OU tem que conter o ISPB no formato de 8 dígitos. Ex.: 11111111.

Exemplos

spb_gen_key_csr.c.

DSPBImportPKCS12()

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>

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

spb_activate_cert.c, spb_enc_dec.c, spb_get_cert.c e spb_import_p12.c.

DSPBExportPKCS12()

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.

DSPBActivateCertificate()

int AAP_API DSPBActivateCertificate	(	HSESSIONCTX	hSession,
		const char *	szIdCert,
		const 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	Reservado para uso Futuro.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

spb_activate_cert.c.

DSPBGetCertificate()

int AAP_API DSPBGetCertificate	(	HSESSIONCTX	hSession,
		const 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

spb_get_cert.c.

DSPBCalculateObjectId()

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.

DSPBMapInfo()

int AAP_API DSPBMapInfo	(	HSESSIONCTX	hSession,
		const 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

spb_get_cert.c.

DSPBSetISPBMap()

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). ND_SPB_USE_ANY Aceita o padrão CIP e SPB. A detecção é feita internamente.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.