CryptoSys Home > FirmaSAT > Java Interface

Java Interface to FirmaSAT

The Java Interface to FirmaSAT provides an interface for Java programmers to use FirmaSAT for Windows.

2015-01-13:

New version 7.0.j0 released. Works with FirmaSAT version 7.0.0 and above* [* see Remarks below].

Using the Interface

Import the Java package net.cryptosys.firmasat into your program

import net.cryptosys.firmasat.*;

and use the Java methods described in the documentation. These are virtually the same as the .NET methods but with Java-style camelCase method names instead of PascalCase names,

Example

Given a base XML Comprobante file ejemplo_v32-base2012.xml, sign it using a password-encrypted private key and matching X.509 certificate file.

import net.cryptosys.firmasat.*;

public final class FirmasatSign {   
    public static void main(String[] args) {
        int n;
        String s;
        String fname, newname;
        String certfile, keyfile, password;
              
        System.out.println("\nSIGN AN XML FILE:");
        fname = "ejemplo_v32-base2012.xml";  // REQUIRED INPUT FILE IN CWD
        newname = "ejemplo_v32-new_signed.xml";
        keyfile = "emisor.key";
        password = "12345678a";   /* CAUTION: DO NOT HARD-CODE REAL PASSWORDS! */
        certfile = "emisor.cer";
        n = Sat.signXml(newname, fname, keyfile, password, certfile);
        System.out.println("Sat.signXml('"+fname+"'-->'"+newname+"') returns "+n);
        assert n == 0 : "Sat.signXml failed";
        // Did we make a valid XML file?
        n = Sat.validateXml(newname);
        System.out.println("Sat.validateXml('"+newname+"') returns "+n);
        assert n == 0 : "Sat.validateXml failed";		
        // ...	
    }
}

The base XML document has empty fields for the `sello`, `certificado` and `noCertificado` attributes, which are filled in by the program. Both the methods Sat.signXml() and Sat.validateXml() return zero on success, or a negative error code if they failed. Use General.errorLookup(int errCode) to lookup the message for the error code and use General.lastError() to retrieve a more detailed error message about the problem.

The Sat.validateXml() method just validates that the XML document has a valid XML structure. To verify the signature itself, use Sat.verifySignature(). This confirms that the `sello` was indeed created by the owner of the X.509 in the `certificado` field.

        System.out.println("\nVERIFY A SIGNATURE IN AN XML FILE:");       
        fname = newname;
        n = Sat.verifySignature(fname);
        System.out.println("Sat.verifySignature('"+fname+"') returns "+n);
        assert n == 0 :  "Sat.verifySignature failed";

We can generate the complete "piped string" (cadena original) and its SHA-1 digest.

        System.out.println("\nFORM THE PIPESTRING FROM AN XML FILE:");
        fname ="ejemplo_v32-base2012.xml";
        s = Sat.makePipeStringFromXml(fname);
        System.out.println("Sat.makePipeStringFromXml('"+fname+"')=\n" + s);
        assert s.length() > 0 : "Sat.makePipeStringFromXml failed";
        
        System.out.println("\nFORM THE DIGEST OF THE PIPESTRING IN AN XML FILE:");
        s = Sat.makeDigestFromXml(fname);
        System.out.println("Sat.makeDigestFromXml('"+ fname+"')=\n"+ s);
        assert s.length() > 0 : "Sat.makeDigestFromXml failed";

The above Java code is in FirmasatSign.java. For a more complete set of tests, see More Advanced Tests.

How to setup the Java package `net.cryptosys.firmasat`

The Java package net.cryptosys.firmasat uses the Java Native Interface (jna.jar) to provide access to the functions in the core diFirmaSAT2.dll library. It currently only works on Windows. All the methods in net.cryptosys.firmasat are static, intended to be called directly in a one-off manner.

You must have installed version 7.0 or later of FirmaSAT for Windows on your system. A fully-functional trial edition is available here.
Extract the file firmasat.jar from the download section below.
Download the latest version of jna.jar from the Java Native Interface site or use this [jna-4.1.0.jar - mirrored copy].

You want the file `jna-X.X.X.jar` (about 900 kB). Rename this as `jna.jar` and put in the same directory as `firmasat.jar`. If you have downloaded the full `jna-master.zip` file (about 50 MB), extract the `jna.jar` file from the directory `jna-master\dist\`.
Ensure the files firmasat.jar and jna.jar are in your codepath. By default, firmasat.jar will look in the current working directory for the file jna.jar, which does not need to be explicitly imported.
A simple "Hello World" Java program to test it works is FirmasatSimple.java
```
/* FirmasatSimple.java */

import net.cryptosys.firmasat.*;

public class FirmasatSimple {
    public static void main(String[] args) { 
        int n = General.version();
        System.out.println("General.version()=" + n);
    }
}
```
This should output something similar to this (depending on which version of FirmaSAT you have installed):
```
General.version()=70000
```
To compile and run on the command line, put `FirmasatSimple.java`, `firmasat.jar` and `jna.jar` in the current directory:
```
javac -cp firmasat.jar FirmasatSimple.java
java -cp .;firmasat.jar FirmasatSimple
```
To get accented characters to display correctly on the Windows console you may need to change the console font and code page. You probably want code page 1252.

More advanced tests

For more advanced tests, run the TestFirmaSAT.java program along with the test files in `FirmaSATtestfiles.zip` (in the download).

The TestFirmaSAT class carries out a series of tests using the methods in the `net.cryptosys.firmasat` package. There is at least one test for each method in the package, including some obscure edge cases that you may not need. The output should look something like this.

Download

Version 7.0.j0

firmasat.zip

Contents:

firmasat.jar
TestFirmaSAT.java
FirmasatSimple.java
FirmaSATtestfiles.zip
javadoc.zip
README

Documentation

Read the Javadoc for the net.cryptosys.firmasat package.

Remarks

2016-07-29: Support for the MD5 message digest option Sat.HashAlgorithm.Md5 has been removed in Version 7.3.10. This has not been relevant since the year 2010 and so we doubt this will cause too much inconvenience. If used it will result in ERROR CODE 19: Algorithm or version not supported/Algoritmo o la version no soportada (NOT_SUPPORTED_ERROR).

Source Code

The Java source code for the interface is in this zip file. The net.cryptosys.firmasat package was developed using the Oracle JDK version 7 and DrJava.

Contact

To comment on this page, make a suggestion for improvement, or just to say you liked it, please send us a message.

This page first published 27 June 2014. Last updated 15 August 2025.