XML

Descrição detalhada

Assinatura XML, incluindo Nota Fiscal Eletronica (NF-e)

Consulte a documentação técnica do HSM

Funções
int AAP_API	DSignXml (HKEYCTX hKey, HHASHCTX hHash, char *szCertId, DWORD dwSizeUnsignedXml, BYTE *pbUnsignedXml, DWORD dwFilterLen, BYTE *pbFilter, DWORD *pdwSizeSignedXml, BYTE **ppbSignedXml)
int AAP_API	DSignXml2 (HSESSIONCTX hSession, BYTE bHashMode, DWORD dwFlags, const char *szKeyId, const char *szCertId, DWORD dwSizeUnsignedXml, BYTE *pbUnsignedXml, DWORD dwFilterLen, BYTE *pbFilter, DWORD *pdwSizeSignedXml, BYTE **ppbSignedXml)
int AAP_API	DVerifySignedXml (HSESSIONCTX hSession, char *szCertsId, DWORD dwSizeSignedXml, BYTE *pbSignedXml, DWORD dwFilterLen, BYTE *pbFilter)
int AAP_API	DVerifySignedXmlEx (HSESSIONCTX hSession, char *szCertsId, DWORD dwSizeSignedXml, BYTE *pbSignedXml, DWORD dwFilterLen, BYTE *pbFilter, char *szCRL)

Funções

DSignXml()

int AAP_API DSignXml	(	HKEYCTX	hKey,
		HHASHCTX	hHash,
		char *	szCertId,
		DWORD	dwSizeUnsignedXml,
		BYTE *	pbUnsignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFilter,
		DWORD *	pdwSizeSignedXml,
		BYTE **	ppbSignedXml )

#include <dinamo.h>

Obsoleto(a)

Esta API está descontinuada, use a função DSignXml2().

Assina digitalmente um documento XML usando os padrões de assinatura digital XML do W3C e RFC 3275.

Parâmetros

[in]	hKey	Contexto da chave privada a ser utilizada na assinatura.
[in]	hHash	Contexto de hash gerado pela função DCreateHash().
[in]	szCertId	Nome do certificado digital equivalente utilizado para assinatura do documento XML.
[in]	dwSizeUnsignedXml	Tamanho, em bytes, do XML original em pbUnsignedXml.
[in]	pbUnsignedXml	Buffer contendo o XML original.
[in]	dwFilterLen	Tamanho, em bytes, do filtro indicado por pbFilter.
[in]	pbFilter	Filtro para assinatura digital de partes do documento. A utilização de filtro é opcional. Caso não utilize filtros, passe 0 (zero) em dwFilterLen. Consulte Uso dos filtros XML para maiores informações sobre filtros.
[out]	pdwSizeSignedXml	Ponteiro para o tamanho do XML assinado, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em ppbSignedXml.
[out]	ppbSignedXml	Ponteiro de ponteiro com o retorno para o XML assinado. A alocação de memória é feita internamente. A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree(). Consulte observações para maiores informações.

Retorna

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

Anotações

Não é necessário indicar o contexto da sessão. O mesmo é obtido por intermédio de hKey.

O buffer ppbSignedXml para retorno do XML assinado será alocado internamente. A aplicação deverá fazer a liberação da memória usando a API DFree(). A função DSignXml() irá retornar D_ERR_INVALID_CERTIFICATE caso o certificado digital indicado não seja correspondente com a chave hKey. Se o XML original não estiver bem formado, a função irá retornar D_ERR_CANNOT_ALLOC_RES.

A representação física ou forma canônica usada na assinatura está de acordo com a recomendação W3C, Versão 1.0 de 15 Março de 2001 (http://www.w3.org/TR/2001/REC-xml-c14n-20010315). As transformações usadas na assinatura (Enveloped e C14N) estão de acordo com a seção 6.6.4 da recomendação XML W3C de 12 de fevereiro de 2002 - Enveloped Signature Transform (http://www.w3.org/2000/09/xmldsig#enveloped-signature) e com a canonicalização descrita anteriormente (http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

É possível realizar assinatura digital de parte do XML, através de filtros, utilizando os parâmetros dwFilterLen e pbFilter. Consulte Uso dos filtros XML para maiores informações sobre filtros.

DSignXml2()

int AAP_API DSignXml2	(	HSESSIONCTX	hSession,
		BYTE	bHashMode,
		DWORD	dwFlags,
		const char *	szKeyId,
		const char *	szCertId,
		DWORD	dwSizeUnsignedXml,
		BYTE *	pbUnsignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFilter,
		DWORD *	pdwSizeSignedXml,
		BYTE **	ppbSignedXml )

#include <dinamo.h>

Assina digitalmente um documento XML usando os padrões de assinatura digital XML do W3C e RFC 3275.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	bHashMode	Tipo de hash utilizado na assinatura. Os valores da tabela abaixo são aceitos. Valor Significado ALG_MD5_InclC14N MD5 com canonicalização InclC14N ALG_SHA1_InclC14N SHA1 com canonicalização InclC14N ALG_SHA256_InclC14N SHA256 com canonicalização InclC14N ALG_SHA384_InclC14N SHA384 com canonicalização InclC14N ALG_SHA512_InclC14N SHA512 com canonicalização InclC14N ALG_SHA224_InclC14N SHA224 com canonicalização InclC14N ALG_MD5_ExclC14N MD5 com canonicalização ExclC14N ALG_SHA1_ExclC14N SHA1 com canonicalização ExclC14N ALG_MD5_InclC14NWithComments MD5 com canonicalização InclC14NWithComments ALG_SHA1_InclC14NWithComments SHA1 com canonicalização InclC14NWithComments ALG_MD5_ExclC14NWithComments MD5 com canonicalização ExclC14NWithComments ALG_SHA1_ExclC14NWithComments SHA1 com canonicalização ExclC14NWithComments ALG_SHA256_ExclC14N SHA256 com canonicalização ExclC14N ALG_SHA256_InclC14NWithComments SHA256 com canonicalização InclC14NWithComment ALG_SHA256_ExclC14NWithComments SHA256 com canonicalização ExclC14NWithComment ALG_SHA384_ExclC14N SHA384 com canonicalização ExclC14N ALG_SHA384_InclC14NWithComments SHA384 com canonicalização InclC14NWithComment ALG_SHA384_ExclC14NWithComments SHA384 com canonicalização ExclC14NWithComment ALG_SHA512_ExclC14N SHA512 com canonicalização ExclC14N ALG_SHA512_InclC14NWithComments SHA512 com canonicalização InclC14NWithComment ALG_SHA512_ExclC14NWithComments SHA512 com canonicalização ExclC14NWithComment ALG_SHA224_ExclC14N SHA224 com canonicalização ExclC14N ALG_SHA224_InclC14NWithComments SHA224 com canonicalização InclC14NWithComment ALG_SHA224_ExclC14NWithComments SHA224 com canonicalização ExclC14NWithComment
[in]	dwFlags	Flags contendo as opções de assinatura. A tabela abaixo é aceita. Valor Significado XML_SIGN_FLAGS_NOL Desabilita a geração de XML de apenas 1 linha("single line"). Esta opção gera o XML de saída em múltiplas linhas. XML_SIGN_FLAGS_NO_RNS Desabilita o uso de namespaces relativos.
[in]	szKeyId	Nome da chave privada utilizada para assinatura.
[in]	szCertId	Nome do certificado digital equivalente utilizado para assinatura do documento XML.
[in]	dwSizeUnsignedXml	Tamanho, em bytes, do XML original em pbUnsignedXml.
[in]	pbUnsignedXml	Buffer contendo o XML original.
[in]	dwFilterLen	Tamanho, em bytes, do filtro indicado por pbFilter.
[in]	pbFilter	Filtro para assinatura digital de partes do documento. A utilização de filtro é opcional. Caso não utilize filtros, passe 0 (zero) em dwFilterLen. Consulte Uso dos filtros XML para maiores informações sobre filtros.
[out]	pdwSizeSignedXml	Ponteiro para o tamanho do XML assinado, em bytes. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em ppbSignedXml.
[out]	ppbSignedXml	Ponteiro de ponteiro com o retorno para o XML assinado. A alocação de memória é feita internamente. A aplicação chamadora é responsável por liberar a memória alocada usando a API DFree(). Consulte observações para maiores informações.

Retorna

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

Anotações

Não é necessário indicar o contexto da sessão. O mesmo é obtido por intermédio de hKey.

O buffer ppbSignedXml para retorno do XML assinado será alocado internamente. A aplicação deverá fazer a liberação da memória usando a API DFree(). A função DSignXml() irá retornar D_ERR_INVALID_CERTIFICATE caso o certificado digital indicado não seja correspondente com a chave hKey. Se o XML original não estiver bem formado, a função irá retornar D_ERR_CANNOT_ALLOC_RES.

A representação física ou forma canônica usada na assinatura está de acordo com a recomendação W3C, Versão 1.0 de 15 Março de 2001 (http://www.w3.org/TR/2001/REC-xml-c14n-20010315). As transformações usadas na assinatura (Enveloped e C14N) estão de acordo com a seção 6.6.4 da recomendação XML W3C de 12 de fevereiro de 2002 - Enveloped Signature Transform (http://www.w3.org/2000/09/xmldsig#enveloped-signature) e com a canonicalização descrita anteriormente (http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

É possível realizar assinatura digital de parte do XML, através de filtros, utilizando os parâmetros dwFilterLen e pbFilter. Consulte Uso dos filtros XML para maiores informações sobre filtros.

Exemplos

sign_verify_xml.c.

DVerifySignedXml()

int AAP_API DVerifySignedXml	(	HSESSIONCTX	hSession,
		char *	szCertsId,
		DWORD	dwSizeSignedXml,
		BYTE *	pbSignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFilter )

#include <dinamo.h>

Verifica a assinatura de um documento XML assinado digitalmente usando os padrões de assinatura digital XML do W3C e RFC 3275.

Obsoleto(a)

As aplicações devem utilizar a API estendida DVerifySignedXmlEx(), que faz a verificação do documento XML assinado consultando uma lista indicada de certificados revogados.

DVerifySignedXmlEx()

int AAP_API DVerifySignedXmlEx	(	HSESSIONCTX	hSession,
		char *	szCertsId,
		DWORD	dwSizeSignedXml,
		BYTE *	pbSignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFilter,
		char *	szCRL )

#include <dinamo.h>

Verifica a assinatura de um documento XML assinado digitalmente usando os padrões de assinatura digital XML do W3C e RFC 3275.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szCertsId	Nome da cadeia PKCS#7 – armazenada internamente no HSM - do certificado utilizado na assinatura do documento XML.
[in]	dwSizeSignedXml	Tamanho, em bytes, do XML assinado em pbSignedXml.
[in]	pbSignedXml	XML assinado.
[in]	dwFilterLen	Tamanho, em bytes, do filtro indicado por pbFilter.
[in]	pbFilter	Filtro para assinatura digital de partes do documento XML. Consulte Uso dos filtros XML para maiores informações sobre filtros.
[in]	szCRL	Nome da Lista de Certificados Revogados (CRL) – armazenada internamente no HSM - onde o certificado digital será verificado. É possível passar NULL indicando que não há uma CRL para verificação.

Retorna

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

Anotações

A função DVerifySignedXmlEx() irá retornar ERR_VERIFY_XML_FAILED caso a assinatura digital não esteja válida ou correta. Se o XML assinado não estiver bem formado, a função irá retornar ERR_INVALID_XML.

Se um XML foi assinado com filtro a verificação deve indicar o mesmo filtro. Consulte Uso dos filtros XML para maiores informações sobre filtros.

Veja também

DSignXml() .

Exemplos

sign_verify_xml.c.