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

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

Descrição Detalhada

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

As funções de assinatura XML estão de acordo com o padrão para assinatura digital em formato XML (Extended Markup Language) definido pelo consórcio W3C (World Wide Web Consortium), de forma a garantir a interoperabilidade, ou seja, documentos XML assinados pelo HSM podem ser verificados em outros ambientes aderentes aos padrões W3C, e o HSM pode fazer a verificação de assinaturas em documentos XML assinados externamente.

As funções de API para uso com assinatura XML exigem o armazenamento interno no HSM dos certificados digitais para assinatura digital e da cadeia completa de confiança dos certificados para verificação.

Para um gravar um certificado digital (ou arquivo) no HSM utilize a console de gerenciamento remoto ou a API DWriteFile().

O certificado digital para assinatura deverá estar codificado no formato binário ASN1 DER e também seguir o padrão X.509 . O arquivo contendo a cadeia de confiança para verificação de assinatura digital deverá estar codificada no formato PKCS#7 (Public Key Cryptography Standard #7 – Cryptographic Message Syntax Standard).

Funções

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>

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 observações 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 documento XML original, indicado por pbUnsignedXml, poderá ser compactado de acordo com o padrão gzip descrito nas RFCs 1950 (zlib format), 1951 (deflate format) e 1952 (gzip format). O reconhecimento da compactação é automático pelo HSM. Caso o documento XML original esteja compactado, o documento XML assinado retornado também estará compactado pelo mesmo padrão gzip. As operações de descompactação, assinatura e compactação são independentes no HSM, caso ocorra um erro interno após a assinatura do XML e não seja possível devolver o documento XML assinado compactado, será retornado o documento XML assinado sem compactação. Embora um erro interno desta natureza seja bastante improvável, a aplicação precisa estar preparada para tratá-lo.

A compactação do documento XML não necessariamente traz um ganho de desempenho nas operações de assinatura. O ganho principal pode vir de uma redução sensível no uso de banda da rede. As circunstâncias específicas de cada ambiente devem ser analisadas para a adoção da compactação do documento XML.

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.

O filtro adota o seguinte formato: namespace|qualificador|id. O caracter separador é o | (pipe). O namespace é aquele definido no atributo xmlns, o qualificador pode estar presente em mais de uma tag e o id deve ser único no documento. Um filtro vazio indica que a assinatura abrange todo o documento. A construção de um filtro válido depende da estrutura do XML.

Num XML onde o namespace está definido os filtros válidos são:

"" (vazio)
"namespace|qualificador|id"

Num XML sem definição de namespace os filtros válidos são:

"" (vazio)
"|qualificador|id"

Exemplo de XML com namespace:

 <?xml version="1.0"?>
 <NFe xmlns="http://www.portalfiscal.inf.br/nfe">
 <infNFe Id="XFGR143576863578" versao="1.01">
 ...
 </infNFe>
 </NFe>

Neste exemplo o namespace é http://www.portalfiscal.inf.br/nfe, o qualificador da tag é infNFe e o id é XFGR143576863578.

Filtros válidos:

"" (vazio)
"http://www.portalfiscal.inf.br/nfe|infNFe|XFGR143576863578"

Exemplo de XML sem namespace:

 <?xml version="1.0"?>
 <NFe>
 <infNFe Id="XFGR143576863578" versao="1.01">
 ...
 </infNFe>
 </NFe>

Neste exemplo não há namespace (campo vazio no filtro), o qualificador da tag é infNFe e o id é XFGR143576863578. Note a presença do primeiro separador para marcar o namespace vazio.

Filtros válidos:

"" (vazio)
"|infNFe|XFGR143576863578"

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.

Descontinuado(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.

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 observações para maiores informações.
[in]	szCRL	Nome da Lista de Certificados Revogados (CRL) 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 D_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 D_ERR_CANNOT_ALLOC_RES.

O documento XML original poderá ser compactado de acordo com o padrão gzip descrito nas RFCs 1950 (zlib format), 1951 (deflate format) e 1952 (gzip format). O reconhecimento da compactação é automático pelo HSM.

A compactação do documento XML não necessariamente traz um ganho de desempenho nas operações de verificação. O ganho principal pode vir de uma redução sensível no uso de banda da rede. As circunstâncias específicas de cada ambiente devem ser analisadas para a adoção da compactação do documento XML.

É possível realizar a verificação da assinatura digital de parte do XML, através de filtros, utilizando os parâmetros dwFilterLen e pbFilter. Veja as anotações sobre filtros na API DSignXml(). Se um XML foi assinado com filtro a verificação deve indicar o mesmo filtro.

Veja também: DSignXml() .