XML

Descripción detallada

Firma XML, incluida la factura electrónica (NF-e)

Las funciones de firma XML se ajustan a la norma para firmas digitales en formato XML (Extended Markup Language) definida por el consorcio W3C (World Wide Web Consortium), con el fin de garantizar la interoperabilidad, es decir, los documentos XML firmados por el HSM pueden verificarse en otros entornos que se adhieran a las normas del W3C, y el HSM puede verificar firmas en documentos XML firmados externamente.

Las funciones de la API para su uso con la firma XML requieren el almacenamiento interno en el HSM de los certificados digitales para la firma digital y la cadena de confianza completa de los certificados para la verificación.

Para escribir un certificado digital (o un archivo) en el HSM, utilice la consola de gestión remota o la API DWriteFile().

El certificado digital para la firma debe estar codificado en formato binario ASN1 DER y seguir también el estándar X.509. El archivo que contiene la cadena de confianza para verificar la firma digital debe estar codificado en formato PKCS#7 (Public Key Cryptography Standard #7 - Cryptographic Message Syntax Standard).

Firma XML, incluida la factura electrónica (NF-e) Más...

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

Funciones

DSignXml()

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

#include <dinamo.h>

Obsoleto

Esta API está descatalogada, utilice la función DSignXml2().

Firma digitalmente un documento XML utilizando los estándares de firma digital XML del W3C y el RFC 3275.

Parámetros

[en]	hKey	Contexto de la clave privada que se utilizará en la firma.
[en]	hHash	Contexto hash generado por la función DCreateHash().
[en]	szCertId	Nombre del certificado digital equivalente utilizado para firmar el documento XML.
[en]	dwSizeUnsignedXml	Tamaño, en bytes, del XML original en pbUnsignedXml.
[en]	pbUnsignedXml	Buffer que contiene el XML original.
[en]	dwFilterLen	Tamaño, en bytes, del filtro indicado por pbFiltro.
[en]	pbFiltro	Filtro para firmar digitalmente partes del documento. El uso de filtros es opcional. Si no utiliza filtros, pase 0 (cero) en dwFilterLen. Consulte Uso de filtros XML para obtener más información sobre los filtros.
[fuera]	pdwSizeSignedXml	Puntero al tamaño del XML firmado, en bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en ppbSignedXml.
[fuera]	ppbSignedXml	Puntero con el retorno al XML firmado. La asignación de memoria se realiza internamente. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree(). Consulte los comentarios para obtener más información.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

No es necesario indicar el contexto de la sesión. Éste se obtiene mediante hKey.

El búfer ppbSignedXml para devolver el XML firmado se asignará internamente. La aplicación debe liberar la memoria utilizando la API DFree(). La función DSignXml() devolverá D_ERR_INVALID_CERTIFICATE si el certificado digital indicado no coincide con la clave hKey. Si el XML original no está bien formado, la función devolverá D_ERR_CANNOT_ALLOC_RES.

La representación física o forma canónica utilizada en la firma se ajusta a la recomendación del W3C, versión 1.0 de 15 de marzo de 2001(http://www.w3.org/TR/2001/REC-xml-c14n-20010315). Las transformaciones utilizadas en la firma (Enveloped y C14N) son conformes con la sección 6.6.4 de la recomendación XML del W3C de 12 de febrero de 2002 - Enveloped Signature Transform(http://www.w3.org/2000/09/xmldsig#enveloped-signature) y con la canonicalización descrita anteriormente(http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

Es posible firmar digitalmente parte del XML mediante filtros, utilizando los siguientes parámetros dwFilterLen e pbFiltro. Consulte Uso de filtros XML para obtener más información sobre los filtros.

DSignXml2()

int AAP_API DSignXml2	(	HSESSIONCTX	hSesión,
		BYTE	bHashMode,
		DWORD	dwFlags,
		const char *	szKeyId,
		const char *	szCertId,
		DWORD	dwSizeUnsignedXml,
		BYTE *	pbUnsignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFiltro,
		DWORD *	pdwSizeSignedXml,
		BYTE **	ppbSignedXml )

#include <dinamo.h>

Firma digitalmente un documento XML utilizando los estándares de firma digital XML del W3C y el RFC 3275.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	bHashMode	Tipo de hash utilizado en la firma. Se aceptan los valores de la tabla siguiente. Valor Significado ALG_MD5_InclC14N MD5 con canonización InclC14N ALG_SHA1_InclC14N SHA1 con canonización InclC14N ALG_SHA256_InclC14N SHA256 con canonización InclC14N ALG_SHA384_InclC14N SHA384 con canonización InclC14N ALG_SHA512_InclC14N SHA512 con canonización InclC14N ALG_SHA224_InclC14N SHA224 con canonización InclC14N ALG_MD5_ExclC14N MD5 con canonización ExclC14N ALG_SHA1_ExclC14N SHA1 con canonización ExclC14N ALG_MD5_InclC14NConComentarios MD5 con canonización InclC14NWithComments ALG_SHA1_InclC14NConComentarios SHA1 con canonicalización InclC14NWithComments ALG_MD5_ExclC14NConComentarios MD5 con canonización ExclC14NWithComments ALG_SHA1_ExclC14NConComentarios SHA1 con canonización ExclC14NWithComments ALG_SHA256_ExclC14N SHA256 con canonización ExclC14N ALG_SHA256_InclC14NConComentarios SHA256 con canonización InclC14NWithComment ALG_SHA256_ExclC14NConComentarios SHA256 con canonización ExclC14NWithComment ALG_SHA384_ExclC14N SHA384 con canonización ExclC14N ALG_SHA384_InclC14NConComentarios SHA384 con canonización InclC14NWithComment ALG_SHA384_ExclC14NConComentarios SHA384 con canonización ExclC14NWithComment ALG_SHA512_ExclC14N SHA512 con canonización ExclC14N ALG_SHA512_InclC14NConComentarios SHA512 con canonicalización InclC14NWithComment ALG_SHA512_ExclC14NConComentarios SHA512 con canonización ExclC14NWithComment ALG_SHA224_ExclC14N SHA224 con canonización ExclC14N ALG_SHA224_InclC14NConComentarios SHA224 con canonización InclC14NWithComment ALG_SHA224_ExclC14NConComentarios SHA224 con canonización ExclC14NWithComment
[en]	dwFlags	Banderas que contienen las opciones de suscripción. Se acepta la tabla siguiente. Valor Significado XML_SIGN_FLAGS_NOL Desactiva la generación de XML de una sola línea. Esta opción genera el XML de salida en varias líneas. XML_SIGN_FLAGS_NO_RNS Desactiva el uso de espacios de nombres relativos.
[en]	szKeyId	Nombre de la clave privada utilizada para firmar.
[en]	szCertId	Nombre del certificado digital equivalente utilizado para firmar el documento XML.
[en]	dwSizeUnsignedXml	Tamaño, en bytes, del XML original en pbUnsignedXml.
[en]	pbUnsignedXml	Buffer que contiene el XML original.
[en]	dwFilterLen	Tamaño, en bytes, del filtro indicado por pbFiltro.
[en]	pbFiltro	Filtro para firmar digitalmente partes del documento. El uso de filtros es opcional. Si no utiliza filtros, pase 0 (cero) en dwFilterLen. Consulte Uso de filtros XML para obtener más información sobre los filtros.
[fuera]	pdwSizeSignedXml	Puntero al tamaño del XML firmado, en bytes. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en ppbSignedXml.
[fuera]	ppbSignedXml	Puntero con el retorno al XML firmado. La asignación de memoria se realiza internamente. La aplicación que llama es responsable de liberar la memoria asignada utilizando la API DFree(). Consulte los comentarios para obtener más información.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

No es necesario indicar el contexto de la sesión. Éste se obtiene mediante hKey.

El búfer ppbSignedXml para devolver el XML firmado se asignará internamente. La aplicación debe liberar la memoria utilizando la API DFree(). La función DSignXml() devolverá D_ERR_INVALID_CERTIFICATE si el certificado digital indicado no coincide con la clave hKey. Si el XML original no está bien formado, la función devolverá D_ERR_CANNOT_ALLOC_RES.

La representación física o forma canónica utilizada en la firma se ajusta a la recomendación del W3C, versión 1.0 de 15 de marzo de 2001(http://www.w3.org/TR/2001/REC-xml-c14n-20010315). Las transformaciones utilizadas en la firma (Enveloped y C14N) son conformes con la sección 6.6.4 de la recomendación XML del W3C de 12 de febrero de 2002 - Enveloped Signature Transform(http://www.w3.org/2000/09/xmldsig#enveloped-signature) y con la canonicalización descrita anteriormente(http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

Es posible firmar digitalmente parte del XML mediante filtros, utilizando los siguientes parámetros dwFilterLen e pbFiltro. Consulte Uso de filtros XML para obtener más información sobre los filtros.

Ejemplos

sign_verify_xml.c.

DVerifySignedXml()

int AAP_API DVerifySignedXml	(	HSESSIONCTX	hSesión,
		char *	szCertsId,
		DWORD	dwSizeSignedXml,
		BYTE *	pbSignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFiltro )

#include <dinamo.h>

Verifica la firma de un documento XML firmado digitalmente utilizando los estándares de firma digital XML del W3C y el RFC 3275.

Obsoleto

Las aplicaciones deben utilizar la API extendida DVerifySignedXmlEx(), que verifica el documento XML firmado consultando una lista de certificados revocados.

DVerifySignedXmlEx()

int AAP_API DVerifySignedXmlEx	(	HSESSIONCTX	hSesión,
		char *	szCertsId,
		DWORD	dwSizeSignedXml,
		BYTE *	pbSignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFiltro,
		char *	szCRL )

#include <dinamo.h>

Verifica la firma de un documento XML firmado digitalmente utilizando los estándares de firma digital XML del W3C y el RFC 3275.

Parámetros

[en]	hSesión	Contexto adquirido a través de la función DOpenSession().
[en]	szCertsId	Nombre de la cadena PKCS#7 -almacenada internamente en el HSM- del certificado utilizado para firmar el documento XML.
[en]	dwSizeSignedXml	Tamaño, en bytes, del XML firmado en pbSignedXml.
[en]	pbSignedXml	XML firmado.
[en]	dwFilterLen	Tamaño, en bytes, del filtro indicado por pbFiltro.
[en]	pbFiltro	Filtro para firmar digitalmente partes del documento XML. Consulte Uso de filtros XML para obtener más información sobre filtros.
[en]	szCRL	Nombre de la lista de revocación de certificados (CRL) -almacenada internamente en el HSM- en la que se verificará el certificado digital. Es posible pasar NULL indicando que no hay CRL que comprobar.

Devolución

0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas

La función DVerifySignedXmlEx( ) devolverá ERR_VERIFY_XML_FAILED si la firma digital no es válida o correcta. Si el XML firmado no está bien formado, la función devolverá ERR_INVALID_XML.

Si se ha firmado un XML con un filtro, la comprobación debe indicar el mismo filtro. Consulte Uso de filtros XML para obtener más información sobre filtros.

Ver también

DSignXml().

Ejemplos

sign_verify_xml.c.