AntTargetsUsage_en

Using j4sign ant targets

Vai alla Versione Italiana

j4sign source distribution (j4sign-x.y.z-src.zip) contains a "build.xml" file for simplifying and automating several tasks, even much more complex than mere code building. Ant is the tool used for that. Using Ant is simple: change to the directory containing "build.xml", and call the "ant" command. In that way you implicitly call the "Default Task" defined in build.xml. In j4sign case it is the "dist.bin" task, that builds the binary distribution "j4sign-x.y.z-bin.zip".

Some properties inside j4sign's build.xml are to be set, or defined in an external file ("properties file"). We will see a properties file example, and how to use it in combination with the ant task for compiling and signing the PKCS11SignApplet applet.

Create "j4sign.build.properties" properties file.

Create a "j4sign.build.properties" file containing the following:

ext.installer.hostandport=https://www.example.com
ext.installer.webcontext=j4sign
applet-pkcs11.referencing.hosts=http://localhost http://127.0.0.1 *.my.fqdn
servlet.api.jar=/home/myuser/tomcat6/lib/servlet-api.jar
javaplugin.api.jar=/usr/lib/jvm/java-7-openjdk/jre/lib/plugin.jar
keystore=/home/myuser/.keystore.swsign
keystore.pass=mystorepass
signer.alias=swsign-rsa
signer.pass=mysignerpass

Here follows a description of the properties meaning:

1. ext.installer.hostandport: is the url of the host from which you will distribute the signature applet and the extension the applet depends upon. Please note that the applet can be placed in a central location, and several web applications can reference it via a .jnlp file, without the need to embed it; see the firma-digitale web application. The .jnlp file can itself be placed centrally, along with the applet and extension jars.
2. ext.installer.webcontext: it's the relative path that with ext.installer.hostandport composes the url location of applet and estension.
3. applet-pkcs11.referencing.hosts: is the space separated list of the hosts which is permitted to reference the applet without javaplugin raises exceptions or warnings. Ideally the applet will be present at: ${ext.installer.hostandport}/${ext.installer.webcontext} (https://www.example.com/j4sign in this example), and the various web application using it will have to be covered by the list. For instance an hypothetical firma.my.fqdn host will be covered, thanks to the wildcard in *.my.fqdn. This permits to control repurposing of the applet, limiting its usage to the preferred scope.
4. servlet.api.jar: local path of the servlet api implementation.
5. javaplugin.api.jar: local path of the javaplugin api (used in the applet code running in the jvm for invoking javascript code running in the browser).
6. keystore: the location of the code signing java keystore, as described in How to create a keystore for j4sign code signing (Values set in this example are the same used in that page).
7. keystore.pass: password to access keystore.
8. signer.alias: keystore item containing keys and certificates for code signing.
9. signer.pass: password to access the private key in signer.alias.

Executing the desired target

Go inside the root of j4sign source distribution. For example, if you extracted it in your home directory:

cd ~/j4sign-0.1.3-src

Then call Ant, passing properties file (let's assume it is placed in your home dir as well) and the desired task name; if you wanto compile and sign PKCS11SignApplet:

ant -propertyfile ~/j4sign.build.properties jar.applet-pkcs11

At the end of a successful build, you will find inside build/applet-pkcs11 folder the PKCS11SignApplet-signed.jar signed jar file containing the applet.

The applet dipends from a "SmartCardAccess" java extension.
The extension is automatically installed at first run of the applet, using the SmartCardAccessInstaller-signed.jar installer. The applet finds the installer at the location configured in the properties: ${ext.installer.hostandport}/${ext.installer.webcontext}. For building the installer run:

ant -propertyfile ~/j4sign.build.properties jar.ext.installer

Note: from j4sign-0.1.5 this target is a dependency of "jar.applet-pkcs11"; no need to run it separately.

In build/ext you will find SmartCardAccessInstaller-signed.jar that has to be accessible from ${ext.installer.hostandport}/${ext.installer.webcontext}. The applet jar as well will be available from the same location, so, in this example:

https://www.example.com/j4sign/PKCS11SignApplet-signed.jar
https://www.example.com/j4sign/SmartCardAccessInstaller-signed.jar