FirmaSAT is a free utility for users of the CryptoSys PKI Toolkit which enables you to create and read digital receipts (Comprobantes Fiscal Digital) as specified by the Servicio de Administración Tributaria* (SAT) in Mexico. FirmaSAT is a command-line program that works with Version 2.0 SAT XML files [REF1]. You can run it from the command-line, or call it from another program (e.g. from ColdFusion). There is also an API interface for advanced programmers. For more information, see also SAT Mexico and the CryptoSys PKI Toolkit.
FirmaSAT enables the user to:
Note: If you installed FirmaSAT before 8 August 2007, then un-install it first using Start > Settings > Control Panel > Add/Remove Programs before re-installing.
(Alternatively, open a command-line window (MS-DOS window) and change directory by typing
CD %APPDATA%\FirmaSAT.)
FirmaSat LIBINFO. If correctly installed, the output should be similar to:
>FirmaSAT LIBINFO FirmaSat Version 1.0.0 last updated Aug 5 2007 16:25:25. diFirmaSat DLL: Version: 101 Module: C:\Documents and Settings\...\Application Data\FirmaSAT\diFirmaSat.dll Compiled: Aug 8 2007 04:13:14 CryptoSys PKI DLL: Version: 310 Module: C:\WINDOWS\system32\diCrPKI.dll Compiled: Aug 2 2007 15:19:35
Usage: FirmaSat ACTION [OPTIONS] [-i] infile [[-o] outfile] ACTION (one of): ATTRIBUTE = extract a given Attribute from XML file. HELP = display this Help. LIBINFO = display DLL Library details. MAKESIG = Make signature from XML file. PIPESTRING = make Pipestring from XML file. SIGNXML = create the Signature and update `sello' field in XML file. VERIFYSIG = Verify the signature in XML file. XMLOK = validate XML file. OPTIONS: -k <keyfile> (required for SIGNXML) -p <password> (required for SIGNXML) -c <certfile> (optional X.509 certificate file for VERIFYSIG/SIGNXML) -a <attribute-name> (required for ATTRIBUTE action) -e <element-name> (ditto) -s <statusfile> (default=none; for stdout use ``-s @'') -t <tracking-info> (optional info for the status file) -d show debug info; -dd show more For help type ``FirmaSat HELP''
All action names and options are case-insensitive. Only the first letter of the action name is required,
so, for example, SIGNXML, Sign, si and S
are all valid for the SIGNXML action.
To see the latest usage information, type ``FirmaSAT HELP''.
As an option, you can specify the name of a tracking file (using the -s option) which will contain the results of the operation. This can be used for tracking automated procedures.
All actions (except HELP and LIBINFO) require an input file to be specified. The input file must be a valid XML file encoded in UTF-8. Only SAT version 2.0 format is supported.
To create the piped-string using PIPESTRING or to make the signature using the MAKESIG action, only the fields required for the piped string need be present in the XML file.
To validate the XML file using XMLOK, all required fields must exist.
To verify the signature using VERIFYSIG, the `sello' field must exist and either the 'certificado' field exists in the XML file or the X.509 certificate file is specified in the command line using the -c option.
To sign the XML file using the SIGNXML action, then `sello' must exist as an empty field (i.e. sello="").
The output XML file will have the `sello' field completed.
A new output XML file is created by this action. The input file is not touched.
If an X.509 certificate is specified using the -c option, then the `certificado' and `noCertificado' fields
will be completed provided empty fields are specified in the input XML file.
For example, your XML file for input should include the following:
<?xml version="1.0" encoding="utf-8"?> <Comprobante ... version="2.0" noCertificado="" sello="" certificado="">
FirmaSAT XMLOK Muestra_v2_base.xml
will check that the input file is validly formed XML. The output in this case should be
OK
If the file is not validly formed, the output would be like:
Error code -27: Invalid XML format: XML Validation Error: Required attribute 'formaDePago' missing for element 'Comprobante' (Line: 2 Col: 311); ... etc ...
Note that this is merely checking that the XML formatting of the input file is OK.
FirmaSAT PIPESTRING Muestra_v2_base.xml
will output the "piped-string" to the console, e.g.
||2.0|A|1|2006-06-22T16:30:00|1|2006|ingreso| ...etc... |150.00|150|IVA|15.00|52.50||
Note that non-ASCII characters will not display properly on the console. It is better to output directly to a file:
FirmaSAT PIPESTRING Muestra_v2_base.xml pipedstring.txt
FirmaSAT MAKESIG -k AAA010101AAA_0408021316S.key -p Empresa1 Muestra_v2_base.xml
will create the signature `sello' from the input XML file using the private key and password provided. The output should be
ScAek/O0o3Qn+HlO7mVa5pHCIQjwgFGUjT48W0gIfZ9aeBZVk/wdnboUgY+zhGoe+G3oSR6fhx2zuZLJ Mb6RGppvFyVFKz524N9WrkpUNGvD4U5kMQZrOlD+m2k8u+ArSx8pN76IfOT+wyOV30+AXzCn2EDrmoQd bikP2XKMra4=
FirmaSAT SIGNXML -c AAA010101AAAsd.cer -k AAA010101AAA_0408021316S.key ¶ -p Empresa1 Muestra_v2_base.xml Muestra_v2_signed.xml
will create a new signed XML file `Muestra_v2_signed.xml' from the input XML file `Muestra_v2_base.xml'. It will sign using the private key in `AAA010101AAA_0408021316S.key' and will add the `certificado' details from the X.509 certificate file `AAA010101AAAsd.cer'. (Note that the above line is split for display purposes - it should be entered in one continuous line.) See also the caution below about hard-coding passwords.
FirmaSAT VERIFYSIG Muestra_v2_signed.xml
will verify the signature in the signed XML file. In this case it will use the `certificado' details in the XML file itself.
FirmaSAT VERIFYSIG Muestra_v2_signednocert.xml
will try to verify the signature in the signed XML file. In this case, there is no `certificado' field in the XML file and an error will result:
Error code -6: Parameter is wrong or missing: Require a certificate file
FirmaSAT VERIFYSIG -c AAA010101AAAsd.cer Muestra_v2_signednocert.xml
will use the certificate `AAA010101AAAsd.cer' to verify the signature in the XML file. This should produce
OK
FirmaSAT ATTRIBUTE -d -a sello -e Comprobante -i Muestra_v2_signed.xml
will extract the attribute `sello' from the element `Comprobante' in the input XML file. The output should look like this:
Attribute=[sello] Element=[Comprobante] ScAek/O0o3Qn+HlO7mVa5pHCIQjwgFGUjT48W0gIfZ9aeBZVk/wdnboUgY+zhGoe+G3oSR6fhx2zuZLJ Mb6RGppvFyVFKz524N9WrkpUNGvD4U5kMQZrOlD+m2k8u+ArSx8pN76IfOT+wyOV30+AXzCn2EDrmoQd bikP2XKMra4=
FirmaSAT HELP
will display the usage syntax.
FirmaSAT LIBINFO
will display details about the program and the libraries it depends on.
CAUTION: You should never hard-code the password for your production private key anywhere. You should always require the user to enter it each time. Here is an example of a simple batch file that expects the password to be typed in as the first parameter.
@echo off if "%1"=="" goto NOPASSWORD set mypwd=%1 FirmaSAT SIGNXML -c AAA010101AAAsd.cer -k AAA010101AAA_0408021316S.key ¶ -s @ -p %mypwd% Muestra_v2_base.xml Muestra_v2_signed1.xml set mypwd= goto DONE :NOPASSWORD echo ERROR: no password :DONE
Use a text editor to create a batch file called, say, SignXMLTest.bat with the above text in it
(you will need to remove the ¶ character).
Then type ``SignXMLTest Empresa1'' on the command line.
>SignXMLTest Empresa1 STATUS: 0 ERRORDESCRIPTION: OK DATETIMECREATED: Mon Aug 06 20:24:59 2007
To call from a C or C++ program, use
#include diFirmaSAT.h
in your source code,
call the functions, and link with the diFirmaSat.lib library.
For more details on the core functions, see the file diFirmaSAT.h.
If you are a Licensed User of the CryptoSys PKI Toolkit and ask nicely,
we will send you the source code for the FirmaSat.exe wrapper program, which shows how the calls to
diFirmaSat.dll are made.
The program should work on all 32-bit versions of Windows 95/98/Me/NT4/2000/XP/2003/Vista.
Dependencies: The program FirmaSAT.exe is dependent on the library file
diFirmaSat.dll, which,
in turn, is dependent on the core CryptoSys PKI DLL diCrPKI.dll.
The files FirmaSAT.exe and diFirmaSat.dll should be kept in the same directory.
The file diCrPKI.dll must exist somewhere in the standard Windows library search path,
e.g. C:\WINDOWS\system32.
None of these files need to be (or can be) registered with RegSvr32.
Validation of the XML is carried out using a DTD file plus some other checks.
This catches most major problems but will not catch strict element typing issues.
The content of the Addenda element is ignored completely.
It will not cope with "special" extensions to the ComplementoConcepto
element.
To carry out a more accurate validation using the XSD file provided by SAT, you will need to use a dedicated XML validation tool.
If you are interested, please compare the official XSD file (38 kB) with the DTD file we use (8 kB). The awful English translations were made using Babelfish. The core DTD definitions are even smaller (3.2 kB).
If you can see a problem in the DTD file, please tell us.
We agree with Rick Jelliffe's comparison between DTD and XSD:
A DTD is a terse thing with a simple macro mechanism that makes people yearn for an XML syntax and more powerful abstractions. It can only handle simple structures.
An XSD is a verbose thing with multiple abstractions that makes people yearn for a terser syntax and less to learn. It still can only handle simple structures.
A simple DTD expression
<!ELEMENT ROOT (A?,B+,C*)>
becomes, in an XML schema,
<element name="ROOT">
<complexType content="elementOnly">
<element ref="t:A" minOccurs="0">
<element ref="t:B" maxOccurs="unbounded">
<element ref="t:C" minOccurs="0" maxOccurs="unbounded">
</complexType>
<element>
As you can see, XML schemas very quickly become virtually unreadable by mere humans.
Contact: Send us an email.
There is no support for FirmaSAT, but we will answer short questions. Obviously we will respond to potential bugs, so please let us know if you find one. We also offer custom programming if you want something special created for your organisation.
For more information on the CryptoSys PKI Toolkit, go to <www.cryptosys.net/pki/>.
This document last updated: 12 June 2009
