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).
|
| byte[] | SignXML (string KeyId, HASH_ALG AlgId, string CertId, string UnsignedXml, string Filter) |
| | Digitally signs an XML document using the W3C XML digital signature standards. Receives parameters in string format.
|
| |
| byte[] | SignXML (string KeyId, HASH_ALG AlgId, string CertId, byte[] byUnsignedXml, byte[] byFilter) |
| | Digitally signs an XML document using the W3C XML digital signature standards. Receives parameters in byte array format.
|
| |
| byte[] | SignXML(HASH_MODE HashMode, Int32 Flags, string KeyId, string CertId, byte[] byUnsignedXml, byte[] byFilter) |
| | Digitally signs an XML document using the W3C XML digital signature standards. Receives parameters in byte array format.
|
| |
| bool | VerifySignedXML (string CertId, string SignedXml, string Filter) |
| | Checks the signature of a digitally signed XML document. Receives parameters in string format.
|
| |
| bool | VerifySignedXML (string CertId, byte[] bySignedXml, byte[] byFilter) |
| | verifies the signature of a digitally signed XML document. It receives the parameters in byte array format.
|
| |
◆ SignXML() [1/3]
| byte[] SignXML |
( |
string |
KeyId, |
|
|
HASH_ALG |
AlgId, |
|
|
string |
CertId, |
|
|
string |
UnsignedXml, |
|
|
string |
Filter |
|
) |
| |
|
inline |
Digitally signs an XML document using the W3C XML digital signature standards. Receives parameters in string format.
- See also
- SignXML(string KeyId, HASH_ALG AlgId, string CertId, byte[] byUnsignedXml, byte[] byFilter)
- Parameters
-
| KeyId | Identifier internal to the HSM referring to the key to be used for signing the XML document. |
| AlgId | Hash algorithm used. See: HASH_ALG |
| CertId | Identifier internal to the HSM referring to the digital certificate to be used for signing the XML document. |
| UnsignedXml | Parameter containing the XML to be signed. |
| Filter | Filter for digitally signing parts of the XML document. Use of the filter is optional. See Using XML filters. |
- Return
- Array of bytes containing the original digitally signed XML document in the specified format.
- Exceptions
-
| DinamoException | Throws exception in case of signature errors |
- Examples
- signxml.cs.
◆ SignXML() [2/3]
| byte[] SignXML |
( |
string |
KeyId, |
|
|
HASH_ALG |
AlgId, |
|
|
string |
CertId, |
|
|
byte[] |
byUnsignedXml, |
|
|
byte[] |
byFilter |
|
) |
| |
|
inline |
Digitally signs an XML document using the W3C XML digital signature standards. Receives parameters in byte array format.
- Parameters
-
| KeyId | Identifier internal to the HSM referring to the key to be used for signing the XML document. |
| AlgId | Hash algorithm used. See: HASH_ALG |
| CertId | Identifier internal to the HSM referring to the digital certificate to be used for signing the XML document. |
| byUnsignedXml | Parameter containing the XML to be signed.(*) |
| byFilter | Filter for digitally signing parts of the XML document. Use of the filter is optional. See Using XML filters. |
- Return
- Array of bytes containing the original digitally signed XML document in the specified format.
- Exceptions
-
| DinamoException | Throws exception in case of signature errors |
The original XML document, indicated by byUnsignedXmlThe file can be compressed according to the gzip standard described in RFCs 1950 (zlib format), 1951 (deflate format) and 1952 (gzip format). HSM automatically recognizes the compression. If the original XML document is compressed, the returned signed XML document will also be compressed using the same gzip standard. The decompression, signing and compression operations are independent in the HSM, so if an internal error occurs after signing the XML and it is not possible to return the compressed signed XML document, the signed XML document will be returned in plain text (without compression). Although such an internal error is highly unlikely, the application must be prepared to deal with it.
Compressing the XML document does not necessarily bring a performance gain in signing operations. The main gain can come from a significant reduction in network bandwidth usage. The specific circumstances of each environment must be analyzed when adopting XML document compression.
◆ SignXML() [3/3]
| byte[] SignXML |
( |
HASH_MODE |
HashMode, |
|
|
Int32 |
Flags, |
|
|
string |
KeyId, |
|
|
string |
CertId, |
|
|
byte[] |
byUnsignedXml, |
|
|
byte[] |
byFilter |
|
) |
| |
|
inline |
Digitally signs an XML document using the W3C XML digital signature standards. Receives parameters in byte array format.
- Parameters
-
| HashMode | Hash algorithm and canonicalization used. See: HASH_MODE |
| Flags | Hash algorithm and canonicalization used. Can be 0 or DinamoApi.XML_SIGN_FLAGS_NOL. |
| KeyId | Identifier internal to the HSM referring to the key to be used for signing the XML document. |
| CertId | Identifier internal to the HSM referring to the digital certificate to be used for signing the XML document. |
| byUnsignedXml | Parameter containing the XML to be signed.(*) |
| byFilter | Filter for digitally signing parts of the XML document. Use of the filter is optional. See Using XML filters. |
- Return
- Array of bytes containing the original digitally signed XML document in the specified format.
- Exceptions
-
| DinamoException | Throws exception in case of signature errors |
The original XML document, indicated by byUnsignedXmlThe file can be compressed according to the gzip standard described in RFCs 1950 (zlib format), 1951 (deflate format) and 1952 (gzip format). HSM automatically recognizes the compression. If the original XML document is compressed, the returned signed XML document will also be compressed using the same gzip standard. The decompression, signing and compression operations are independent in the HSM, so if an internal error occurs after signing the XML and it is not possible to return the compressed signed XML document, the signed XML document will be returned in plain text (without compression). Although such an internal error is highly unlikely, the application must be prepared to deal with it.
Compressing the XML document does not necessarily bring a performance gain in signing operations. The main gain can come from a significant reduction in network bandwidth usage. The specific circumstances of each environment must be analyzed when adopting XML document compression.
◆ VerifySignedXML() [1/2]
| bool VerifySignedXML |
( |
string |
CertId, |
|
|
string |
SignedXml, |
|
|
string |
Filter |
|
) |
| |
|
inline |
Checks the signature of a digitally signed XML document. Receives parameters in string format.
- Parameters
-
| CertId | Identifier internal to the HSM referring to the PKCS#7 chain - stored internally in the HSM - of the certificate used to sign the XML document |
| SignedXml | XML digitally signed in UTF-8. |
| Filter | Filter for checking the digital signature of parts of the XML document in UTF-8. Use of the filter is optional. See comments for more information on filters. |
- Return
- True if the check was successful.
- Exceptions
-
| DinamoException | Throws exception in case of error. |
- Examples
- signxml.cs.
◆ VerifySignedXML() [2/2]
| bool VerifySignedXML |
( |
string |
CertId, |
|
|
byte[] |
bySignedXml, |
|
|
byte[] |
byFilter |
|
) |
| |
|
inline |
verifies the signature of a digitally signed XML document. It receives the parameters in byte array format.
- Parameters
-
| CertId | Identifier internal to the HSM referring to the PKCS#7 chain - stored internally in the HSM - of the certificate used to sign the XML document |
| bySignedXml | Digitally signed XML |
| byFilter | Filter for checking the digital signature of parts of the XML document. The use of filters is optional. See comments for more information on filters. |
- Return
- True if the check was successful.
- Exceptions
-
| DinamoException | Throws exception in case of error. |
