The C/C++ interface to the diFirmaSat2.dll library. More...

Macros
#define	SAT_ENCODE_LATIN1 1
	Encode output in Latin-1 (ISO-8859-1)

#define	SAT_ENCODE_UTF8 0
	Encode output in UTF-8 (default)

#define	SAT_FILE_BIGFILE 0x8000000
	Speed up the processing of large files (not TFD)

#define	SAT_FILE_NO_BOM 0x2000
	Create output XML file without UTF-8 byte-order mark (BOM)

#define	SAT_FORMAT_BINARY 0x40000
	Output PFX file in binary DER form with SAT_WritePfxFile()

#define	SAT_FORMAT_PEM 0x10000
	Output key or PFX file in PEM textual form with SAT_NewKeyFile() and SAT_WritePfxFile().

#define	SAT_GEN_DIGALG 0x2000
	Flag to return default digest algorithm with SAT_XmlReceiptVersion()

#define	SAT_GEN_PLATFORM 0x40
	Flag to retrieve platform type with SAT_ModuleName()

#define	SAT_HASH_DEFAULT 0
	Use default hash algorithm.

#define	SAT_KEY_ENCRYPTED 0x10000
	Get private key as PEM-style encrypted private key with SAT_GetKeyAsString()

#define	SAT_MAX_ERROR_CHARS 4073
	Maximum number of characters in an error message.

#define	SAT_MAX_HASH_CHARS 64
	Maximum number of characters in hex-encoded hash digest value.

#define	SAT_TFD 0x8000
	Operate on Timbre Fiscal Digital (TFD) instead of Combrobante.

#define	SAT_XML_EMPTYELEMTAG 0x20000
	Output XML elements with no content in empty-element tag form.

#define	SAT_XML_LOOSE 0x4000
	Use loose XML type checking with SAT_ValidateXml()

#define	SAT_XML_OVERRIDE_REQD 0x4000
	Override strict checks for required nodes when signing (advanced users)

Functions
long	SAT_Asciify (char szOut, long nOutChars, const char szXmlFile, long nOptions)
	Replace non-ASCII characters in an XML document with XML numeric character references (where permitted). More...

long	SAT_CheckKeyAndCert (const char szKeyFile, const char szPassword, const char *szCertFile, long nOptions)
	Verify that the public key in an X.509 certificate matches the private key. More...

long	SAT_Comments (char *szOut, long nOutChars, long nOptions)
	Get additional information about the core DLL module. More...

long	SAT_CompileTime (char *szOut, long nOutChars)
	Get date and time the core DLL module was last compiled. More...

long	SAT_ErrorLookup (char *szOut, long nOutChars, long nErrCode)
	Look up error code. More...

long	SAT_ExtractDigestFromSignature (char szOut, long nOutChars, const char szXmlFile, const char *szCertFile, long nOptions)
	Extract the hex-encoded message digest from the signature (Sello) in an XML file. More...

long	SAT_FixBOM (const char szOutputFile, const char szInputFile, long nOptions)
	Add a UTF-8 byte order mark (BOM) to a file if not already present. More...

long	SAT_GetCertAsString (char szOut, long nOutChars, const char szFileName, long nOptions)
	Get the certificate data as a base64 string. More...

long	SAT_GetCertExpiry (char szOut, long nOutChars, const char szFileName, long nOptions)
	Get the expiry date of the X.509 certificate in ISO time format 'yyyy-mm-ddThh:nn:ssZ' [deprecated]. More...

long	SAT_GetCertNumber (char szOut, long nOutChars, const char szFileName, long nOptions)
	Get the serial number of the X.509 certificate in special SAT format (20 ASCII digits) [deprecated]. More...

long	SAT_GetKeyAsString (char szOut, long nOutChars, const char szKeyFile, const char *szPassword, long nOptions)
	Get the private key as a base64 string to use in XML de Cancelación. More...

long	SAT_GetXmlAttribute (char szOut, long nOutChars, const char szXmlFile, const char szAttribute, const char szElement)
	Extract attribute data for a given element in an XML file. More...

long	SAT_GetXmlAttributeEx (char szOut, long nOutChars, const char szXmlFile, const char szAttribute, const char szElement, long nOptions)
	Extract attribute data for a given element in an XML file with option to encode output. More...

long	SAT_InsertCert (const char szOutputFile, const char szXmlFile, const char *szCertFile, long nOptions)
	Insert certificate information into an XML document and outputs to a new file. More...

long	SAT_InsertCertToString (char szOut, long nOutChars, const char szXmlFile, const char *szCertFile, long nOptions)
	Insert certificate information into an XML document and output to memory. More...

long	SAT_LastError (char *szOut, long nOutChars)
	Retrieve the last error message (if available). More...

long	SAT_LicenceType (void)
	Get the licence type. More...

long	SAT_MakeDigestFromXml (char szOut, long nOutChars, const char szXmlFile, long nOptions)
	Form the hex-encoded hash digest of piped string (cadena original) from an XML file. More...

long	SAT_MakePipeStringFromXml (char szOut, long nOutChars, const char szXmlFile, long nOptions)
	Create the "pipe" string (cadena original) from an XML file. More...

long	SAT_MakeSignatureFromXml (char szOut, long nOutChars, const char szXmlFile, const char szKeyFile, const char szPassword)
	Create the signature as a base64 string ready for insertion as `Sello` node. More...

long	SAT_MakeSignatureFromXmlEx (char szOut, long nOutChars, const char szXmlFile, const char szKeyFile, const char szPassword, long nOptions)
	Create the signature as a base64 string ready for insertion as `Sello` node. More...

long	SAT_ModuleName (char *szOut, long nOutChars, long nOptions)
	Get full path name of core DLL module. More...

long	SAT_NewKeyFile (const char szOutputFile, const char szNewPassword, const char szKeyFile, const char szPassword, const char *szReserved, long nOptions)
	Save keyfile with a new password. More...

long	SAT_Platform (char *szOut, long nOutChars)
	Get platform for which the core DLL was compiled ("Win32" or "Win64"). More...

long	SAT_QueryCert (char szOut, long nOutChars, const char szFileName, const char *szQuery, long nOptions)
	Query an X.509 certificate. More...

long	SAT_SignXml (const char szOutputFile, const char szXmlFile, const char szKeyFile, const char szPassword, const char *szCertFile, long nOptions)
	Sign an XML file. More...

long	SAT_SignXmlToString (char szOut, long nOutChars, const char szXmlFile, const char szKeyFile, const char szPassword, const char *szCertFile, long nOptions)
	Sign an XML document and outputs to memory. More...

long	SAT_Uuid (char *szOut, long nOutChars, long nOptions)
	Generate a Universally Unique IDentifier (UUID) compliant with RFC 4122. More...

long	SAT_ValidateXml (const char *szXmlFile, long nOptions)
	Validate an XML file against SAT specification. More...

long	SAT_VerifySignature (const char szXmlFile, const char szCertFile, long nOptions)
	Verify the signature (`Sello`) in an XML file. More...

long	SAT_Version (void)
	Get version number of the core DLL. More...

long	SAT_WritePfxFile (const char szOutputFile, const char szPfxPassword, const char szKeyFile, const char szKeyPassword, const char *szCertFile, long nOptions)
	Create a PFX (PKCS-12) file in PEM format suitable for a Cancelación. More...

long	SAT_XmlReceiptVersion (const char *szXmlFile, long nOptions)
	Find version number of `Comprobante` element or ID number for other document types. More...

Detailed Description

The C/C++ interface to the diFirmaSat2.dll library.

Note re output to szOut buffer: Functions that provide output in szOut require the buffer to be pre-dimensioned (i.e. allocated) to at least the specified length nOutChars PLUS one extra for the null-terminating byte. These functions always return the total length in bytes of the string they tried to create. To find the required length, pass a NULL szOut or zero nOutChars argument, then add one to the result for the required buffer size. For example:
char *xmlfile = "test.xml";

long nchars;

char *lpszOut;

// Find out how many bytes we need

nchars = SAT_MakePipeStringFromXml(NULL, 0, xmlfile, 0);

if (nchars <= 0) error();

// Pre-dimension, i.e allocate memory for string buffer

lpszOut = malloc(nchars+1); // NB +1

if (!lpszOut) error();

nchars = SAT_MakePipeStringFromXml(lpszOut, nchars, xmlfile, 0);

// ...

// do something with lpszOut...

// ...

free(lpszOut);

SAT_MakePipeStringFromXml
long SAT_MakePipeStringFromXml(char *szOut, long nOutChars, const char *szXmlFile, long nOptions)
Create the "pipe" string (cadena original) from an XML file.

Function Documentation

◆ SAT_Asciify()

long SAT_Asciify	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		long	nOptions
	)

Replace non-ASCII characters in an XML document with XML numeric character references (where permitted).

Parameters

[out]	szOut	Buffer to receive output as a null-terminated string
[in]	nOutChars	Maximum length of output buffer in bytes not including terminating null character
[in]	szXmlFile	Name of input XML file to be processed (or a string containing XML data)
[in]	nOptions	Default (0) is to encode characters that cannot be asciified in multibyte UTF-8. Use option SAT_ENCODE_LATIN1 to encode in ISO-8859-1 (Latin-1).

Returns: Number of bytes in or required for output buffer; or a negative error code .

Remarks: In almost all cases, the output contains only US-ASCII characters and can safely be used as input to other functions without concern for character encoding issues. For example, the character "ó" (U+00F3 LATIN SMALL LETTER O WITH ACUTE) is replaced by the XML character reference "ó".; In certain cases, some characters in an XML document cannot be replaced by a numeric character reference, for example where they are used in an element or attribute name, such as Año="2016". In these cases, they are left as UTF-8-encoded characters.

◆ SAT_CheckKeyAndCert()

long SAT_CheckKeyAndCert	(	const char *	szKeyFile,
		const char *	szPassword,
		const char *	szCertFile,
		long	nOptions
	)

Verify that the public key in an X.509 certificate matches the private key.

Parameters

[in]	szKeyFile	PKCS#8 encrypted key file
[in]	szPassword	Password for encrypted key file
[in]	szCertFile	X.509 certificate file or XML file with a `certificado` node
[in]	nOptions	None. Use 0.

Returns: Zero (0) if keys match or a negative error code .

Remarks: This will also verify that the password is correct for the key file.

◆ SAT_Comments()

long SAT_Comments	(	char *	szOut,
		long	nOutChars,
		long	nOptions
	)

Get additional information about the core DLL module.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	nOptions	Not used. Set as zero (0).

Returns: Number of characters in or required for output string; or a negative error code

◆ SAT_CompileTime()

long SAT_CompileTime	(	char *	szOut,
		long	nOutChars
	)

Get date and time the core DLL module was last compiled.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes

Returns: Number of characters in or required for output string; or a negative error code .

◆ SAT_ErrorLookup()

long SAT_ErrorLookup	(	char *	szOut,
		long	nOutChars,
		long	nErrCode
	)

Look up error code.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	nErrCode	Value of error code to lookup (positive or negative)

Returns: Number of characters in or required for output string; or a negative error code .

◆ SAT_ExtractDigestFromSignature()

long SAT_ExtractDigestFromSignature	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szCertFile,
		long	nOptions
	)

Extract the hex-encoded message digest from the signature (Sello) in an XML file.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes (expect 64 by default)
[in]	szXmlFile	Name of XML file to be processed
[in]	szCertFile	(optional) certificate file
[in]	nOptions	Use SAT_TFD to extract digest instead from `SelloSAT` of Timbre Fiscal Digital; otherwise use 0.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: If the XML file contains a Certificado node, then that certificate will be used for the public key; otherwise the user must specify a separate certificate file.

Note: A separate certificate file must be specified to use the SAT_TFD option.

◆ SAT_FixBOM()

long SAT_FixBOM	(	const char *	szOutputFile,
		const char *	szInputFile,
		long	nOptions
	)

Add a UTF-8 byte order mark (BOM) to a file if not already present.

Parameters

[in]	szOutputFile	Name of output file to be created.
[in]	szInputFile	Name of input file to be processed.
[in]	nOptions	None. Use 0.

Returns: Zero (0) if output file with BOM successfully created, or a negative error code .

Remarks: This works with any UTF-8 input file. It is an error if the input file contains invalid UTF-8 characters.

◆ SAT_GetCertAsString()

long SAT_GetCertAsString	(	char *	szOut,
		long	nOutChars,
		const char *	szFileName,
		long	nOptions
	)

Get the certificate data as a base64 string.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes.
[in]	szFileName	X.509 certificate file or XML file with a `certificado` node
[in]	nOptions	None. Use 0.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: Use to obtain the base64 value for the certificado node from a .CER file. It is an error if szOut is too small. If the input is an XML file, this function is equivalent to
SAT_GetXmlAttribute(szFileName, "certificado", "Comprobante");

SAT_GetXmlAttribute
long SAT_GetXmlAttribute(char *szOut, long nOutChars, const char *szXmlFile, const char *szAttribute, const char *szElement)
Extract attribute data for a given element in an XML file.

◆ SAT_GetCertExpiry()

long SAT_GetCertExpiry	(	char *	szOut,
		long	nOutChars,
		const char *	szFileName,
		long	nOptions
	)

Get the expiry date of the X.509 certificate in ISO time format 'yyyy-mm-ddThh:nn:ssZ' [deprecated].

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes (expect 20 characters)
[in]	szFileName	X.509 certificate file or XML file with a `certificado` node
[in]	nOptions	Use `SAT_DATE_NOTBEFORE` to get start date instead of expiry date; otherwise use 0.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: The time is GMT (UTC, Zulu time), not local.

Deprecated:: Use instead SAT_QueryCert() with query notAfter or notBefore.

◆ SAT_GetCertNumber()

long SAT_GetCertNumber	(	char *	szOut,
		long	nOutChars,
		const char *	szFileName,
		long	nOptions
	)

Get the serial number of the X.509 certificate in special SAT format (20 ASCII digits) [deprecated].

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes (expect 20 characters)
[in]	szFileName	X.509 certificate file or XML file with a `certificado` node
[in]	nOptions	None. Use 0.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: This only works with a certificate issed by SAT with their special serial number format. If input is an XML file, this extracts the number indirectly from the certificado node, not the noCertificado node.

See also: Use instead SAT_QueryCert() with query serialNumber.

◆ SAT_GetKeyAsString()

long SAT_GetKeyAsString	(	char *	szOut,
		long	nOutChars,
		const char *	szKeyFile,
		const char *	szPassword,
		long	nOptions
	)

Get the private key as a base64 string to use in XML de Cancelación.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szKeyFile	Encrypted key file
[in]	szPassword	Password for encrypted key file
[in]	nOptions	Use SAT_KEY_ENCRYPTED to output encrypted key in PEM format. The default (0) will output unencrypted key in plain base64 form.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: The default option creates a private key in base64 form suitable for a llaveCertificado node in a Cancelacion element.; The output using SAT_KEY_ENCRYPTED can be used as input to another function as the szKeyFile parameter.

Warning: The default option outputs your private key in unencrypted form. Using it is a huge security risk. Use with caution.

◆ SAT_GetXmlAttribute()

long SAT_GetXmlAttribute	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szAttribute,
		const char *	szElement
	)

Extract attribute data for a given element in an XML file.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szXmlFile	Name of XML file to be processed
[in]	szAttribute	Name of attribute to find
[in]	szElement	Name of element to find or xpath expression (see remarks)

Returns: Number of characters in or required for output string; or a negative error code . In particular it will return -NO_MATCH_ERROR if the element/attribute combination cannot be found.

Remarks: Attribute and element names are case-sensitive. For a simple element name, the default behaviour is to get the attribute from the first element found with the given name. Specify the element name in the form "element[N]" to extract the attribute for the N'th element found in the XML document, where N is a positive decimal integer (N=1,2,3,...). Setting szElement="" will output the value of the specified attribute from the root element of the XML document. Setting both szElement="" and szAttribute="" will output the name of the root element itself.

XPath Expression: Alternatively, specify an path expression in elementName using the "/" and "//" operators and optional predicate [N] where N is a positive integer. For example "/Comprobante/Emisor" or "//Concepto[2]//Retencion[3]". This is a simplified form of XPath that selects the first occurrence of the element matching the path expression (whereas XPath would select all matching elements). Path expressions must start with a "/" or "//" and must not end with a "/". No other XPath function or operator is accepted. Do not use namespace prefixes (e.g. "cfdi:") in the path expression.

Simplified Xpath syntax:

/e1 – selects the first <e1> document element (child element of the document node).
/e1/e2 – selects the first <e2> child element of the first <e1> document element.
/e1[2]/e2[3] – selects the third <e2> child element of the second <e1> document element.
/e1[1]/e2[1] – same as /e1/e2.
//e2 – the first <e2> element found anywhere (same as simple e2).
//e2[3] – the third <e2> element found anywhere (same as simple e2[3]).
/e1//e2 – the first <e2> element found anywhere inside the <e1> element.

To test for the existence of an element, set szAttribute="". This will return a positive value if it exists, or return -NO_MATCH_ERROR if not found.

◆ SAT_GetXmlAttributeEx()

long SAT_GetXmlAttributeEx	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szAttribute,
		const char *	szElement,
		long	nOptions
	)

Extract attribute data for a given element in an XML file with option to encode output.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szXmlFile	Name of XML file to be processed
[in]	szAttribute	Name of attribute to find
[in]	szElement	Name of element to find or xpath expression
[in]	nOptions	Use SAT_ENCODE_LATIN1 to encode output in Latin-1; otherwise use 0 for default UTF-8.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: See remarks in SAT_GetXmlAttribute() for more details.

◆ SAT_InsertCert()

long SAT_InsertCert	(	const char *	szOutputFile,
		const char *	szXmlFile,
		const char *	szCertFile,
		long	nOptions
	)

Insert certificate information into an XML document and outputs to a new file.

Parameters

[in]	szOutputFile	Name of new output file to be created.
[in]	szXmlFile	Name of input XML file to be processed (or a string containing XML data)
[in]	szCertFile	X.509 certificate file
[in]	nOptions	Add any of the following options (use the `\|` operator). Default (0) is to add BOM, empty elements in form `<foo></foo>`. SAT_XML_EMPTYELEMTAG to write all empty elements in the empty-element tag form `<foo />`. The default is the start-end tag pair form `<foo></foo>`. SAT_FILE_NO_BOM do not add byte-order mark (BOM) to output file. Default = add BOM.

Returns: Zero (0) on success or a negative error code .

Remarks: This will create an output XML document copied from the input with the noCertificado and Certificado nodes overwritten by new values. Any existing file with same name as the szOutputFile argument will be overwritten without warning. The input and output files can be the same.

◆ SAT_InsertCertToString()

long SAT_InsertCertToString	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szCertFile,
		long	nOptions
	)

Insert certificate information into an XML document and output to memory.

Parameters

[out]	szOut	Buffer to receive output as a null-terminated string
[in]	nOutChars	Maximum length of output buffer in bytes not including terminating null character
[in]	szXmlFile	Name of input XML file to be processed (or a string containing XML data)
[in]	szCertFile	X.509 certificate file (or a string containing certificate data in PEM or plain base64 form)
[in]	nOptions	Use SAT_XML_EMPTYELEMTAG to write all empty elements in the empty-element tag form `<foo />`. The default (0) is the start-end tag pair form `<foo></foo>`.

Returns: Number of bytes in or required for output buffer; or a negative error code .

Remarks: The output string is always encoded in UTF-8

◆ SAT_LastError()

long SAT_LastError	(	char *	szOut,
		long	nOutChars
	)

Retrieve the last error message (if available).

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: Call this function to find out more information about the last error. Not all functions set this.

◆ SAT_LicenceType()

long SAT_LicenceType ( void )

Get the licence type.

Returns: The ASCII value of the licence type, either 'D' (ASCII 68, 0x44) for the Developer Edition or 'T' (ASCII 84, 0x54) for the Trial Edition.

◆ SAT_MakeDigestFromXml()

long SAT_MakeDigestFromXml	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		long	nOptions
	)

Form the hex-encoded hash digest of piped string (cadena original) from an XML file.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes (expect 64 by default)
[in]	szXmlFile	Name of XML file to be processed
[in]	nOptions	Use SAT_TFD to make digest of the cadena original del Timbre Fiscal Digital instead; otherwise use 0. Add SAT_XML_OVERRIDE_REQD to override strict checks for required nodes (advanced users).

Returns: Number of characters in or required for output string; or a negative error code .

◆ SAT_MakePipeStringFromXml()

long SAT_MakePipeStringFromXml	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		long	nOptions
	)

Create the "pipe" string (cadena original) from an XML file.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szXmlFile	Name of XML file to be processed
[in]	nOptions	Use SAT_ENCODE_LATIN1 to encode in Latin1. The default (0) is SAT_ENCODE_UTF8 for UTF-8. Add SAT_TFD to create the cadena original del Timbre Fiscal Digital instead. Add SAT_XML_OVERRIDE_REQD to override strict checks for required nodes (advanced users).

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: Final string length may be shorter after extra spaces are removed.

See also: Note re output to szOut buffer.

◆ SAT_MakeSignatureFromXml()

long SAT_MakeSignatureFromXml	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szKeyFile,
		const char *	szPassword
	)

Create the signature as a base64 string ready for insertion as Sello node.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szXmlFile	Name of XML file to be processed
[in]	szKeyFile	Encrypted key file
[in]	szPassword	Password for encrypted key file

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: This will use the default hash algorithm. For advanced options use SAT_MakeSignatureFromXmlEx().

◆ SAT_MakeSignatureFromXmlEx()

long SAT_MakeSignatureFromXmlEx	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szKeyFile,
		const char *	szPassword,
		long	nOptions
	)

Create the signature as a base64 string ready for insertion as Sello node.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szXmlFile	Name of XML file to be processed
[in]	szKeyFile	Encrypted key file
[in]	szPassword	Password for encrypted key file
[in]	nOptions	Use 0 for default or SAT_TFD to make `SelloSAT` for Timbre Fiscal Digital instead. Add SAT_XML_OVERRIDE_REQD to override strict checks for required nodes (advanced users).

Returns: Number of characters in or required for output string; or a negative error code .

◆ SAT_ModuleName()

long SAT_ModuleName	(	char *	szOut,
		long	nOutChars,
		long	nOptions
	)

Get full path name of core DLL module.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes

Returns: Number of characters in or required for output string; or a negative error code

◆ SAT_NewKeyFile()

long SAT_NewKeyFile	(	const char *	szOutputFile,
		const char *	szNewPassword,
		const char *	szKeyFile,
		const char *	szPassword,
		const char *	szReserved,
		long	nOptions
	)

Save keyfile with a new password.

Parameters

[in]	szOutputFile	Name of new output file to be created.
[in]	szNewPassword	Password for new key file.
[in]	szKeyFile	Name of input key file (or a string containing the key in PEM form).
[in]	szPassword	Password for existing key file.
[in]	szReserved	Reserved for future use. Specify `""` or `NULL`.
[in]	nOptions	Use SAT_FORMAT_PEM to output key file in PEM textual format. The default (0) is binary DER encoded.

Returns: Zero (0) on success or a negative error code .

◆ SAT_Platform()

long SAT_Platform	(	char *	szOut,
		long	nOutChars
	)

Get platform for which the core DLL was compiled ("Win32" or "Win64").

Parameters

[out]	szOut	Buffer to receive output string.
[in]	nOutChars	Maximum number of character bytes to be received (excluding the null terminating byte).

Returns: Number of characters in or required for output string.

◆ SAT_QueryCert()

long SAT_QueryCert	(	char *	szOut,
		long	nOutChars,
		const char *	szFileName,
		const char *	szQuery,
		long	nOptions
	)

Query an X.509 certificate.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	szFileName	X.509 certificate file or XML file with a `certificado` node
[in]	szQuery	Query string. See Remarks.
[in]	nOptions	Use `#SAT_ENCODE_LATIN1` to encode output in Latin-1; otherwise use 0 for default UTF-8.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks

Valid queries are:

rfc to get the subject's RFC (expect 12 or 13 characters)
orgName or organizationName to get the issuer's organization name (expect "Servicio de Administración Tributaria" in default UTF-8 encoding)
companyName to get the subject's organizationName
notAfter to get the expiry date [a replacement for SAT_GetCertExpiry()]
notBefore to get the start date [a replacement for SAT_GetCertExpiry() with SAT_DATE_NOTBEFORE option]
serialNumber to get the 20-digit SAT-specific serial number [a replacement for SAT_GetCertNumber()]
sigAlg to get the algorithm used to sign the certificate (e.g. "sha256WithRSAEncryption")
keySize to get the size in bits of the certificate's public key (e.g. "2048")

Note: Times are GMT (UTC, Zulu time), not local, and are in the ISO time format yyyy-mm-ddThh:nn:ssZ.

◆ SAT_SignXml()

long SAT_SignXml	(	const char *	szOutputFile,
		const char *	szXmlFile,
		const char *	szKeyFile,
		const char *	szPassword,
		const char *	szCertFile,
		long	nOptions
	)

Sign an XML file.

Parameters

[in]	szOutputFile	Name of new output file to be created with `Sello` and (optionally) `Certificado` and `NoCertificado` nodes completed.
[in]	szXmlFile	Name of input XML file to be processed.
[in]	szKeyFile	Encrypted private key file
[in]	szPassword	Password for encrypted key file
[in]	szCertFile	(optional) X.509 certificate file
[in]	nOptions	Add any of the following options (use the `\|` operator). Default (0) is to add BOM, empty elements in form `<foo></foo>`. SAT_XML_EMPTYELEMTAG to write all empty elements in the empty-element tag form `<foo />`. The default is the start-end tag pair form `<foo></foo>`. SAT_FILE_NO_BOM do not add byte-order mark (BOM) to output file. Default = add BOM. SAT_FILE_BIGFILE to speed up the processing of large files. SAT_XML_OVERRIDE_REQD to override strict checks for required nodes (advanced users).

Returns: Zero (0) on success or a negative error code .

Remarks: This will create an output XML document copied from the input with the Comprobante/@Sello node overwritten by a new signature value. Any existing file with same name as the szOutputFile argument will be overwritten without warning. The input and output files can be the same. If a certificate file szCertFile is specified then the Certificado and NoCertificado nodes will be overwritten in the output file with the values in the certificate file.; If a certficate file is not specified then the Certificado value in the XML will be used.

Note: For CFD v4.0/3.3 the NoCertificado attribute in the input must be set to the correct certificate serial number before signing or computing the digest. It is an error (CERT_NUM_ERROR) if this value does not match the serial number of the certificate.
<Comprobante Version="4.0" ...

NoCertificado="40001000000300000337"

Certificado=""

Sello=""

...>; In a Retenciones document you must set the CertNum attribute before signing. In a ControlesVolumetricos document you must set both the noCertificado and certificado attributes before signing.; It is an error (NO_MATCH_ERROR) if the private key and certificate do not match.; Alternative mode: Set nOptions to SAT_TFD to create and insert a tfd:TimbreFiscalDigital element signed by the "PAC" with the given key/certificate pair. In this case the input file must be a properly signed v4.0/3.3 CFDI document without a TFD element, and the certificate must be provided. This option may be useful for testing purposes.

See also: SAT_InsertCert() and SAT_InsertCertToString().

◆ SAT_SignXmlToString()

long SAT_SignXmlToString	(	char *	szOut,
		long	nOutChars,
		const char *	szXmlFile,
		const char *	szKeyFile,
		const char *	szPassword,
		const char *	szCertFile,
		long	nOptions
	)

Sign an XML document and outputs to memory.

Parameters

[out]	szOut	Buffer to receive output as a null-terminated string
[in]	nOutChars	Maximum length of output buffer in bytes not including terminating null character
[in]	szXmlFile	Name of input XML file to be processed (or a string containing XML data)
[in]	szKeyFile	Encrypted private key file (or a string containing key data in PEM form)
[in]	szPassword	Password for encrypted key file
[in]	szCertFile	(optional) X.509 certificate file (or a string containing certificate data in PEM or plain base64 form)
[in]	nOptions	Use SAT_XML_EMPTYELEMTAG to write all empty elements in the empty-element tag form `<foo />`. The default (0) is the start-end tag pair form `<foo></foo>`.

Returns: Number of bytes in or required for output buffer; or a negative error code .

Remarks: The output string is always encoded in UTF-8

Note: It is an error if the private key and certificate do not match.

◆ SAT_Uuid()

long SAT_Uuid	(	char *	szOut,
		long	nOutChars,
		long	nOptions
	)

Generate a Universally Unique IDentifier (UUID) compliant with RFC 4122.

Parameters

[out]	szOut	Buffer to receive output as a null-terminated string
[in]	nOutChars	Maximum length of output buffer in bytes not including terminating null character
[in]	nOptions	None. Use 0.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: The output string is always exactly 36 characters long in the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" where 'x' is a lowercase hexadecimal digit [0-9a-f].

◆ SAT_ValidateXml()

long SAT_ValidateXml	(	const char *	szXmlFile,
		long	nOptions
	)

Validate an XML file against SAT specification.

Parameters

[in]	szXmlFile	Name of XML file to be processed
[in]	nOptions	Use SAT_XML_LOOSE to loosen strict checks on XML restrictions. Default (0) is `SAT_XML_STRICT`.

Returns: Zero (0) on success or a negative error code .

Remarks: This only does a check that the XML elements are well-formed and in the correct order. It does not check the signature and may not catch all XML facet restriction errors that a strict XML parser may find. This function is meant as a quick check for structural problems in the XML file, not as a replacement for a full XSD checker.

◆ SAT_VerifySignature()

long SAT_VerifySignature	(	const char *	szXmlFile,
		const char *	szCertFile,
		long	nOptions
	)

Verify the signature (Sello) in an XML file.

Parameters

[in]	szXmlFile	Name of XML file to be processed.
[in]	szCertFile	(optional) certificate file
[in]	nOptions	Use SAT_TFD to verify `SelloSAT` in Timbre Fiscal Digital instead.

Returns: Zero (0) on success or a negative error code .

Remarks: If no certificate file is specified, then the Certificado node in the XML file will be used. If a separate certificate file is specified, it will be used instead.

Note: A separate certificate file is always required for the SAT_TFD option.

◆ SAT_Version()

long SAT_Version ( void )

Get version number of the core DLL.

Returns: Version number as an integer in the form Major*10000+Minor*100+Revision. For example, version 9.2.15 would return 90215.

◆ SAT_WritePfxFile()

long SAT_WritePfxFile	(	const char *	szOutputFile,
		const char *	szPfxPassword,
		const char *	szKeyFile,
		const char *	szKeyPassword,
		const char *	szCertFile,
		long	nOptions
	)

Create a PFX (PKCS-12) file in PEM format suitable for a Cancelación.

Parameters

[in]	szOutputFile	Name of output PFX file to be created.
[in]	szPfxPassword	Password to open new PFX file
[in]	szKeyFile	Name of encrypted key file
[in]	szKeyPassword	Password for encrypted key file
[in]	szCertFile	Name of X.509 certificate file
[in]	nOptions	Use: 0 for the default output (base64) SAT_FORMAT_PEM for a PKCS12 file in PEM textual form SAT_FORMAT_BINARY for a PKCS12/PFX file in binary DER form

Returns: Zero (0) if output file is successfully created, or a negative error code .

Warning: Giving the PFX password to a third party is a security risk. Use with caution.

◆ SAT_XmlReceiptVersion()

long SAT_XmlReceiptVersion	(	const char *	szXmlFile,
		long	nOptions
	)

Find version number of Comprobante element or ID number for other document types.

Parameters

[in]	szXmlFile	Name of XML file to be processed
[in]	nOptions	Use SAT_GEN_DIGALG to retrieve default digest algorithm for the document.

Returns: Version number or ID number for XML document,
or a negative error code .

Remarks

Possible return values:

40 = Comprobante document with Version="4.0"
33 = Comprobante document with Version="3.3" (legacy)
32 = Comprobante document with version="3.2" (legacy)
1010/1020 = Retenciones document with Version="1.0"/"2.0"
2011/2013 = CatalogoCuentas document with Version="1.1"/"1.3"
2111/2113 = BalanzaComprobacion document with Version="1.1"/"1.3"
2211/2213 = PolizasPeriodo document with Version="1.1"/"1.3"
2312/2313 = AuxiliarFolios document with Version="1.2"/"1.3"
2411/2413 = AuxiliarCtas document with Version="1.1"/"1.3"
2511 = SelloDigitalContElec document with Version="1.1"
4011/4012 = ControlesVolumetricos document with Version="1.1"/"1.2"

Return values with nOptions=SAT_GEN_DIGALG:

1 = SHA-1 is default digest algorithm for document
256 = SHA-256 is default digest algorithm for document

For example:

printf("%ld\n", SAT_XmlReceiptVersion("cfdv40-ejemplo.xml", 0)); // 40

SAT_XmlReceiptVersion

long SAT_XmlReceiptVersion(const char *szXmlFile, long nOptions)

Find version number of Comprobante element or ID number for other document types.

Macros

Functions

Detailed Description

Function Documentation

◆ SAT_Asciify()

◆ SAT_CheckKeyAndCert()

◆ SAT_Comments()

◆ SAT_CompileTime()

◆ SAT_ErrorLookup()

◆ SAT_ExtractDigestFromSignature()

◆ SAT_FixBOM()

◆ SAT_GetCertAsString()

◆ SAT_GetCertExpiry()

◆ SAT_GetCertNumber()

◆ SAT_GetKeyAsString()

◆ SAT_GetXmlAttribute()

◆ SAT_GetXmlAttributeEx()

◆ SAT_InsertCert()

◆ SAT_InsertCertToString()

◆ SAT_LastError()

◆ SAT_LicenceType()

◆ SAT_MakeDigestFromXml()

◆ SAT_MakePipeStringFromXml()

◆ SAT_MakeSignatureFromXml()

◆ SAT_MakeSignatureFromXmlEx()

◆ SAT_ModuleName()

◆ SAT_NewKeyFile()

◆ SAT_Platform()

◆ SAT_QueryCert()

◆ SAT_SignXml()

◆ SAT_SignXmlToString()

◆ SAT_Uuid()

◆ SAT_ValidateXml()

◆ SAT_VerifySignature()

◆ SAT_Version()

◆ SAT_WritePfxFile()

◆ SAT_XmlReceiptVersion()