Api XML signature

XML files can be signed to prove their integrity. For signing XML files, you need a certificate and private key.
The different APIs available are below. The Syracuse module name (first parameter of ASYRWEBSER.EXEC_JS) is syracuse-xml/lib/helpers.

Sign XML data Verify XML data Sign XML file Verify XML file test whether certificate with given name exists

Sign XML data

This function signes the XML data and returns the signed XML data. Function name: sign.

Parameters

There is a callback parameter at first position.

Code Type and dimension Contents
XML Char XML data
PATH Value Array of Char. List of xpath expressions of parts of XML which should be signed (entry with empty string will sign the whole XML data)
CERTIFICATE Char. name of certificate in certificate entity (must be certificate with private key)
OPTIONS Char. Options. Must have JSON structure of Object with information:
  • signatureAlgorithm (optional) signature algorithm (default: "RSA-SHA256")
  • includeKeyInfo (optional) include key info into signature with certificate and details of public key
  • canonicalizationAlgorithm (optional): canonicalization algorithm (default: "http://www.w3.org/2001/10/xml-exc-c14n#"); currently no other algorithm supported
  • utf8 (optional boolean): XML data (with UTF8 encoding) have been read in UTF8 mode, not in binary mode. Output also for UTF8 mode.
  • prefix (optional): prefix for signature namespace
  • xades (optional): include basic Xades information. Object with information:
    • identifier: identifier, e. g. http://www.facturae.es/politica_de_firma_formato_facturae/politica_de_firma_formato_facturae_v3_1.pdf
    • description: description, e. g. facturae31
    • hashAlgorithm (optional) hash algorithm, default "SHA1", may be "SHA256", "SHA512"
    • hash (only necessary if 'document' is not given): value of hash, if document is not given, e. g. Ohixl6upD6av8N7pEvDABhEL6hM=
    • document (only necessary if 'hash' is not given): document to create hash from, given as a buffer
    • claimedRoles (optional): claimed roles (may be a single string, e. g. "emisor" or an array)
    • certifiedRoles (optional): certified roles

Sign XML file

This function reads the XML data in a file and writes the signed data to a file. You have to specify the folder name in the options unless you want to access files from Syracuse server. Function name: signfile.

Parameters

There is a callback parameter at first position.

Code Type and dimension Contents
XMLFILE Char absolute path of XML file
XMLOUTFILE Char absolute path of signed XML file which is created. May be equal to path in XMLFILE
PATH Value Array of Char. List of xpath expressions of parts of XML which should be signed (entry with empty string will sign the whole XML data)
CERTIFICATE Char. name of certificate in certificate entity (must be certificate with private key)
OPTIONS Char. Options. Must have JSON structure of Object with information:
  • folder: X3 folder (if empty, use Syracuse server for reading/writing)
  • endpoint: X3 endpoint (optional, if folder is not unique)
  • includeKeyInfo (optional) include key info into signature with certificate and details of public key
  • canonicalizationAlgorithm (optional): canonicalization algorithm (default: "http://www.w3.org/2001/10/xml-exc-c14n#"); currently no other algorithm supported
  • prefix (optional): prefix for signature namespace
  • xades (optional): include basic Xades information. Object with information:

verify XML data

This function verifies given XML string. It returns an array of verification errors. When the array is empty, verification is OK. Function name: verify.

Parameters

There is a callback parameter at first position.

Code Type and dimension Contents
XML Char XML data
NAME Char. Name of certificate in certificate entity.
OPTIONS Char. Options. Must have JSON structure of Object with information (should not be necessary at all):
  • utf8 (optional boolean): XML data (with UTF8 encoding) have been read in UTF8 mode, not in binary mode. Output also for UTF8 mode.

verify XML file

This function verifies given XML data in a file. It returns an array of verification errors. When the array is empty, verification is OK.
You have to specify the folder name in the options unless you want to access files from Syracuse server. Function name: verifyfile.

Parameters

There is a callback parameter at first position.

Code Type and dimension Contents
XMLFILE Char absolute path of file with XML data
NAME Char. Name of certificate in certificate entity.
OPTIONS Char. Options. Must have JSON structure of Object with information:
  • folder: X3 folder (if empty, use Syracuse server for reading/writing)
  • endpoint: X3 endpoint (optional, if folder is not unique)

check whether certificate exists with the given name

This function looks into the certificate entity and looks whether there is a certificate with the given name. It may also be searched for a certificate with private key. Return value: true, when certificate exists. Function name: certificateExists.

Parameters

There is a callback parameter at first position.

Code Type and dimension Contents
NAME Char. Name of certificate in certificate entity.
WITHKEY Boolean When true, it searches for a certificate with private key