Warning: This documentation is out-dated, newest version of the documentation is available at https://gazelle.ihe.net/gazelle-documentation/Gazelle-Security-Suite/installation.html

The Gazelle project entitled Gazelle-Security-Suite (alias GSS) gathers the following tools used in the context of the security profile IHE ATNA :

• Gazelle PKI to generate and share certificates for testing purposes
• ATNA Questionnaire used to collect security properties of systems under test
• Gazelle TLS to test implementation of secured connections
• A model-based validation service for validating Audit Messages
• A model-based validation service for validating XUA assertions
• And a Certificate validator.

Since version 5.0.0 the tool is called Gazelle-Security-Suite and run on JBoss 7. It was prior called Gazelle ATNA Tools and ran on JBoss 5. The main title has changed, but a lot of modules have kept the old name, so do not be surprise to find both names in code sources.

Sources & binaries

Gazelle-Security-Suite is an open-source project under Apache License Version 2.0. Sources are available via Subversion at https://scm.gforge.inria.fr/anonscm/svn/gazelle/Maven/gazelle-atna/.

The public packaged application of our development trunk can be found here. If you prefer a more stable version, the latest release can be downloaded from our Sonatype Nexus repository (search for gazelle-atna-ear).

If you download the ear from Nexus it will have a name such as gazelle-atna-ear-4.7.12-tls.ear or gazelle-atna-ear-5.0.0-gss.ear, then be sure to rename it to gazelle-tls.ear or gazelle-gss.ear otherwise the deployment will fail.

Installation

If you are installing a Gazelle tool for the first time in your environment, make sure to read carefully the general considerations for JBoss7.

If your are installing a version of GSS prior to 5.0.0, you will have to set up a JBoss 5 application server instead.

Bouncycastle

Bouncycastle, as a security library, is very sensible to the classloader. This library is prepared during GSS build and available here (Jenkins workspace). Depending on which version of JBoss GSS is running, the installation differs.

Bouncycastle with JBoss 7 :

bcprov library must be installed as a module of the application server.

1. Create the followings directories in the JBoss 7 installation : ${JBOSS_HOME}/modules/org/bouncycastle/main/
2. Copy the bcprov jar into ${JBOSS_HOME}/modules/org/bouncycastle/main/
3. Create a file named modules.xml into ${JBOSS_HOME}/modules/org/bouncycastle/main/
4. Edit module.xml and write :

   <?xml version="1.0" encoding="UTF-8"?>
   <module xmlns="urn:jboss:module:1.1" name="org.bouncycastle">
   
       <resources>
           <resource-root path="bcprov-jdk15-1.45.jar"/>
       </resources>
   
       <dependencies>
           <module name="javax.api" slot="main" export="true"/>
       </dependencies>
   
   </module>

Bouncycastle with JBoss 5 :

• bcprov library is not in the ear, WEB-INF/lib or any directory of JBoss
• bcprov library must be unique and only in ${JBOSS_HOME}/server/${YOUR_SERVER}/lib/ (replace ${YOUR_SERVER} by the server where the ear will be deployed)

Java key length policy

The USA government restricts the allowed Java key size by default. It is needed to change the policy of the JVM if you get the error java.security.InvalidKeyException: Illegal key size.

This can be fixed by overwriting policy files in the Java runtime by those provided on the Java download page :

• Java 6 : http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html
• Java 7 : http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

Unzip The 2 files jce/US_export_policy.jar and jce/local_policy.jar and paste them into ${JAVA_HOME}/jre/lib/security/

To check whether it's working, try to create a custom certificate with a key size of 2048 once GSS is installed.

Database creation

Your database must have a user gazelle

1. Connect to your database

   psql -U gazelle

2. Execute the SQL statement to create the database.

   CREATE DATABASE tls OWNER gazelle ENCODING 'UTF-8' ;

3. For GSS 5.1.0 and younger : Download the script schema.sql associated with your GSS version. It can be found in https://scm.gforge.inria.fr/anonscm/svn/gazelle/Maven/gazelle-atna/tags/${GSS_VERSION}/gazelle-atna-ear/scr/main/sql/schema.sql. The create the schema by running:

   psql -U gazelle tls < schema.sql

Deployment

To deploy Gazelle-Security-Suite :

1. paste the archive gazelle-gss.ear in the JBoss deployment directory:
   • JBoss 7 : ${JBOSS7_HOME}/standalone/deployments/.
   • JBoss 5 : ${JBOSS5_HOME}/server/${YOUR_SERVER}/deploy/.
2. Display JBoss server logs and wait for ear deployment. Then the datatable schema must then have been created.
3. Download the script init.sql associated with your Gazelle-Security-Suite version. They can be found in https://scm.gforge.inria.fr/anonscm/svn/gazelle/Maven/gazelle-atna/tags/${GSS_VERSION}/gazelle-atna-ear/scr/main/sql/init.sql and run it to initialize the database :

   psql -U gazelle tls < init.sql

4. Except for special builds and depending of the JBoss port offset, the application can be browsed at http://localhost:8080/gss (port can be different whether you have modified the JBoss configuration).

Data storage

If the ATNA-questionnaire is enable (true by default), GSS will need a directory to record Audit Messages and validation results. By default, the application is configured to use /opt/tls/.

sudo mkdir /opt/tls

Be sure this directory can be read/written by JBoss.

sudo chmod -R 775 /opt/tls
sudo chown -R jboss:jboss-admin /opt/tls

Update from a previous version

The update mechanism changed at version 5.1.0. Be careful to strictly follow the process associated to the version you come from.

Update from version prior to GSS 5.1.0

1. Undeploy the old ear from JBoss by removing it from the deployment directory.
2. Backup your database
3. Download the new ear and its associated update SQL script. Those scripts can be found in https://scm.gforge.inria.fr/anonscm/svn/gazelle/Maven/gazelle-atna/tags/${GSS_VERSION}/gazelle-atna-ear/scr/main/sql/.. Not each version has an update sql to execute.
4. Execute SQL statements that must be run before deployment (Open the update-X.X.X.sql file with a text editor to see which one).
5. Deploy the new ear
6. Execute SQL statemnts that must be run after deployment (Open the update-X.X.X.sql file with a text editor to see which one).

Due to the update mechanism of the database (the ear is responsible for creating elements, and the update-X.X.X.sql script is responsible for updating or deleting elements), it is important to not skip any version of the application in an overall update. You cannot go directly from 4.7.4 to 4.7.12, you will have to repeat the process from 4.7.4 to 4.7.5, 4.7.6, 4.7.7 and so on.

To update Gazelle-ATNA-tools 4.7.12 to Gazelle-Security-Suite 5.0.0 the process is the same, except that the deployment of the new ear (step 5) must be done on a JBoss7 properly installed for GSS.

Update from GSS version 5.1.0 and younger

1. Undeploy the old ear from JBoss by removing it from the deployment directory.
2. Backup your database
3. Download the new ear and all intermediate update SQL scripts from your old version (excluded) to your target version (included). Those scripts can be found in https://scm.gforge.inria.fr/anonscm/svn/gazelle/Maven/gazelle-atna/tags/${GSS_VERSION}/gazelle-atna-ear/scr/main/sql/.. Not each version has an update sql to execute.
4. Execute the update SQL scripts
5. Deploy the new ear

Example (version number are hypothetical) : to update GSS from 5.1.0 to 5.1.5 you have to execute 5.1.1, 5.1.2, 5.1.3, 5.1.4 and 5.1.5 update SQL scripts, but you only have to deploy the latest gss 5.1.5 ear.

Configuration

GSS Double Central Authentication Service

Basicaly one Gazelle Central Authentication Service provides user authentication for all Gazelle applications in a test bed. However we once had the need to connect one instance of GSS with two test beds. We implemented a feature to answer this need and decide to leave the option available for public. So GSS can be connected with two distinct Authentication Services and users are identified from two databases. GSS concatenates the username and the CAS key to preserve username uniqueness all over the application. Of course the second authentication channel is optional and can be turned off.

Note that every configuration variable related to a user feature is then derivated in two versions and prefixed with main_ or second_. It allows admin to configure options and services for the first or the second test bed.

Gazelle PKI specific considerations

PKI features of GSS require to define a certificate authority (CA) for :

• Signing test participant certificate requests
• Generating Auto-Login CAS certificate requests
• Batch certificate creation

The certicate authority of the tool can be set in the administration of the application. Set the preference certificate_authority_Id to the id (primary key in database) of the Certificate of the selected CA. GSS requires that the private key of this certificate is stored in the application, otherwise it would not be possible to sign any requests.

There is several way to have a certificate authority stored into the application :

Creating a new self-signed CA

Go to Administration > Create a Certificate Authority, Fill the form and validate. This is the most recommended way.

importing an existing CA

Depending on the format go to Administration > Import p12 or Import PEM. Import also the private key.

If you import an existing CA, do not use a CA chained to an issuer publicly trusted. GSS provides certificates for testing purpose only, they must not be valid outside of this context.

List of properties