SAT-related methods. More...

Public Types
enum class	KeyFormat { Binary = 0x0 , PEM = 0x10000 }
	Format for saved key files. More...

enum class	KeyOption { UnencryptedBase64 = 0x0 , EncryptedPEM = 0x10000 }
	Options for key output. More...

enum	SignOpts : unsigned int { Default = 0x0 , NoBOM = 0x2000 , UseEmptyElements = 0x20000 , BigFile = 0x8000000 , OverrideReqd = 0x4000 }
	Options for signing XML. More...

enum class	XmlOption { Strict = 0x0 , Loose = 0x4000 }
	Options for XML validation. More...

Static Public Member Functions
static std::string	Asciify (const std::string &xmlFile)
	Replace non-ASCII characters in an XML document with XML numeric character references (where permitted). More...

static int	CheckKeyAndCert (const std::string &keyFile, const std::string &password, const std::string &certFile)
	Verify that the public key in an X.509 certificate matches the private key. More...

static std::string	ExtractDigestFromSignature (const std::string &xmlFile, const std::string &certFile="")
	Extract message digest from the signature (sello) in an XML file . More...

static int	FixBOM (const std::string &outFile, const std::string &inputFile)
	Add UTF-8 byte order mark (BOM) to a file if not already present. More...

static std::string	GetCertAsString (const std::string &certFile)
	Get certificate data as a base64 string. More...

static std::string	GetKeyAsString (const std::string &keyFile, const std::string &password="", const KeyOption keyOpt=KeyOption::UnencryptedBase64)
	Get private key data as a base64 string. More...

static std::string	GetXmlAttribute (const std::string &xmlFile, const std::string &attributeName, const std::string &elementName)
	Extract attribute data from an XML file. More...

static int	InsertCert (const std::string &newFile, const std::string &xmlFile, const std::string &certFile)
	Insert certificate information into an XML document and output to a new file. More...

static std::string	InsertCertToString (const std::string &xmlFile, const std::string &certFile)
	Insert certificate information into an XML document and output to memory. More...

static std::string	MakeDigestFromXml (const std::string &xmlFile)
	Compute message digest of piped string (cadena) from an XML file. More...

static std::string	MakePipeStringFromXml (const std::string &xmlFile)
	Create the piped string (cadena) from an XML file. More...

static std::string	MakeSignatureFromXml (const std::string &xmlFile, const std::string &keyFile, const std::string &password="")
	Create signature as a base64 string from data in an XML file ready to be inserted as a `sello` node. More...

static int	NewKeyFile (const std::string &newFile, const std::string &newPassword, const std::string &keyFile, const std::string &keyPassword, const KeyFormat format=KeyFormat::Binary)
	Save keyfile with a new password. More...

static std::string	QueryCert (const std::string &certFile, const std::string &query)
	Query an X.509 certificate. More...

static void	SetXmlNoMatch (const std::string &value="")
	Modify the string returned when Sat::GetXmlAttribute fails to find a match. More...

static int	SignXml (const std::string &outFile, const std::string &xmlFile, const std::string &keyFile, const std::string &password="", const std::string &certFile="", const SignOpts signOpts=SignOpts::Default)
	Sign an XML file. More...

static std::string	SignXmlToString (const std::string &xmlFile, const std::string &keyFile, const std::string &password="", const std::string &certFile="", const SignOpts signOpts=SignOpts::Default)
	Sign an XML document and output to memory. More...

static std::string	Uuid ()
	Generate a Universally Unique IDentifier (UUID) compliant with RFC 4122. More...

static int	ValidateXml (const std::string &xmlFile, const XmlOption xmlOpt=XmlOption::Strict)
	Validate an XML file against SAT specifications. More...

static int	VerifySignature (const std::string &xmlFile, const std::string &certFile="")
	Verify the signature (sello) in an XML file. More...

static int	WritePfxFile (const std::string &pfxFile, const std::string &pfxPassword, const std::string &keyFile, const std::string &keyPassword, const std::string &certFile)
	Create a PFX (PKCS-12) file in PEM format. More...

static std::string	XmlNoMatch ()
	Error message returned when Sat::GetXmlAttribute fails to find a match. More...

static int	XmlReceiptVersion (const std::string &xmlFile)
	Find version number of Comprobante element or ID number for other document types. More...

Detailed Description

SAT-related methods.

Member Enumeration Documentation

◆ KeyFormat

enum firmasat::Sat::KeyFormat

strong

Format for saved key files.

Enumerator
Binary	Binary DER-encoded (default)
PEM	Output key file in PEM textual form.

◆ KeyOption

enum firmasat::Sat::KeyOption

strong

Options for key output.

Enumerator
UnencryptedBase64	Key as unencrypted base64 string suitable for Cancelacion element (default)
EncryptedPEM	Key as encrypted private key in PEM format suitable for input as a keyFile parameter.

◆ SignOpts

enum firmasat::Sat::SignOpts : unsigned int

Options for signing XML.

Enumerator
Default	Default options.
NoBOM	Do not add byte-order mark (BOM) to file.
UseEmptyElements	Output empty elements in empty-element tag form `<foo />` (default is start-end tag pair form `<foo></foo>`)
BigFile	Speed up the processing of large files.
OverrideReqd	Override strict checks for required nodes (advanced users)

◆ XmlOption

enum firmasat::Sat::XmlOption

strong

Options for XML validation.

Enumerator
Strict	Enforce stricter XML restrictions (default).
Loose	Use looser restrictions on data types .

Member Function Documentation

◆ Asciify()

static std::string firmasat::Sat::Asciify ( const std::string & xmlFile )

static

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

Parameters

xmlFile Name of XML file (or a string containing XML data).

Returns: XML document as a string with non-ASCII characters replaced by XML numeric character references.

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.

◆ CheckKeyAndCert()

static int firmasat::Sat::CheckKeyAndCert	(	const std::string &	keyFile,
		const std::string &	password,
		const std::string &	certFile
	)

static

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

Parameters

keyFile	Name of private key file or string containing PEM representation.
password	Password for encrypted private key.
certFile	X.509 certificate file or XML document with embedded `certificado` node.

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

◆ ExtractDigestFromSignature()

static std::string firmasat::Sat::ExtractDigestFromSignature	(	const std::string &	xmlFile,
		const std::string &	certFile = `""`
	)

static

Extract message digest from the signature (sello) in an XML file .

Parameters

xmlFile	Name of XML file to be processed (or a string containing XML data).
certFile	Optional X.509 certificate file (will overrule public key in XML `certificado` node).

Returns: Message digest in hex format or empty string on error.

◆ FixBOM()

static int firmasat::Sat::FixBOM	(	const std::string &	outFile,
		const std::string &	inputFile
	)

static

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

Parameters

outFile	Name of new file to be created.
inputFile	Name of existing file.

Returns: 0 if successful or nonzero error code if failed.

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

◆ GetCertAsString()

static std::string firmasat::Sat::GetCertAsString ( const std::string & certFile )

static

Get certificate data as a base64 string.

Parameters

certFile X.509 certificate file or XML file with certificado node.

Returns: Certificate data as a string of base64 characters.

◆ GetKeyAsString()

static std::string firmasat::Sat::GetKeyAsString	(	const std::string &	keyFile,
		const std::string &	password = `""`,
		const KeyOption	keyOpt = `KeyOption::UnencryptedBase64`
	)

static

Get private key data as a base64 string.

Parameters

keyFile	Private key file or key represented as a PEM string.
password	Password for encrypted key.
keyOpt	Options for key output.

Returns: Private key in string form.

◆ GetXmlAttribute()

static std::string firmasat::Sat::GetXmlAttribute	(	const std::string &	xmlFile,
		const std::string &	attributeName,
		const std::string &	elementName
	)

static

Extract attribute data from an XML file.

Parameters

xmlFile	Name of XML file to be processed (or a string containing XML data).
attributeName	Name of attribute.
elementName	Name of element or xpath expression (see remarks)

Returns: Attribute value, if found; or "!NO MATCH!" if not found (see Sat::XmlNoMatch).

Exceptions

std::runtime_error if missing file or invalid XML.

◆ InsertCert()

static int firmasat::Sat::InsertCert	(	const std::string &	newFile,
		const std::string &	xmlFile,
		const std::string &	certFile
	)

static

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

Parameters

newFile	Name of new output file to be created.
xmlFile	Name of input XML file to be processed (or a string containing XML data).
certFile	X.509 certificate file.

Returns: 0 if successful or nonzero error code if failed.

◆ InsertCertToString()

static std::string firmasat::Sat::InsertCertToString	(	const std::string &	xmlFile,
		const std::string &	certFile
	)

static

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

Parameters

xmlFile	Name of input XML file to be processed (or a string containing XML data).
certFile	X.509 certificate file.

Returns: XML data as a UTF-8-encoded string.

◆ MakeDigestFromXml()

static std::string firmasat::Sat::MakeDigestFromXml ( const std::string & xmlFile )

static

Compute message digest of piped string (cadena) from an XML file.

Parameters

xmlFile Name of XML file to be processed (or a string containing XML data).

Returns: Message digest value in hex format or empty string on error.

◆ MakePipeStringFromXml()

static std::string firmasat::Sat::MakePipeStringFromXml ( const std::string & xmlFile )

static

Create the piped string (cadena) from an XML file.

Parameters

xmlFile Name of XML file to be processed (or a string containing XML data).

Returns: Piped string (UTF-8 encoded).

◆ MakeSignatureFromXml()

static std::string firmasat::Sat::MakeSignatureFromXml	(	const std::string &	xmlFile,
		const std::string &	keyFile,
		const std::string &	password = `""`
	)

static

Create signature as a base64 string from data in an XML file ready to be inserted as a sello node.

Parameters

xmlFile	Name of base XML file to be signed (or a string containing XML data).
keyFile	Name of private key file.
password	Password for private key file.

Returns: Signature in base64 format or empty string on error.

◆ NewKeyFile()

static int firmasat::Sat::NewKeyFile	(	const std::string &	newFile,
		const std::string &	newPassword,
		const std::string &	keyFile,
		const std::string &	keyPassword,
		const KeyFormat	format = `KeyFormat::Binary`
	)

static

Save keyfile with a new password.

Parameters

newFile	Name of new output file to be created.
newPassword	Password for new key file.
keyFile	Name of input key file (or a string containing the key in PEM form).
keyPassword	Password for existing key file.
format	Format to save file (default = DER binary)

Returns: 0 if successful or nonzero error code if failed.

◆ QueryCert()

static std::string firmasat::Sat::QueryCert	(	const std::string &	certFile,
		const std::string &	query
	)

static

Query an X.509 certificate.

Parameters

certFile	X.509 certificate file or XML file with `certificado` node.
query	Query.

Returns: Result of query or an empty string on error.

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 organization name of subject. This should be your company name.
notAfter to get the expiry date
notBefore to get the start date
serialNumber to get the 20-digit SAT-specific serial number
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.

◆ SetXmlNoMatch()

static void firmasat::Sat::SetXmlNoMatch ( const std::string & value = "" )

static

Modify the string returned when Sat::GetXmlAttribute fails to find a match.

Parameters

value New string value. Pass "" to reset to default.

See also: Sat::XmlNoMatch.

◆ SignXml()

static int firmasat::Sat::SignXml	(	const std::string &	outFile,
		const std::string &	xmlFile,
		const std::string &	keyFile,
		const std::string &	password = `""`,
		const std::string &	certFile = `""`,
		const SignOpts	signOpts = `SignOpts::Default`
	)

static

Sign an XML file.

Parameters

outFile	Name of new signed file to be created
xmlFile	Name of base XML file to be signed (or a string containing XML data).
keyFile	Name of private key file.
password	Password for private key file.
certFile	(optional) name of X.509 certificate file to be included in output XML.
signOpts	Options for output format.

Returns: 0 if successful or nonzero error code if failed.

◆ SignXmlToString()

static std::string firmasat::Sat::SignXmlToString	(	const std::string &	xmlFile,
		const std::string &	keyFile,
		const std::string &	password = `""`,
		const std::string &	certFile = `""`,
		const SignOpts	signOpts = `SignOpts::Default`
	)

static

Sign an XML document and output to memory.

Parameters

xmlFile	Name of base XML file to be signed (or a string containing XML data).
keyFile	Name of private key file (or string containing key data in PEM format).
password	Password for private key file.
certFile	(optional) name of X.509 certificate file to be included in output XML (or string containing certificate data in base64 or PEM format).
signOpts	Options for output format.

Returns: Signed XML data in a UTF-8 encoded string.

◆ Uuid()

static std::string firmasat::Sat::Uuid ( )

static

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

Returns: UUID string of exactly 36 characters in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where 'x' is a lowercase hexadecimal digit [0-9a-f].

Remarks: The output value is randomly generated and will be different each time.; For example:
cout << firmasat::Sat::Uuid() << endl;

// 343c6b13-4f69-4d2a-97e6-64cb770c7677

firmasat::Sat::Uuid
static std::string Uuid()
Generate a Universally Unique IDentifier (UUID) compliant with RFC 4122.

◆ ValidateXml()

static int firmasat::Sat::ValidateXml	(	const std::string &	xmlFile,
		const XmlOption	xmlOpt = `XmlOption::Strict`
	)

static

Validate an XML file against SAT specifications.

Parameters

xmlFile	Name of XML file to be processed (or a string containing XML data).
xmlOpt	Option for strict or loose XML restrictions.

Returns: Zero if OK or a nonzero error code if failed.

◆ VerifySignature()

static int firmasat::Sat::VerifySignature	(	const std::string &	xmlFile,
		const std::string &	certFile = `""`
	)

static

Verify the signature (sello) in an XML file.

Parameters

xmlFile	Name of XML file to be processed (or a string containing XML data).
certFile	Optional X.509 certificate file.

Returns: Zero if signature is verified or a nonzero error code if failed.

Remarks: By default, the certificado node in the XML will be used to verify the signature. However, if a certFile is provided, the public key will be obtained from the specified X.509 certificate and any existing certificado node in the XML will be ignored.

◆ WritePfxFile()

static int firmasat::Sat::WritePfxFile	(	const std::string &	pfxFile,
		const std::string &	pfxPassword,
		const std::string &	keyFile,
		const std::string &	keyPassword,
		const std::string &	certFile
	)

static

Create a PFX (PKCS-12) file in PEM format.

Parameters

pfxFile	Name of output PFX file to be created.
pfxPassword	Password to open new PFX file.
keyFile	Name of encrypted private key file.
keyPassword	Password for encrypted private key file.
certFile	Name of X.509 certificate file that matches private key.

Returns: 0 if successful or nonzero error code if failed.

◆ XmlNoMatch()

static std::string firmasat::Sat::XmlNoMatch ( )

static

Error message returned when Sat::GetXmlAttribute fails to find a match.

Returns: Error message (default = "!NO MATCH!")

Remarks: Use directly to check the result of Sat::GetXmlAttribute, for example
string s = firmasat::Sat::GetXmlAttribute(fname, attributeName, elementName);

if (firmasat::Sat::XmlNoMatch() == s) {

// Catch no match here...

}

firmasat::Sat::GetXmlAttribute
static std::string GetXmlAttribute(const std::string &xmlFile, const std::string &attributeName, const std::string &elementName)
Extract attribute data from an XML file.

firmasat::Sat::XmlNoMatch
static std::string XmlNoMatch()
Error message returned when Sat::GetXmlAttribute fails to find a match.; Use Sat::SetXmlNoMatch to change the error message string.

◆ XmlReceiptVersion()

static int firmasat::Sat::XmlReceiptVersion ( const std::string & xmlFile )

static

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

Parameters

xmlFile Name of XML file to be processed (or a string containing XML data).

Returns: Version number or ID number, 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"

For example:

cout << firmasat::Sat::XmlReceiptVersion("cfdv40-ejemplo.xml") << endl; // 40

cout << firmasat::Sat::XmlReceiptVersion("ConVolE12345-base.xml") << endl; // 4011

firmasat::Sat::XmlReceiptVersion

static int XmlReceiptVersion(const std::string &xmlFile)

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

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ KeyFormat

◆ KeyOption

◆ SignOpts

◆ XmlOption

Member Function Documentation

◆ Asciify()

◆ CheckKeyAndCert()

◆ ExtractDigestFromSignature()

◆ FixBOM()

◆ GetCertAsString()

◆ GetKeyAsString()

◆ GetXmlAttribute()

◆ InsertCert()

◆ InsertCertToString()

◆ MakeDigestFromXml()

◆ MakePipeStringFromXml()

◆ MakeSignatureFromXml()

◆ NewKeyFile()

◆ QueryCert()

◆ SetXmlNoMatch()

◆ SignXml()

◆ SignXmlToString()

◆ Uuid()

◆ ValidateXml()

◆ VerifySignature()

◆ WritePfxFile()

◆ XmlNoMatch()

◆ XmlReceiptVersion()