FirmaSAT .NET Class Library 10.50.0

A .NET interface for FirmaSAT

Classes

• General Class - General utilities.
• Sat Class - SAT-related methods.
• Tfd Class - Methods for Timbre Fiscal Digital (TFD).

Methods

General Class Methods

• General.Comments Method
  • Get additional information about the core DLL module.
• General.CompileTime Method
  • Get date and time the core DLL module was last compiled.
• General.ErrorLookup Method
  • Look up error code.
• General.FormatErrorMessage Method
  • Return an error message string for the last error.
• General.LastError Method
  • Retrieve the last error message.
• General.LicenceType Method
  • Get licence type.
• General.ModuleName Method
  • Get full path name of core diFirmaSat DLL module.
• General.Platform Method
  • Get the platform for which the core native DLL was compiled.
• General.Version Method
  • Return version number of core diFirmaSat DLL.

Sat Class Methods

• Sat.Asciify Method (Byte[])
  • Replace any non-ASCII characters in an XML document (as a byte array) with XML character references (where permitted).
• Sat.Asciify Method (String)
  • Replace non-ASCII characters in an XML document with XML numeric character references (where permitted).
• Sat.CheckKeyAndCert Method
  • Verify that the public key in an X.509 certificate matches the private key.
• Sat.DefaultDigestAlg Method
  • Return default digest (hash) algorithm for the XML document type.
• Sat.ExtractDigestFromSignature Method
  • Extract message digest from the signature (sello) in an XML file.
• Sat.FixBom Method
  • Add UTF-8 byte order mark (BOM) to a file if not already present.
• Sat.GetCertAsString Method
  • Get certificate data as a base64 string.
• Sat.GetCertExpiry Method
  • Get expiry date of the X.509 certificate in ISO time format.
• Sat.GetCertNumber Method
  • Get serial number of the X.509 certificate in "special" SAT format.
• Sat.GetCertStart Method
  • Get start date of the X.509 certificate in ISO time format.
• Sat.GetKeyAsString Method
  • Get private key data as a base64 string suitable for a llaveCertificado element in a Cancelacion XML document
• Sat.GetXmlAttribute Method
  • Extract attribute data from an XML file.
• Sat.InsertCert Method
  • Insert certificate information into an XML document and output to a new file.
• Sat.InsertCertToBytes Method (Byte[], String)
  • Insert certificate information into an XML document (as a byte array) and output to memory.
• Sat.InsertCertToBytes Method (String, String)
  • Insert certificate information into an XML document (as a file) and output to memory.
• Sat.LastError Method
  • Retrieve the last error message.
• Sat.MakeDigestFromXml Method
  • Form message digest of piped string (cadena) from an XML file.
• Sat.MakePipeStringFromXml Method
  • Create the piped string (cadena) from an XML file.
• Sat.MakeSignatureFromXml Method
  • Create signature as a base64 string from data in an XML file ready to be inserted as a sello node.
• Sat.NewKeyFile Method
  • Save keyfile with a new password.
• Sat.QueryCert Method
  • Query an X.509 certificate.
• Sat.SetXmlNoMatch Method
  • Modify the string returned when GetXmlAttribute fails to find a match.
• Sat.SignXml Method
  • Sign an XML file
• Sat.SignXmlEx Method
  • Sign an XML file with extended options [deprecated].
• Sat.SignXmlToBytes Method (Byte[], String, String, String, SignOptions)
  • Sign XML data writing output to a byte array.
• Sat.SignXmlToBytes Method (String, String, String, String, SignOptions)
  • Sign XML file writing output to a byte array.
• Sat.Uuid Method
  • Generate a Universally Unique IDentifier (UUID) compliant with RFC 4122.
• Sat.ValidateXml Method
  • Validate an XML file against SAT specifications.
• Sat.VerifySignature Method
  • Verify the signature (sello) in an XML file.
• Sat.WritePfxFile Method
  • Create PFX (PKCS-12) file in PEM format suitable for a Cancelacin.
• Sat.XmlNoMatch Method
  • Error message returned when GetXmlAttribute fails to find a match
• Sat.XmlReceiptVersion Method
  • Find version number of Comprobante element or ID number for other document types.

Tfd Class Methods

• Tfd.AddSignedTfd Method
  • Add a signed Timbre Fiscal Digital (TFD) element to a CFDI document.
• Tfd.ExtractDigestFromSignature Method
  • Extract message digest from the selloSAT node in Timbre Fiscal Digital of CFDI document.
• Tfd.MakeDigestFromXml Method
  • Form message digest of cadena original del Timbre Fiscal Digital del SAT (TFD piped string) from CFDI XML file.
• Tfd.MakePipeStringFromXml Method
  • Create the cadena original del Timbre Fiscal Digital del SAT (TFD piped string) from CFDI XML file.
• Tfd.MakeSignatureFromXml Method
  • Create the selloSAT signature as a base64 string from TFD data in CFDI XML document.
• Tfd.VerifySignature Method
  • Verify the selloSAT signature in CFDI XML document.

General.Comments Method

Get additional information about the core DLL module.

Syntax

public static string Comments()

Public Shared Function Comments As String

Return Value

Example

Console.WriteLine(General.Comments());
// Licensed Developer Edition | Edicion de Desarrollador Licenciado.

General.CompileTime Method

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

Syntax

public static string CompileTime()

Public Shared Function CompileTime As String

Return Value

Example

Console.WriteLine(General.CompileTime());  // Feb 28 2021 18:29:46

General.ErrorLookup Method

Look up error code.

Syntax

public static string ErrorLookup(
	int errCode
)

Public Shared Function ErrorLookup ( _
	errCode As Integer _
) As String

Parameters

errCode

Code number (may be positive or negative)

Return Value

Example

Console.WriteLine(General.ErrorLookup(-10));
// Required data not found/Datos necesarios no encontrados (MISSING_ERROR)

General.FormatErrorMessage Method

Return an error message string for the last error.

Syntax

public static string FormatErrorMessage(
	int errCode
)

Public Shared Function FormatErrorMessage ( _
	errCode As Integer _
) As String

Parameters

errCode

Error code returned by last call (optional)

Return Value

Example

// Error (-28): XML restriction is violated/XML restriccion es violada (XML_FACET_ERROR):
// Bad attribute/atributo mal [iedu:instEducativas/@CURP] (line 30):
// 'JUAN01010101GTOHMD0' is too long/es demasiado largo, maximum length/longitud maxima=18

General.LastError Method

Retrieve the last error message.

Syntax

public static string LastError()

Public Shared Function LastError As String

Return Value

Remarks

Example

int n = Sat.ValidateXml("cfdv33a-badspec.xml");
Console.WriteLine("Sat.ValidateXml returns {0}", n);
// Sat.ValidateXml returns -27
Console.WriteLine(General.ErrorLookup(n));
// Invalid XML format/No valido formato XML (BAD_XML_ERROR)
Console.WriteLine(General.LastError());
// XML validation error/Error al validar XML: Required attribute 'Importe' missing for element 'cfdi:Concepto' (Line/numero de linea: 12); 
// XML validation error/Error al validar XML: Required attribute 'Importe' missing for element 'cfdi:Concepto' (Line/numero de linea: 13)

General.LicenceType Method

Get licence type.

Syntax

public static char LicenceType()

Public Shared Function LicenceType As Char

Return Value

General.ModuleName Method

Get full path name of core diFirmaSat DLL module.

Syntax

public static string ModuleName()

Public Shared Function ModuleName As String

Return Value

Example

Console.WriteLine(General.ModuleName());  // C:\WINDOWS\SYSTEM32\diFirmaSAT2.dll

General.Platform Method

Get the platform for which the core native DLL was compiled.

Syntax

public static string Platform()

Public Shared Function Platform As String

Return Value

General.Version Method

Return version number of core diFirmaSat DLL.

Syntax

public static int Version()

Public Shared Function Version As Integer

Return Value

Remarks

Example

int n = General.Version();
Console.WriteLine("Version = {0}", n);  // Version = 90215

Sat.Asciify Method (Byte[])

Replace any non-ASCII characters in an XML document (as a byte array) with XML character references (where permitted).

Syntax

public static string Asciify(
	byte[] xmlData
)

Public Shared Function Asciify ( _
	xmlData As Byte() _
) As String

Parameters

xmlData

Byte array containing XML data

Return Value

Remarks

Example

byte[] b = File.ReadAllBytes("cfdv40-ejemplo.xml");
string s = Sat.Asciify(b);
Console.WriteLine(s);
// <?xml version="1.0"?>
// <cfdi:Comprobante ... >
//   <cfdi:Emisor Rfc=" AAA010101AAA" Nombre="Esta es una demostraci&#xF3;n" RegimenFiscal="622"></cfdi:Emisor>
// ... [etc]

Sat.Asciify Method (String)

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

Syntax

public static string Asciify(
	string xmlFile
)

Public Shared Function Asciify ( _
	xmlFile As String _
) As String

Parameters

xmlFile

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

Return Value

Remarks

Example

Console.WriteLine(Sat.Asciify("cfdv40-ejemplo.xml");
// <?xml version="1.0" ?>
// <cfdi:Comprobante ... >
//   <cfdi:Emisor Rfc=" AAA010101AAA" Nombre="Esta es una demostraci&#xF3;n" RegimenFiscal="622"></cfdi:Emisor>
// ... [etc]

Sat.CheckKeyAndCert Method

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

Syntax

public static int CheckKeyAndCert(
	string keyFile,
	string password,
	string certFile
)

Public Shared Function CheckKeyAndCert ( _
	keyFile As String, _
	password As String, _
	certFile As String _
) As Integer

Parameters

keyFile

Name of private key file

password

Password for encrypted private key

certFile

X.509 certificate file or XML document with embedded certificado node

Return Value

Example

int n = Sat.CheckKeyAndCert("emisor.key", "12345678a", "emisor.cer");
Console.WriteLine("Sat.CheckKeyAndCert returns {0}", n);
// Sat.CheckKeyAndCert returns 0

// Cert and key do not match ...
n = Sat.CheckKeyAndCert("emisor.key", "12345678a", "pac.cer");
Console.WriteLine("Sat.CheckKeyAndCert returns {0}", n);
// Sat.CheckKeyAndCert returns -21
Console.WriteLine(General.ErrorLookup(n));
// Match not found/No se pudo encontrar datos coincidente (NO_MATCH_ERROR)
Console.WriteLine(General.LastError());
// Private key does not match key in certificate/La clave privada no coincide con la clave del certificado

Sat.DefaultDigestAlg Method

Return default digest (hash) algorithm for the XML document type.

Syntax

public static string DefaultDigestAlg(
	string xmlFile
)

Public Shared Function DefaultDigestAlg ( _
	xmlFile As String _
) As String

Parameters

xmlFile

Name of XML file

Return Value

Example

Console.WriteLine(Sat.DefaultDigestAlg("cfdv40-ejemplo.xml"));  // SHA-256

Sat.ExtractDigestFromSignature Method

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

Syntax

public static string ExtractDigestFromSignature(
	string xmlFile,
	string certFile
)

Public Shared Function ExtractDigestFromSignature ( _
	xmlFile As String, _
	certFile As String _
) As String

Parameters

xmlFile

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

certFile

X.509 certificate file (optional) to override embedded Certificado node.

Return Value

Remarks

Example

Console.WriteLine(Sat.ExtractDigestFromSignature("cfdv40-ejemplo-signed-tfd.xml"));
// 0FF1274E51FBB090489588D832BB1B5B36543302DECBB0A5490839B8C99E8755

Sat.FixBom Method

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

Syntax

public static int FixBom(
	string outputFile,
	string inputFile
)

Public Shared Function FixBom ( _
	outputFile As String, _
	inputFile As String _
) As Integer

Parameters

outputFile

Name of output file to be created with BOM.

inputFile

Name of input file.

Return Value

Remarks

Example

int n = Sat.FixBom("cfdv40_new-signed-with-BOM.xml", "cfdv40-signed-nobom.xml");
Console.WriteLine("Sat.FixBom returns {0}", n);
// Read in new file as bytes, truncate, and display first 3 bytes: expecting EF-BB-BF
byte[] b = File.ReadAllBytes("cfdv40_new-signed-with-BOM.xml");
Array.Resize(ref b, 3);
Console.WriteLine(BitConverter.ToString(b));
// EF-BB-BF

Sat.GetCertAsString Method

Get certificate data as a base64 string.

Syntax

public static string GetCertAsString(
	string fileName
)

Public Shared Function GetCertAsString ( _
	fileName As String _
) As String

Parameters

fileName

X.509 certificate file or XML file with Certificado node

Return Value

Remarks

Example

Console.WriteLine(Sat.GetCertAsString("emisor.cer"));
// MIIF+TCCA+GgAwIBAgIUMzAwMDEwMDAwMDAzMDAw ...

Sat.GetCertExpiry Method

Get expiry date of the X.509 certificate in ISO time format.

Syntax

public static string GetCertExpiry(
	string fileName
)

Public Shared Function GetCertExpiry ( _
	fileName As String _
) As String

Parameters

fileName

X.509 certificate file or XML file with certificado node

Return Value

Example

Console.WriteLine(Sat.GetCertExpiry("emisor.cer"));
// 2021-05-18T03:54:56Z

Sat.GetCertNumber Method

Get serial number of the X.509 certificate in "special" SAT format.

Syntax

public static string GetCertNumber(
	string fileName
)

Public Shared Function GetCertNumber ( _
	fileName As String _
) As String

Parameters

fileName

X.509 certificate file or XML file with certificado node

Return Value

Remarks

Example

// From certificate file directly
Console.WriteLine(Sat.GetCertNumber("emisor.cer"));
// 30001000000300023708
// From embedded Certificado attribute
Console.WriteLine(Sat.GetCertNumber("cfdv40-ejemplo-signed-tfd.xml"));
// 30001000000300023708

Sat.GetCertStart Method

Get start date of the X.509 certificate in ISO time format.

Syntax

public static string GetCertStart(
	string fileName
)

Public Shared Function GetCertStart ( _
	fileName As String _
) As String

Parameters

fileName

X.509 certificate file or XML file with certificado node

Return Value

Example

Console.WriteLine(Sat.GetCertStart("emisor.cer"));
// 2017-05-18T03:54:56Z

Sat.GetKeyAsString Method

Get private key data as a base64 string suitable for a llaveCertificado element in a Cancelacion XML document

Syntax

public static string GetKeyAsString(
	string fileName,
	string password,
	KeyOption keyOpt
)

Public Shared Function GetKeyAsString ( _
	fileName As String, _
	password As String, _
	keyOpt As KeyOption _
) As String

Parameters

fileName

Encrypted private key file

password

Password for encrypted private key

keyOpt

Type: KeyOption
Output format (optional, default=UnencryptedBase64)

Return Value

Remarks

Example

Console.WriteLine(Sat.GetKeyAsString("emisor.key", "12345678a"));
// PFJTQUtleVZhbHVlPjxNb2R1bHVzP ... WYWx1ZT4=

Console.WriteLine(Sat.GetKeyAsString("emisor.key", "12345678a", KeyOption.EncryptedPEM));
// -----BEGIN ENCRYPTED PRIVATE KEY-----
// MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIAgEAAoIBAQACAggA
// ... rbw=
// -----END ENCRYPTED PRIVATE KEY-----

Sat.GetXmlAttribute Method

Extract attribute data from an XML file.

Syntax

public static string GetXmlAttribute(
	string xmlFile,
	string attributeName,
	string elementName
)

Public Shared Function GetXmlAttribute ( _
	xmlFile As String, _
	attributeName As String, _
	elementName As String _
) As String

Parameters

xmlFile

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

attributeName

Name of attribute

elementName

Name of element or xpath expression (see remarks)

Return Value

Remarks

Example

Console.WriteLine(Sat.GetXmlAttribute("cfdv40-ejemplo.xml", "Nombre", "cfdi:Emisor"));
// Esta es una demostración

Sat.InsertCert Method

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

Syntax

public static int InsertCert(
	string newFile,
	string baseFile,
	string certFile
)

Public Shared Function InsertCert ( _
	newFile As String, _
	baseFile As String, _
	certFile As String _
) As Integer

Parameters

newFile

Name of new file to be created.

baseFile

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

certFile

X.509 certificate file.

Return Value

Example

// Take an XML file without a NoCertificado...
string fname = cfdv40-ejemplo-nocertnum.xml";
Console.WriteLine("Start file '{0}'.NoCertificado=[{1}]", fname, Sat.GetXmlAttribute(fname, "NoCertificado", "cfdi:Comprobante"));
Console.WriteLine("Start file '{0}'.Certificado={1} bytes", fname, Sat.GetXmlAttribute(fname, "Certificado", "cfdi:Comprobante").Length);
// Insert certificate details into intermediate file...
string interfile = "cfdv40_new-base-pluscert.xml";
int n = Sat.InsertCert(interfile, fname, "emisor.cer");
Console.WriteLine("Sat.InsertCert() returns {0} (expecting 0)", n);
Debug.Assert(0 == n, "Sat.InsertCert failed");
Console.WriteLine("Inter file '{0}'.NoCertificado=[{1}]", interfile, Sat.GetXmlAttribute(interfile, "NoCertificado", "cfdi:Comprobante"));
Console.WriteLine("Inter file '{0}'.Certificado={1} bytes", interfile, Sat.GetXmlAttribute(interfile, "Certificado", "cfdi:Comprobante").Length);
// Start file 'cfdv40-ejemplo-nocertnum.xml'.NoCertificado=[]
// Start file 'cfdv40-ejemplo-nocertnum.xml'.Certificado=0 bytes
// Sat.InsertCert() returns 0 (expecting 0)
// Inter file 'cfdv40_new-base-pluscert.xml'.NoCertificado=[30001000000300023708]
// Inter file 'cfdv40_new-base-pluscert.xml'.Certificado=1836 bytes

Sat.InsertCertToBytes Method (Byte[], String)

Insert certificate information into an XML document (as a byte array) and output to memory.

Syntax

public static byte[] InsertCertToBytes(
	byte[] xmlData,
	string certFile
)

Public Shared Function InsertCertToBytes ( _
	xmlData As Byte(), _
	certFile As String _
) As Byte()

Parameters

xmlData

Byte array containing XML data

certFile

X.509 certificate file

Return Value

Remarks

Example

// Pass input XML data as a byte array
byte[] xmlArr = File.ReadAllBytes("cfdv40-ejemplo-nocertnum.xml");
string cerStr = Sat.GetCertAsString("emisor.cer");
byte[] b = Sat.InsertCertToBytes(xmlArr, cerStr);
Console.WriteLine(System.Text.Encoding.UTF8.GetString(b));
// <cfdi:Comprobante 
// ...
// NoCertificado="30001000000300023708" Sello="" Certificado="MIIF+TCCA+GgAwIBAgIU ...

Sat.InsertCertToBytes Method (String, String)

Insert certificate information into an XML document (as a file) and output to memory.

Syntax

public static byte[] InsertCertToBytes(
	string xmlFile,
	string certFile
)

Public Shared Function InsertCertToBytes ( _
	xmlFile As String, _
	certFile As String _
) As Byte()

Parameters

xmlFile

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

certFile

X.509 certificate file

Return Value

Remarks

Example

// Pass input XML data as a string
string xmlStr = File.ReadAllText("cfdv40-ejemplo-nocertnum.xml");
string cerStr = Sat.GetCertAsString("emisor.cer");
byte[] b = Sat.InsertCertToBytes(xmlStr, cerStr);
Console.WriteLine(System.Text.Encoding.UTF8.GetString(b)); 
// <cfdi:Comprobante 
// ...
// NoCertificado="30001000000300023708" Sello="" Certificado="MIIF+TCCA+GgAwIBAgIU ...

Sat.LastError Method

Retrieve the last error message.

Syntax

public static string LastError()

Public Shared Function LastError As String

Return Value

Remarks

Example

// Attempt to sign but input file does not comply with CFDi specifications
int n = satSignXml("cfdv33a-out.xml", "cfdv33a-badspec.xml", "emisor.key", "12345678a", "emisor.cer");
Console.WriteLine("Error {0}: {1}", n, Sat.ErrorLookup(n));
// Error -10: Required data not found/Datos necesarios no encontrados (MISSING_ERROR)
Console.WriteLine(Sat.LastError());
// Attribute 'Importe' is mandatory/Atributo es obligatorio

Sat.MakeDigestFromXml Method

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

Syntax

public static string MakeDigestFromXml(
	string xmlFile
)

Public Shared Function MakeDigestFromXml ( _
	xmlFile As String _
) As String

Parameters

xmlFile

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

Return Value

Example

Console.WriteLine(Sat.MakeDigestFromXml("cfdv40-ejemplo-signed-tfd.xml"));
// 0ff1274e51fbb090489588d832bb1b5b36543302decbb0a5490839b8c99e8755

Sat.MakePipeStringFromXml Method

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

Syntax

public static string MakePipeStringFromXml(
	string xmlFile
)

Public Shared Function MakePipeStringFromXml ( _
	xmlFile As String _
) As String

Parameters

xmlFile

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

Return Value

Example

string s = Sat.MakePipeStringFromXml("cfdv40-ejemplo.xml");
Console.WriteLine(s);
// ||3.3|A|123ABC|2017-12-04T01:23:59|02|...[cut]...||

Sat.MakeSignatureFromXml Method

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

Syntax

public static string MakeSignatureFromXml(
	string xmlFile,
	string keyFile,
	string password
)

Public Shared Function MakeSignatureFromXml ( _
	xmlFile As String, _
	keyFile As String, _
	password As String _
) As String

Parameters

xmlFile

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

keyFile

Name of private key file

password

Password

Return Value

Example

string s = Sat.MakeSignatureFromXml("cfdv40-ejemplo.xml", "emisor.key", "12345678a");
Console.WriteLine(s);
// JQJd6rbiMZj1tZVb1Ta8l88bE7pTDm/aAl ...

Sat.NewKeyFile Method

Save keyfile with a new password.

Syntax

public static int NewKeyFile(
	string newFile,
	string newPassword,
	string keyFile,
	string keyPassword,
	KeyFormat format
)

Public Shared Function NewKeyFile ( _
	newFile As String, _
	newPassword As String, _
	keyFile As String, _
	keyPassword As String, _
	format As KeyFormat _
) As Integer

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

Type: KeyFormat
Format to save file [default = DER binary].

Return Value

Example

string password = "12345678a";
string newpassword = "password123";
int n = Sat.NewKeyFile("emisor_new.pem", newpassword, "emisor.key", password, KeyFormat.PEM);
Debug.Assert(n == 0, "Sat.NewKeyFile failed");
Console.WriteLine(File.ReadAllText("emisor_new.pem"));
// -----BEGIN ENCRYPTED PRIVATE KEY-----
// MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQIn2sl+Cj3VtgCAggA ...
// -----END ENCRYPTED PRIVATE KEY-----

Sat.QueryCert Method

Query an X.509 certificate.

Syntax

public static string QueryCert(
	string fileName,
	Query query
)

Public Shared Function QueryCert ( _
	fileName As String, _
	query As Query _
) As String

Parameters

fileName

X.509 certificate file or XML file with certificado node

query

Type: Query
Query

Return Value

Sat.SetXmlNoMatch Method

Modify the string returned when GetXmlAttribute(String, String, String) fails to find a match.

Syntax

public static void SetXmlNoMatch(
	string value
)

Public Shared Sub SetXmlNoMatch ( _
	value As String _
)

Parameters

value

New string value.

Example

// Show default NoMatch string
Console.WriteLine(Sat.XmlNoMatch());
// !NO MATCH!
string fname = "cfdv40-ejemplo-signed-tfd.xml";
// Look for element that isn't there
Console.WriteLine(Sat.GetXmlAttribute(fname, "", "/Comprobante/notthere"));
// !NO MATCH!
// Set a new NoMatch string
Sat.SetXmlNoMatch("##No coinciden##");
Console.WriteLine(Sat.GetXmlAttribute(fname, "", "/Comprobante/notthere"));
// ##No coinciden##

Sat.SignXml Method

Sign an XML file

Syntax

public static int SignXml(
	string newFile,
	string baseFile,
	string keyFile,
	string password,
	string certFile,
	SignOptions signOpts
)

Public Shared Function SignXml ( _
	newFile As String, _
	baseFile As String, _
	keyFile As String, _
	password As String, _
	certFile As String, _
	signOpts As SignOptions _
) As Integer

Parameters

newFile

Name of new file to be created

baseFile

Name of base XML file to be signed (or a string containing XML data)

keyFile

Name of private key file

password

Password

certFile

Name of X.509 certificate file to be included in output XML (optional)

signOpts

Type: SignOptions
Options for output format (optional)

Return Value

Remarks

Example

int n = Sat.SignXml("cfdv40-signed_new.xml", "cfdv40-ejemplo.xml", "emisor.key", "12345678a", "emisor.cer");

Sat.SignXmlEx Method

Sign an XML file with extended options [deprecated].

Syntax

[ObsoleteAttribute("Use Sat.SignXml with optional SignOptions parameter")]
public static int SignXmlEx(
	string newFile,
	string xmlFile,
	string keyFile,
	string password,
	string certFile,
	SignOptions signOpts
)

<ObsoleteAttribute("Use Sat.SignXml with optional SignOptions parameter")> _
Public Shared Function SignXmlEx ( _
	newFile As String, _
	xmlFile As String, _
	keyFile As String, _
	password As String, _
	certFile As String, _
	signOpts As SignOptions _
) As Integer

Parameters

newFile

Name of new file to be created

xmlFile

Name of base XML file to be signed

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

Type: SignOptions
Options for output format

Return Value

Remarks

Example

int n = Sat.SignXmlEx(newname, fname, keyfile, password, certfile, SignOptions.BigFile);

Sat.SignXmlToBytes Method (Byte[], String, String, String, SignOptions)

Sign XML data writing output to a byte array.

Syntax

public static byte[] SignXmlToBytes(
	byte[] xmlData,
	string keyFile,
	string password,
	string certFile,
	SignOptions signOpts
)

Public Shared Function SignXmlToBytes ( _
	xmlData As Byte(), _
	keyFile As String, _
	password As String, _
	certFile As String, _
	signOpts As SignOptions _
) As Byte()

Parameters

xmlData

Byte array containing XML data

keyFile

Name of private key file (or string containing key data in PEM format)

password

Password for 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

Type: SignOptions
Options for output format

Return Value

Remarks

Example

string password = "12345678a";
string keyStr = Sat.GetKeyAsString("emisor.key", password, KeyOption.EncryptedPEM);
string cerStr = Sat.GetCertAsString("emisor.cer");
byte[] xmlArr = File.ReadAllBytes("cfdv40-ejemplo.xml");
byte[] xmlArrSigned = Sat.SignXmlToBytes(xmlArr, keyStr, password, cerStr, 0);
Console.WriteLine(System.Text.Encoding.UTF8.GetString(xmlArrSigned));
// <?xml version="1.0" encoding="UTF-8"?>
// <cfdi:Comprobante xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cfdi="http://www.sat.gob.mx/cfd/3" ...

Sat.SignXmlToBytes Method (String, String, String, String, SignOptions)

Sign XML file writing output to a byte array.

Syntax

public static byte[] SignXmlToBytes(
	string xmlFile,
	string keyFile,
	string password,
	string certFile,
	SignOptions signOpts
)

Public Shared Function SignXmlToBytes ( _
	xmlFile As String, _
	keyFile As String, _
	password As String, _
	certFile As String, _
	signOpts As SignOptions _
) As Byte()

Parameters

xmlFile

Name of base XML file to be signed

keyFile

Name of private key file (or string containing key data in PEM format)

password

Password for 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

Type: SignOptions
Options for output format

Return Value

Remarks

Example

byte[] b = Sat.SignXmlToBytes("cfdv40-ejemplo.xml", "emisor.key", "12345678a", "emisor.cer", SignOptions.Default);
Console.WriteLine(System.Text.Encoding.UTF8.GetString(b));
// <?xml version="1.0" encoding="UTF-8"?>
// <cfdi:Comprobante xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cfdi="http://www.sat.gob.mx/cfd/3" ...

Sat.Uuid Method

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

Syntax

public static string Uuid()

Public Shared Function Uuid As String

Return Value

Remarks

Example

Console.WriteLine(Sat.Uuid());
// 343c6b13-4f69-4d2a-97e6-64cb770c7677

Sat.ValidateXml Method

Validate an XML file against SAT specifications.

Syntax

public static int ValidateXml(
	string xmlFile,
	XmlOption xmlOpt
)

Public Shared Function ValidateXml ( _
	xmlFile As String, _
	xmlOpt As XmlOption _
) As Integer

Parameters

xmlFile

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

xmlOpt

Type: XmlOption
Option for strict or loose XML restrictions (optional, default=Strict)

Return Value

Remarks

Example

int n = Sat.ValidateXml("cfdv40-ejemplo.xml");
Console.WriteLine("Sat.ValidateXml returns {0}", n);
// Sat.ValidateXml returns 0

int n = Sat.ValidateXml("cfdv40-iedu-badcurp.xml");
Console.WriteLine("Sat.ValidateXml returns {0}", n);
// Sat.ValidateXml returns -28
Console.WriteLine(General.ErrorLookup(n));
// XML restriction is violated/XML restriccion es violada (XML_FACET_ERROR)
Console.WriteLine(General.LastError());
// Bad attribute/atributo mal [iedu:instEducativas/@CURP] (line 30): 
// 'JUAN01010101GTOHMD0' is too long/es demasiado largo, maximum length/longitud maxima=18

// Input has valid XML form but an invalid facet error against SAT specifications
// Using the "Loose" option validates that the XML form is still correct.
int n = Sat.ValidateXml("cfdv40-iedu-badcurp.xml", XmlOption.Loose);
Console.WriteLine("Sat.ValidateXml(Loose) returns {0}", n);
// Sat.ValidateXml(Loose) returns 0

Sat.VerifySignature Method

Verify the signature (sello) in an XML file.

Syntax

public static int VerifySignature(
	string xmlFile,
	string certFile
)

Public Shared Function VerifySignature ( _
	xmlFile As String, _
	certFile As String _
) As Integer

Parameters

xmlFile

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

certFile

X.509 certificate file (optional)

Return Value

Remarks

Example

Console.WriteLine(Sat.VerifySignature("cfdv40-ejemplo-signed.xml"));
// 0
Console.WriteLine(Sat.VerifySignature("cfdv40-badsig.xml"));
// -15
Console.WriteLine(General.ErrorLookup(-15));
// Decryption error/De error de descifrado (DECRYPT_ERROR)

Sat.WritePfxFile Method

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

Syntax

public static int WritePfxFile(
	string pfxFile,
	string pfxPassword,
	string keyFile,
	string keyPassword,
	string certFile,
	PfxFormat pfxFormat
)

Public Shared Function WritePfxFile ( _
	pfxFile As String, _
	pfxPassword As String, _
	keyFile As String, _
	keyPassword As String, _
	certFile As String, _
	pfxFormat As PfxFormat _
) As Integer

Parameters

pfxFile

Name of output PFX file to be created

pfxPassword

Password to open new PFX file

keyFile

Name of encrypted key file

keyPassword

Password for encrypted key file

certFile

Name of X.509 certificate file

pfxFormat

Type: PfxFormat
Output format for PFX file (optional, default=plain base64)

Return Value

Example

string password = "12345678a";
string newpassword = "clavedesalida";
int n = Sat.WritePfxFile("archivo_new-pfx.txt", newpassword, "emisor.key", password, "emisor.cer");
Debug.Assert(n == 0, "Sat.WritePfxFile failed");
Console.WriteLine(File.ReadAllText("archivo_new-pfx.txt"));
// MIIMOQIBAzCCC/8GCSqGSIb3DQEHAaCCC/AEggvsMIIL6DCCBp8GCSqGSIb3DQEH ...

Sat.XmlNoMatch Method

Error message returned when GetXmlAttribute(String, String, String) fails to find a match

Syntax

public static string XmlNoMatch()

Public Shared Function XmlNoMatch As String

Return Value

Remarks

Example

Console.WriteLine(Sat.XmlNoMatch());
// !NO MATCH!

Sat.XmlReceiptVersion Method

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

Syntax

public static int XmlReceiptVersion(
	string xmlFile
)

Public Shared Function XmlReceiptVersion ( _
	xmlFile As String _
) As Integer

Parameters

xmlFile

Name of XML file

Return Value

Example

Console.WriteLine(Sat.XmlReceiptVersion("cfdv40-ejemplo.xml"));  // 40

Tfd.AddSignedTfd Method

Add a signed Timbre Fiscal Digital (TFD) element to a CFDI document.

Syntax

public static int AddSignedTfd(
	string newFile,
	string inputFile,
	string keyFile,
	string password,
	string certFile
)

Public Shared Function AddSignedTfd ( _
	newFile As String, _
	inputFile As String, _
	keyFile As String, _
	password As String, _
	certFile As String _
) As Integer

Parameters

newFile

Name of new file to be created

inputFile

Name of existing CFDI file

keyFile

Name of PAC's private key file

password

Password for private key

certFile

Name of PAC's X.509 certificate that matches the keyFile

Return Value

Remarks

Example

int n = Tfd.AddSignedTfd(newname, fname, keyfile, password, certfile);
Console.WriteLine("Tfd.AddSignedTfd returns {0}", n);  // 0
string s = Sat.GetXmlAttribute("cfdv40-ejemplo_signed.xml", "SelloSAT", "TimbreFiscalDigital");
// SelloSat=Qncw19SZ0w/uxkwCYkf/7V3DF3j28Jp1XyNVyqiyOreq0S ...

Tfd.ExtractDigestFromSignature Method

Extract message digest from the selloSAT node in Timbre Fiscal Digital of CFDI document.

Syntax

public static string ExtractDigestFromSignature(
	string xmlFile,
	string certFile
)

Public Shared Function ExtractDigestFromSignature ( _
	xmlFile As String, _
	certFile As String _
) As String

Parameters

xmlFile

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

certFile

X.509 certificate file of PAC who signed the TFD (required)

Return Value

Tfd.MakeDigestFromXml Method

Form message digest of cadena original del Timbre Fiscal Digital del SAT (TFD piped string) from CFDI XML file.

Syntax

public static string MakeDigestFromXml(
	string xmlFile
)

Public Shared Function MakeDigestFromXml ( _
	xmlFile As String _
) As String

Parameters

xmlFile

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

Return Value

Tfd.MakePipeStringFromXml Method

Create the cadena original del Timbre Fiscal Digital del SAT (TFD piped string) from CFDI XML file.

Syntax

public static string MakePipeStringFromXml(
	string xmlFile
)

Public Shared Function MakePipeStringFromXml ( _
	xmlFile As String _
) As String

Parameters

xmlFile

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

Return Value

Tfd.MakeSignatureFromXml Method

Create the selloSAT signature as a base64 string from TFD data in CFDI XML document.

Syntax

public static string MakeSignatureFromXml(
	string xmlFile,
	string keyFile,
	string password
)

Public Shared Function MakeSignatureFromXml ( _
	xmlFile As String, _
	keyFile As String, _
	password As String _
) As String

Parameters

xmlFile

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

keyFile

Name of private key file

password

Password

Return Value

Remarks

Tfd.VerifySignature Method

Verify the selloSAT signature in CFDI XML document.

Syntax

public static int VerifySignature(
	string xmlFile,
	string certFile
)

Public Shared Function VerifySignature ( _
	xmlFile As String, _
	certFile As String _
) As Integer

Parameters

xmlFile

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

certFile

X.509 certificate file of PAC who signed the TFD (required)

Return Value

Enumerations

• KeyFormat Enumeration - Format for saved key files.
• KeyOption Enumeration - Options for key output in Sat.GetKeyAsString().
• PfxFormat Enumeration - Options for PKCS12 (PFX) output in Sat.WritePfxFile().
• Query Enumeration - Options for certificate query.
• SignOptions Enumeration - Options for signing XML.
• XmlOption Enumeration - Options for XML validation.

KeyFormat Enumeration

Format for saved key files.

Syntax

public enum KeyFormat

Public Enumeration KeyFormat

Members

KeyOption Enumeration

Options for key output in Sat.GetKeyAsString().

Syntax

public enum KeyOption

Public Enumeration KeyOption

Members

PfxFormat Enumeration

Options for PKCS12 (PFX) output in Sat.WritePfxFile().

Syntax

public enum PfxFormat

Public Enumeration PfxFormat

Members

Query Enumeration

Options for certificate query.

Syntax

public enum Query

Public Enumeration Query

Members

SignOptions Enumeration

Options for signing XML.

Syntax

[FlagsAttribute]
public enum SignOptions

<FlagsAttribute> _
Public Enumeration SignOptions

Members

XmlOption Enumeration

Options for XML validation.

Syntax

public enum XmlOption

Public Enumeration XmlOption

Members

Index