XML

Detailed description

XML Signature, including Electronic Invoice (NF-e)

The XML signature functions are in accordance with the standard for digital signatures in XML (Extended Markup Language) format defined by the W3C (World Wide Web Consortium) consortium, in order to guarantee interoperability, i.e. XML documents signed by the HSM can be verified in other environments adhering to W3C standards, and the HSM can verify signatures on XML documents signed externally.

The API functions for use with XML signing require the internal storage in the HSM of the digital certificates for digital signing and the complete chain of trust of the certificates for verification.

To write a digital certificate (or file) to the HSM, use the remote management console or the DWriteFile() API.

The digital certificate for signing must be encoded in ASN1 DER binary format and also follow the X.509 standard. The file containing the chain of trust for verifying the digital signature must be encoded in PKCS#7 format (Public Key Cryptography Standard #7 - Cryptographic Message Syntax Standard).

XML Signature, including Electronic Invoice (NF-e) More...

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

Functions

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>

Obsolete

This API is discontinued, use the DSignXml2() function.

Digitally signs an XML document using the W3C XML digital signature standards and RFC 3275.

Parameters

[in]	hKey	Context of the private key to be used in the signature.
[in]	hHash	Hash context generated by the DCreateHash() function.
[in]	szCertId	Name of the equivalent digital certificate used to sign the XML document.
[in]	dwSizeUnsignedXml	Size, in bytes, of the original XML in pbUnsignedXml.
[in]	pbUnsignedXml	Buffer containing the original XML.
[in]	dwFilterLen	Size, in bytes, of the filter indicated by pbFilter.
[in]	pbFilter	Filter for digitally signing parts of the document. The use of filters is optional. If you don't use filters, enter 0 (zero) in dwFilterLen. Consult Use of XML filters for more information on filters.
[out]	pdwSizeSignedXml	Pointer to the size of the signed XML, in bytes. When the function returns, this parameter will contain the size of the data stored in ppbSignedXml.
[out]	ppbSignedXml	Pointer with the return to the signed XML. Memory allocation is done internally. The calling application is responsible for freeing the allocated memory using the DFree() API. See comments for more information.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It is not necessary to indicate the context of the session. This is obtained via hKey.

The buffer ppbSignedXml to return the signed XML will be allocated internally. The application must release the memory using the API DFree(). The function DSignXml() will return D_ERR_INVALID_CERTIFICATE if the digital certificate indicated does not match the key hKey. If the original XML is not well-formed, the function will return D_ERR_CANNOT_ALLOC_RES.

The physical representation or canonical form used in the signature is in accordance with the W3C recommendation, Version 1.0 of March 15, 2001(http://www.w3.org/TR/2001/REC-xml-c14n-20010315). The transformations used in the signature (Enveloped and C14N) are in accordance with section 6.6.4 of the W3C XML recommendation of February 12, 2002 - Enveloped Signature Transform(http://www.w3.org/2000/09/xmldsig#enveloped-signature) and with the canonicalization described above(http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

It is possible to digitally sign part of the XML, through filters, using the following parameters dwFilterLen e pbFilter. Consult Use of XML filters for more information on filters.

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>

Digitally signs an XML document using the W3C XML digital signature standards and RFC 3275.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	bHashMode	Type of hash used in the signature. The values in the table below are accepted. Value Meaning ALG_MD5_InclC14N MD5 with InclC14N canonicalization ALG_SHA1_InclC14N SHA1 with InclC14N canonicalization ALG_SHA256_InclC14N SHA256 with InclC14N canonicalization ALG_SHA384_InclC14N SHA384 with InclC14N canonicalization ALG_SHA512_InclC14N SHA512 with InclC14N canonicalization ALG_SHA224_InclC14N SHA224 with InclC14N canonicalization ALG_MD5_ExclC14N MD5 with ExclC14N canonicalization ALG_SHA1_ExclC14N SHA1 with ExclC14N canonicalization ALG_MD5_InclC14NWithComments MD5 with InclC14NWithComments canonicalization ALG_SHA1_InclC14NWithComments SHA1 with canonicalization InclC14NWithComments ALG_MD5_ExclC14NWithComments MD5 with ExclC14NWithComments canonicalization ALG_SHA1_ExclC14NWithComments SHA1 with canonicalization ExclC14NWithComments ALG_SHA256_ExclC14N SHA256 with ExclC14N canonicalization ALG_SHA256_InclC14NWithComments SHA256 with canonicalization InclC14NWithComment ALG_SHA256_ExclC14NWithComments SHA256 with ExclC14NWithComment canonicalization ALG_SHA384_ExclC14N SHA384 with ExclC14N canonicalization ALG_SHA384_InclC14NWithComments SHA384 with canonicalization InclC14NWithComment ALG_SHA384_ExclC14NWithComments SHA384 with ExclC14NWithComment canonicalization ALG_SHA512_ExclC14N SHA512 with ExclC14N canonicalization ALG_SHA512_InclC14NWithComments SHA512 with canonicalization InclC14NWithComment ALG_SHA512_ExclC14NWithComments SHA512 with ExclC14NWithComment canonicalization ALG_SHA224_ExclC14N SHA224 with ExclC14N canonicalization ALG_SHA224_InclC14NWithComments SHA224 with canonicalization InclC14NWithComment ALG_SHA224_ExclC14NWithComments SHA224 with ExclC14NWithComment canonicalization
[in]	dwFlags	Flags containing the subscription options. The table below is accepted. Value Meaning XML_SIGN_FLAGS_NOL Disables the generation of single-line XML. This option generates the output XML in multiple lines. XML_SIGN_FLAGS_NO_RNS Disables the use of relative namespaces.
[in]	szKeyId	Name of the private key used for signing.
[in]	szCertId	Name of the equivalent digital certificate used to sign the XML document.
[in]	dwSizeUnsignedXml	Size, in bytes, of the original XML in pbUnsignedXml.
[in]	pbUnsignedXml	Buffer containing the original XML.
[in]	dwFilterLen	Size, in bytes, of the filter indicated by pbFilter.
[in]	pbFilter	Filter for digitally signing parts of the document. The use of filters is optional. If you don't use filters, enter 0 (zero) in dwFilterLen. Consult Use of XML filters for more information on filters.
[out]	pdwSizeSignedXml	Pointer to the size of the signed XML, in bytes. When the function returns, this parameter will contain the size of the data stored in ppbSignedXml.
[out]	ppbSignedXml	Pointer with the return to the signed XML. Memory allocation is done internally. The calling application is responsible for freeing the allocated memory using the DFree() API. See comments for more information.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

It is not necessary to indicate the context of the session. This is obtained via hKey.

The buffer ppbSignedXml to return the signed XML will be allocated internally. The application must release the memory using the API DFree(). The function DSignXml() will return D_ERR_INVALID_CERTIFICATE if the digital certificate indicated does not match the key hKey. If the original XML is not well-formed, the function will return D_ERR_CANNOT_ALLOC_RES.

The physical representation or canonical form used in the signature is in accordance with the W3C recommendation, Version 1.0 of March 15, 2001(http://www.w3.org/TR/2001/REC-xml-c14n-20010315). The transformations used in the signature (Enveloped and C14N) are in accordance with section 6.6.4 of the W3C XML recommendation of February 12, 2002 - Enveloped Signature Transform(http://www.w3.org/2000/09/xmldsig#enveloped-signature) and with the canonicalization described above(http://www.w3.org/TR/2001/REC-xml-c14n-20010315).

It is possible to digitally sign part of the XML, through filters, using the following parameters dwFilterLen e pbFilter. Consult Use of XML filters for more information on filters.

Examples

sign_verify_xml.c.

DVerifySignedXml()

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

#include <dinamo.h>

Verifies the signature of a digitally signed XML document using the W3C XML digital signature standards and RFC 3275.

Obsolete

Applications must use the DVerifySignedXmlEx() extended API, which checks the signed XML document against a list of revoked certificates.

DVerifySignedXmlEx()

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

#include <dinamo.h>

Verifies the signature of a digitally signed XML document using the W3C XML digital signature standards and RFC 3275.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szCertsId	Name of the PKCS#7 chain - stored internally in the HSM - of the certificate used to sign the XML document.
[in]	dwSizeSignedXml	Size, in bytes, of the XML signed on pbSignedXml.
[in]	pbSignedXml	Signed XML.
[in]	dwFilterLen	Size, in bytes, of the filter indicated by pbFilter.
[in]	pbFilter	Filter for digitally signing parts of the XML document. See Using XML filters for more information on filters.
[in]	szCRL	Name of the Certificate Revocation List (CRL) - stored internally in the HSM - where the digital certificate will be verified. It is possible to pass NULL indicating that there is no CRL to check.

Return

0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The DVerifySignedXmlEx() function will return ERR_VERIFY_XML_FAILED if the digital signature is not valid or correct. If the signed XML is not well formed, the function will return ERR_INVALID_XML.

If an XML has been signed with a filter, the check must indicate the same filter. See Using XML filters for more information on filters.

See also

DSignXml().

Examples

sign_verify_xml.c.