XML

Descripción detallada

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

Consulte la documentación técnica del HSM

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 *	pbFilter,
		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

[in]	hKey	Contexto de la clave privada que se utilizará en la firma.
[in]	hHash	Contexto hash generado por la función DCreateHash().
[in]	szCertId	Nombre del certificado digital equivalente utilizado para firmar el documento XML.
[in]	dwSizeUnsignedXml	Tamaño, en bytes, del XML original en pbUnsignedXml.
[in]	pbUnsignedXml	Buffer que contiene el XML original.
[in]	dwFilterLen	Tamaño, en bytes, del filtro indicado por pbFiltro.
[in]	pbFilter	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.
[out]	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.
[out]	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	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>

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

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	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
[in]	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.
[in]	szKeyId	Nombre de la clave privada utilizada para firmar.
[in]	szCertId	Nombre del certificado digital equivalente utilizado para firmar el documento XML.
[in]	dwSizeUnsignedXml	Tamaño, en bytes, del XML original en pbUnsignedXml.
[in]	pbUnsignedXml	Buffer que contiene el XML original.
[in]	dwFilterLen	Tamaño, en bytes, del filtro indicado por pbFiltro.
[in]	pbFilter	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.
[out]	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.
[out]	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	hSession,
		char *	szCertsId,
		DWORD	dwSizeSignedXml,
		BYTE *	pbSignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFilter )

#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	hSession,
		char *	szCertsId,
		DWORD	dwSizeSignedXml,
		BYTE *	pbSignedXml,
		DWORD	dwFilterLen,
		BYTE *	pbFilter,
		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

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	szCertsId	Nombre de la cadena PKCS#7 -almacenada internamente en el HSM- del certificado utilizado para firmar el documento XML.
[in]	dwSizeSignedXml	Tamaño, en bytes, del XML firmado en pbSignedXml.
[in]	pbSignedXml	XML firmado.
[in]	dwFilterLen	Tamaño, en bytes, del filtro indicado por pbFiltro.
[in]	pbFilter	Filtro para firmar digitalmente partes del documento XML. Consulte Uso de filtros XML para obtener más información sobre filtros.
[in]	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.