Introduction

The Gazelle project entitled Gazelle-Security-Suite (alias GSS) gathers the following tools used for the testing of IHE ATNA integration profile:

• 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
• The Syslog Collector to validate SYSLOG protocol implementation
• A model-based validation service for validating Audit Messages
• A model-based validation service for validating XUA assertions
• 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 (https://gazelle.ihe.net/content/license). Sources are available via git at https://gitlab.inria.fr/gazelle/applications/mixed/gazelle-atna.git.

The latest public packaged release can be downloaded from our Sonatype Nexus repository https://gazelle.ihe.net/nexus/index.html#nexus-search;quick~gazelle-atna-ear (search for gazelle-atna-X.X.X-gss.ear).

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

If you need for any reason a more recent version (hotfix, experimental feature…), The public packaged application of our development trunk can be found at https://gazelle.ihe.net/jenkins/job/gazelle-atna/ws/gazelle-atna-ear/target/gazelle-gss.ear. This package can be unstable.

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 Gazelle Security Suite is already installed in your environment and you are looking for the update process, jump to the next section Update from a previous version.

Bouncycastle

Bouncycastle, as a security library, is very sensible to the classloader. This library is prepared during GSS build and available from our Nexus repository https://gazelle.ihe.net/nexus/index.html#nexus-search;quick~gazelle-atna-ear (search for gazelle-atna-X.X.X-lib.zip)

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

1. Unzip the dowloaded archive

2. Create the followings directories in the JBoss 7 installation : ${JBOSS_HOME}/modules/org/bouncycastle/main/

3. Copy the bcprov jar and module.xml files into ${JBOSS_HOME}/modules/org/bouncycastle/main/

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 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. Download the SQL scripts archive from our Nexus repository https://gazelle.ihe.net/nexus/index.html#nexus-search;quick~gazelle-atna-ear (search for gazelle-atna-X.X.X-sql.zip)

2. Unzip the archive into a folder named gss-sql

3. Connect to your database

   psql -U gazelle
   

4. Execute the SQL statement to create the database.

   CREATE DATABASE gss OWNER gazelle ENCODING UTF8 ;
   

5. From the bash, create the schema by running :

   psql -U gazelle gss < gss-sql/schema.sql
   

6. Initialize database by running :

   psql -U gazelle gss < gss-sql/init.sql
   

7. You don’t need those SQL scripts any more, you can delete the archive and the folder /gss-sql.

Deployment

To deploy Gazelle Security Suite :

1. Paste the archive gazelle-gss.ear in the JBoss deployment directory ${JBOSS7\_HOME}/standalone/deployments/

2. Display JBoss server logs, start JBoss and wait for ear deployment.

3. The application can be browsed at http://localhost:8080/gss or http://localhost:8080/gss-dev, depending on the compilation profile (Public or dev).
   Port could also be different whether you have modified the JBoss configuration.

Data storage

GSS need 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

Syslog directory

Syslog needs some configuration files installed on the same machine GSS is running.

1. Create a directory

   sudo mkdir /opt/syslog
   

2. Download the syslog archive from our Nexus repository https://gazelle.ihe.net/nexus/index.html#nexus-search;quick~gazelle-atna-ear (search for gazelle-atna-X.X.X-syslog.zip)

3. Unzip the archive and copy every files into /opt/syslog

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

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

Update from a previous version

The update mechanism has 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

Reminder: Before version 5.0.0, Gazelle Security Suite was called Gazelle-ATNA-Tools.

1. Download the new ear and its associated update SQL script from our Nexus repository https://gazelle.ihe.net/nexus/index.html#nexus-search;quick~gazelle-atna-ear (search for gazelle-atna-X.X.X-gss.ear and gazelle-atna-X.X.X-sql.zip). Not each version has an update sql to execute.

2. Undeploy the old ear from JBoss by removing it from the deployment directory.

3. Backup your database

4. Unzip the SQL archive

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

6. Deploy the new ear

7. Execute SQL statements 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, 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 version GSS 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://gitlab.inria.fr/gazelle/applications/mixed/gazelle-atna/tree/master/gazelle-atna-ear/src/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

Application can be configured directly from the web interface. From the menu, go to Administration > Application preferences (you need to be logged in as admin_role).

GSS Double Central Authentication Service

Basicaly one Gazelle Central Authentication Service provide 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 concatenate 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.

There is two files that need to be created in /opt/gazelle/cas :

• file.properties : This is the configuration file for the main cas, used in all the other tools. It should be already present.
• file_second_cas.properties : This is the configuration file for the second cas.

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 request
• Certificates creation from participants table (CSV format)

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 ways 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 provide certificates for testing purpose only, they must not be valid outside of this context.

List of properties