FirmaSAT Manual

Introduction

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.

Features

FirmaSAT enables the user to:

create the "piped-string" required for the signature from an XML file
make the signature string in base64 format given an XML file, the private key file and its password
validate an XML file for the correct SAT form
verify a signature in an XML file using either the encapsulated `certificado' field or a separate X.509 certificate file
sign a given XML file by creating and adding the `sello' field and (optionally) the 'certificado' and 'noCertficado' fields
extract a given attribute from the XML file

How to get started

Make sure that the CryptoSys PKI Toolkit is installed on your system. If you are a licensed user, you should already have it installed. If not, you can download and install a free, trial version from here.
Install FirmaSAT using one of these options (last updated 2007-08-08T09:05Z):
- WinZip self-extracting EXE file (151 kB) or
- Zipped version with instructions (135 kB)
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.
Open a command-line window in the FirmaSAT directory by using the menu options Start > Programs > FirmaSAT > FirmaSAT-open.
(Alternatively, open a command-line window (MS-DOS window) and change directory by typing CD %APPDATA%\FirmaSAT.)

Type 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

If you get an error message that says "the application has failed to start because diCrPKI.dll/diFirmaSat.dll was not found", then the installation is not correct.

Syntax

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.

Input XML file

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="">

Remarks

The output from the PIPESTRING or MAKESIG actions is UTF-8. This may not appear correctly when output to the stdout terminal. For the correct data, always output to a text file.
You will need a UTF-8-aware text editor to create the input XML file and to read the output files. We use IDM Computer Solutions' Ultra-Edit text editor which automatically detects and displays UTF-8 characters. The more recent versions of Windows NotePad are UTF-8-aware.
The XMLOK action merely confirms that the XML file is correctly formed. The validation provided by FirmaSAT uses a DTD file and may not catch every strict detail. See XML Validation for more details.
CAUTION: Currently, there are no checks made that the private key and the certificate match. However, the user can use the VERIFYSIG action on the output XML file to confirm that the signature and certificate are correctly matched.

Examples

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.

Hard-coded passwords - no!

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. Then type ``SignXMLTest Empresa1'' on the command line.

>SignXMLTest Empresa1

STATUS: 0
ERRORDESCRIPTION: OK
DATETIMECREATED: Mon Aug 06 20:24:59 2007

API Interface

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.

Frequently Asked Questions

Why do the strange characters like Ã© appear in my output?: All output is in UTF-8. On a command-line console or in an old text editor that is not UTF-8-aware, the accented characters (óéíáñ) will appear as two `funny' characters. For example, "México" will appear as "MÃ©xico". The solution is always to output to a text file and use a text editor that can cope with UTF-8.
Why is this written in English, you Yanqui Imperialist!?: Actually, we're Australian. We have tried hard with our very basic knowledge of Spanish, but we don't have enough to write up a technical document. Would you like to help?

Legal Bits

We have no connection whatsoever with or any endorsement from the Servicio de Administración Tributaria in Mexico.
FirmaSAT is provided at no cost as a utility for Licensed users of the CryptoSys PKI Toolkit. There is no support. Use at your own risk. Please make your own checks to ensure it does what you expect. It is provided 'as is' with no warranties. If you do not accept the licence conditions, then do not use it.

Technical Details

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.

XML Validation

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).

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.

If you can see a problem in the DTD file, please tell us.

Acknowledgments

FirmaSAT uses code from 'Parsifal XML Parser' copyright (c) 2002-2005 Toni Uusitalo released to the public domain 2002-11-15 <http://www.saunalahti.fi/~samiuus/toni/xmlproc/>.
The executable was compressed using UPX, the Ultimate Packer for eXecutables available from http://upx.sourceforge.net or http://www.oberhumer.com/opensource/upx/.
Thanks to the guys at NullSoft for their Nullsoft Scriptable Install System.
Thanks to Guillermo Dewey and Alvaro Cervantes for their help.

References

[REF1]: Modificación al Anexo 20 de la Resolución Miscelánea Fiscal para 2006, Servicio de Administración Tributaria, Mexico, 22 June 2006, ftp://ftp2.sat.gob.mx/asistencia_ftp/publicaciones/solcedi/Anexo_20_2006.pdf

Contact us

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/>.

Revision History

This document last updated: 4 January 2008

8 August 2007: Changed install program to use APPDATA instead of ProgramFiles directory. Fixed problem with InformacionAduanera element in DTD file.
6 August 2007: First published FirmaSAT version 1.0.0.0.