Creating a Trust Fabric Certificate Authority

[ GTS: Administrators Guide | Developers Guide | caGrid: Documentation Guides ]

	Contents Step 1: Install caGrid/GTS Install Prerequisites for the caGrid 1.4 Installer Install caGrid using the caGrid 1.4 Installer Step 2: Bootstrap the Trust Fabric Step 3: Configure Globus to Trust the Certificate Authority

This guide explains how to install caGrid and create the trust fabric certificate authority as part of the installation of a new grid.

This Page is Part of a Multi-Page Set of Directions The instructions on this page are intended to be used a part of the instructions for installing a new grid that start on the Grid Installation Guide.

All of the steps described on this page should be performed on the same host VM that will host the grid's master GTS.

Step 1: Install caGrid/GTS

In this step you download and install caGrid using the caGrid Installer. If you have already installed caGrid 1.4, proceed to the next step.

What immediately follows this paragraph is a standard set of instructions for installing caGrid. When you get to the part with the installer asks you to select a target grid, you can save some time by selecting No Target Grid rather than the training grid that is suggested.

Install Prerequisites for the caGrid 1.4 Installer

The caGrid Installer will install all prerequisites except for Java and MySQL.

• Sun/Oracle Java 6 JDK
• (Optional) If you are deploying caGrid core services locally, you may also need a MySQL database.
  • NOTE: MySQL is only required for the security services and GME. You can use 4.x (with transaction enabled; i.e., use InnoDB engine) or 5.x.
• Make sure the JAVA_HOME environment variable is set and points to the correct respective location.

Install caGrid using the caGrid 1.4 Installer

Installer Prerequisites

The caGrid Installer installs all prerequisites except for Java and MySQL.

• Java 6 JDK
  • Make sure the JAVA_HOME environment variable is set and points to the location where the JDK has been installed.
• (Optional) If you are deploying caGrid core services locally, you may also need a MySQL database.

  Note MySQL is only required for the security services and GME. You can use 4.x (with transaction enabled; i.e., use InnoDB engine) or 5.x.

Installing caGrid 1.4 Using the Installer

Internet Resources Required by the Installer Unless you are using a customized installer, the installer will need to be able to access these internet resources: http://gforge.nci.nih.gov to download caGrid and Globus http://archive.apache.org to download ant and tomcat (if you create a tomcat container) http://downloads.sourceforge.net to download JBoss if you create a JBoss container. https://ncisvn.nci.nih.gov to download the default installer properties and configuration file

1. Download the caGrid 1.4 Installer, unless you have a customized installer that you have been instructed to use for your grid. The downloaded installer should be contained in the file caGrid-installer-1.4.zip. If you are using a customized installer the name may vary.
   
   
2. Unzip the file caGrid-installer-1.4.zip. This creates the directory caGrid-installer-1.4. This documentation refers to this directory as CAGRID_INSTALLER_LOCATION.
   
   
3. From a command prompt, launch the installer using the following command:

   Do not launch the installer by double-clicking the jar file

   

    > cd *CAGRID_INSTALLER_LOCATION*
   
   > java -jar caGrid-installer-1.4.jar 

4. Select the I agree to this license checkbox and then click  Next.
5. Select the Install/Configure caGrid Software checkbox and then click  Next.
6. The installer detects whether or not you have already installed Ant. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Ant.
   
   
7. The installer detects whether or not you have already installed Globus. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Globus.
   
   
8. The installer asks you for a location on your local file system to install caGrid. Specify a location to install caGrid and click  Next.

   To select a file location that is not in the User's Home directory, Click the Look In: drop down list and select a new starting location.
9. The installer displays a list of tasks that the installer will perform. Click  Next to begin the installation process. At this time the installer downloads, builds, and installs several components. This process takes several minutes.
   
   
10. Once the installer has completed installing all the components, click  Next.
    
    
11. The installer prompts you to specify which Grid you want to configure your installation to use. The installer supports configuring caGrid to work out of the box with many community Grid environments. For testing and development purposes, we recommend selecting the Training Grid. If you do not want to configure caGrid to work with an existing Grid you may select that as well. The installer can also be modified to support additional Grids.
12. The installer shows a summary of the tasks to be completed. Click  Next to configure caGrid to use the selected target Grids. This process takes several minutes.
    
    
13. Once the installer has finished configuring caGrid to use the target Grid, click  Next. The final screen reminds you to set your ANT_HOME and GLOBUS_LOCATION environment variables. Set these variables immediately and click Finish.

Congratulations! You have successfully installed caGrid.

Add ANT_HOME/bin to PATH You will be running the ant program from the command line so add ANT_HOME/bin to PATH.

• The installer installs caGrid to the directory you specified during installation. From this point on we refer to this directory as CAGRID_HOME.
  
• You can find the GTS in the directory CAGRID_HOME/projects/gts; from this point on we refer to this directory as GTS_HOME.

• The GAARDS UI (user interface) for administrating the GTS is located in CAGRID_HOME/projects/gaardsui; from this point on we refer to this directory as GAARDS_UI_HOME.

Step 2: Bootstrap the Trust Fabric

Deployments that leverage the GTS to maintain the trust fabric are effectively delegating their authentication responsibility to the GTS. Therefore it is imperative the GTS instance(s) can be trusted. In order for the GTS to be trusted it must run securely with a host credential (X.509 certificate and private key). It is critical that this host credential be issued by an authority that all parties in the deployment trust.  This certificate authority will be the trust anchor of the entire trust fabric and will be the certificate authority that all parties trust in order to bootstrap the entire trust fabric.

It is EXTREMELY IMPORTANT that this certificate authority be highly secured. If it were to be compromised parties trusting it could be convinced to trust certificate authorities that would not otherwise be trusted.

Although it is not required, we recommend that you use a separate certificate authority for issuing host credentials to GTS instance(s). For the purposes of this guide we create a certificate authority that we will use for issuing credentials to GTS instances.

To create a certificate authority please complete the following steps from a command line:

#Create a directory to contain the CA's certificate and key files. For the purposes of these directions, we will assume that this directory is /home/gridAdmin/certificates.

1. Type cd GTS_HOME.
   
   
2. Type ant generateCA.
   
   
3. Enter the distinguished name (DN) for the CA. The name that you enter should follow the pattern
   O=[GRID_NAME],OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA
   where [GRID_NAME] is the one-word name for your grid. For example, if the grid name is "abc", then the distinguished name should be
   O=abc,OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA
   
   
4. Enter the number of days that the CA will be valid for (i.e 3650).
   
   
5. Enter a password which will be used to encrypt the CA's private key. Be sure to make a note of the password as it will be needed later.

   The password should be 13 characters long.

   
   

6. Enter a file to write the CA private key to. We will assume that you enter
   /home/gridAdmin/certificates/trustca-key.pem

   No White Space Be careful not to enter any leading or trailing white space (blankes, tabs, ...)

   
   
   

7. Enter a file to write the CA certificate to. We will assume that you enter
   /home/gridAdmin/certificates/trustca-cert.pem

Sample output from executing the above steps is shown below:

ant generateCA
Buildfile: build.xml

setGlobus:

checkGlobus:
     [echo] Globus: /home/gridAdmin/ext/ws-core-4.0.3

defineClasspaths:

defineExtendedClasspaths: 

init: 

checkValidate:

preInit:

configure:
     [copy] Copying 1 file to /home/gridAdmin/releases/caGrid-1.3/projects/gts

postInit: generateCA:
     [input] Please enter the DN for the new CA (ex. O=osu,OU=bmi,CN=Some CA):
O=abc,OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA
     [input] Please enter the number of days the new CA will be valid for:
3650
     [input] Please enter a password for the new CA:
LPM23sdf_en123
     [input] Please enter a location to write the new CA's private key:
/home/gridAdmin/certificates/trustca-key.pem
     [input] Please enter a location to write the new CA's certificate:
/home/gridAdmin/certificates/trustca-cert.pem
     [java] Successfully created the CA certificate:
     [java] O=abc,OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA
     [java] CA certificate valid till:
     [java] Thu Feb 14 15:06:56 EST 2019 \[java\] CA private key written to:
     [java] /home/gridAdmin/certificates/trustca-key.pem
     [java] CA certificate written to:
     [java] /home/gridAdmin/certificates/trustca-cert.pem

BUILD SUCCESSFUL
 Total time: 1 minute 44 seconds

Be sure to note down the location that your CA certificate and private key were written to, from this point forward we will refer to thesse locations as TRUST_CA_CERTIFICATE and TRUST_CA_KEY respectively.  Also be sure to note down that password you entered for your private key.  Finally be sure to take note of the distiguished name or subject you entered for your CA, from this point forward we will refer to this as the CA_SUBJECT.

Now that we have created a trust fabric certificate authority we can use it to issue host credentials for GTS instances. To create host credentials please complete the following steps from a command prompt(illustrated below):

1. Type cd GTS_HOME.
   
   
2. Type ant createAndSignHostCertificate.
   
   
3. Enter the location of the CA's private key (TRUST_CA_KEY).
   
   
4. Enter the password used to encrypt the CA's private key.
   
   
5. Enter the location of the CA's certificate (TRUST_CA_CERTIFICATE).
   
   
6. Enter the name of the host. For example, mastergts.abc.example.org.

   Use of the fully qualified hostname is highly recommended.

   
   
   

7. Enter the number of days that the host credentials should be valid for (i.e 3620).

   The number of days entered must allow the host certificate to expire before the CA's certificate.

   
   
   

8. Enter a location to which to write the host private key. The location you enter should follow this pattern:
   HOME/.cagrid/certficates/hostName-key.pem
   Where HOME is your home directory and hostName is the host name you entered previously. For example if HOME is /home/gridAdmin and the host name is mastergts.abc.example.org, then you should enter
   /home/gridAdmin/.cagrid/certificates/mastergts.abc.example.org-key.pem
   
   
9. Enter a location to which to write the host certificate. The location you enter should follow this pattern:
   HOME/.cagrid/certficates/hostName-cert.pem
   Where HOME is your home directory and hostName is the host name you entered previously. For example if HOME is /home/gridAdmin and the host name is mastergts.abc.example.org, then you should enter
   /home/gridAdmin/.cagrid/certificates/mastergts.abc.example.org-cert.pem

Sample output from executing the above steps is shown below:

$ ant createAndSignHostCertificate 
Buildfile: build.xml 
setGlobus: 
checkGlobus: 
[echo] Globus: /home/gridAdmin/ws-core-4.0.3 
defineClasspaths: 
defineExtendedClasspaths: 
init: checkValidate: 
preInit: 
configure: 
[copy] Copying 1 file to /home/gridAdmin/caGrid-1.3/projects/gts 
postInit: 
createAndSignHostCertificate: 
[input] Please enter the location of the CA's private key: 
/home/gridAdmin/certificates/trustca-key.pem 
[input] Please enter the CA's password: d3DM^si_1MBd
[input] Please enter the location of the CA's certificate: /home/gridAdmin/certificates/trustca-cert.pem 
[input] Please enter the Hostname [mastergts.abc.example.org]: [mastergts.abc.example.org] 
llanowar 
[input] Please enter the number of days the host certificate will be valid for: 
1000 
[input]Please enter a location to write the host key:
/home/gridAdmin/.cagrid/certificates/mastergts.abc.example.org-key.pem
[input] Please enter a location to write the host certificate: 
/home/gridAdmin/.cagrid/certificates/mastergts.abc.example.org-cert.pem
[java] 
Successfully created the host certificate: 
[java] O=abc,OU=GTS,OU=Trust Fabric,CN=host/mastergts.abc.example.org 
[java] Host certificate issued by: 
[java] O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=Trust Fabric CA 
[java] Host certificate valid till: [java] Sun Nov 13 15:42:32 EST 2011 
[java] Host private key written to: 
[java] /home/gridAdmin/.cagrid/certificates/mastergts.abc.example.org-key.pem 
[java] Host certificate written to: 
[java] /home/gridAdmin/.cagrid/certificates/mastergts.abc.example.org-cert.pem 

BUILD SUCCESSFUL
 Total time: 1 minute 44 seconds

Make a copy of the directory that contains the host certificate and key files. You will need this copy to restore the files if they are corrupted.

Note down the location to which the host certificate and private key were written. You will need these later to configure your container. Also be sure to note the location of the copied directory.

Step 3: Configure Globus to Trust the Certificate Authority

In order for the GTS to be used to distribute trust certificate authorities we MUST configure Globus to trust the CA that issued the GTS's host certificate. To do this we place a copy of the certificate authority certificate (TRUST_CA_CERTIFICATE) in the Globus trusted certificates directory.

In most installations the Globus trusted certificate directory is usually USER_HOME/.globus/certificates. Globus requires all CA certificates in its trusted certificates directory to be in PEM format and to have a digit extension (0-9). For example, if the CA certificate is stored in the file cacert.pem we would configure Globus to trust this certificate authority by copying to the directory USER_HOME/.globus/certificates (create directory if needed) with the file name cacert.0

1. Locate the CA certificate file that you created in Step 2
2. Copy the file into the USER_HOME/.globus/certificates directory as cacert.0
   1. Unix Location: usually /home/<username>/.globus/certificates
   2. Windows: usually C:\Documents and Settings\<username>\.globus\certificates
   3. Mac: usually /Users/<username>/.globus/certificates