Installing Certificate Authorities (CAs)¶
The certificate authorities (CAs) provide the trust roots for the public key infrastructure OSG uses to maintain integrity of its sites and services. This document provides details of various options to install the Certificate Authority (CA) certificates and have up-to-date certificate revocation lists (CRLs) on your OSG hosts.
We provide three options for installing CA certificates that offer varying levels of control:
- Install an RPM for a specific set of CA certificates (default)
osg-ca-scripts, a set of scripts that provide fine-grained CA management
- Install an RPM that doesn't install any CAs. This is useful if you'd like to manage CAs yourself while satisfying RPM dependencies.
Prior to following the instructions on this page, you must enable our yum repositories
Installing CA Certificates¶
Please choose one of the three options to install CA certificates.
Option 1: Install an RPM for a specific set of CA certificates¶
This option is the default if you install OSG software without pre-installing CAs.
yum install osg-ce will bring in
osg-ca-certs by default.
In the OSG repositories, you will find two different sets of predefined CA certificates:
- (default) The OSG CA certificates. This is similar to the IGTF set but may have a small number of additions or deletions
- The IGTF CA certificates
See this page for details of the contents of the OSG CA package.
|If you chose...||Then run the following command...|
|OSG CA certificates||
|IGTF CA certificates||
To automatically keep your RPM installation of CAs up to date, we recommend the OSG CA certificates updater service.
Option 2: Install osg-ca-scripts¶
osg-ca-scripts package provides scripts to install and update predefined sets of CAs with the ability to add or remove specific CAs.
- The OSG CA certificates. This is similar to the IGTF set but may have a small number of additions or deletions
- The IGTF CA certificates
See this page for details of the contents of the OSG CA package.
root@host # yum install osg-ca-scripts
Choose and install the CA certificate set:
If you choose... Then run the following command... OSG CA certificates
osg-ca-manage setupCA --location root --url osg
IGTF CA certificates
osg-ca-manage setupCA --location root --url igtf
osg-update-certs-cronservice to enable periodic CA updates. As a reminder, here are common service commands (all run as
To... Run the command... Start a service
systemctl start <SERVICE-NAME>
Stop a service
systemctl stop <SERVICE-NAME>
Enable a service to start on boot
systemctl enable <SERVICE-NAME>
Disable a service from starting on boot
systemctl disable <SERVICE-NAME>
(Optional) To add a new CA:
osg-ca-manage add [--dir <local_dir>] --hash <CA-HASH>
(Optional) To remove a CA
osg-ca-manage remove --hash <CA-HASH>
A complete set of options available though
osg-ca-manage command, can be found in the osg-ca-manage documentation
Option 3: Site-managed CAs¶
If you want to handle the list of CAs completely internally to your site, you can utilize the
empty-ca-certs RPM to satisfy
RPM dependencies while not actually installing any CAs. To install this RPM, run the following command:
root@host # yum install empty-ca-certs –-enablerepo=osg-empty
If you choose this option, you are responsible for installing and maintaining the CA certificates. They must be installed in
/etc/grid-security/certificates, or a symlink must be made from that location to the directory that contains the CA certificates.
Installing other CAs¶
In addition to the above CAs, you can install other CAs via RPM. These only work with the RPMs that provide CAs (that is,
osg-ca-certs and the like, but not
osg-ca-scripts.) They are in addition to the above RPMs, so do not only install these extra CAs.
|Set of CAs||RPM name||Installation command (as root)|
Verifying CA Certificates¶
After installing or updating the CA certificates, they can be verified with the following command:
root@host # curl --cacert <CA FILE> \ --capath <CA DIRECTORY> \ -o /dev/null \ https://gracc.opensciencegrid.org \ && echo "CA certificate installation verified"
<CA FILE> is the path to a valid X.509 CA certificate and
<CA DIRECTORY> is the path to the directory
containing the installed CA certificates.
For example, the following command can be used to verify a default OSG CA certificate installation:
root@host # curl --cacert /etc/grid-security/certificates/cilogon-osg.pem \ --capath /etc/grid-security/certificates/ \ -o /dev/null \ https://gracc.opensciencegrid.org \ && echo "CA certificate installation verified" % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 22005 0 22005 0 0 86633 0 --:--:-- --:--:-- --:--:-- 499k CA certificate installation verified
If you do not see
CA certificate installation verified this means that your CA certificate installation is broken.
First, ensure that your CA installation is up-to-date and if you continue to see issues please contact us.
Keeping CA Certificates Up-to-date¶
It is important to keep CA certificates up-to-date for services and their clients to maintain integrity of production services. To verify that your CA certificates are on the latest version on a given host, determine the most recently released versions and the method by which your CA certificates have been installed:
Determine which of the three CA certificate installation methods you are using:
# rpm -q igtf-ca-certs osg-ca-certs osg-ca-scripts empty-ca-certs
Based on which package is installed from the output in the previous step, choose one of the following options:
osg-ca-certsis installed, compare the installed version from step 2 to the corresponding version from step 1.
If the version is older than the corresponding version from step 1, continue onto option 1 to upgrade your current installation and keep your installation up-to-date.
If the versions match, your CA certificates are up-to-date!
osg-ca-scriptsis installed, run the following command to update your CA certificates:
# osg-ca-manage refreshCA
And continue to the instructions in option 2 to enable automatic updates of your CA certificates.
empty-ca-scriptsis installed, then you are responsible for maintaining your own CA certificates as outlined in option 3.
If none of the packages are installed, your host likely does not need CA certificates and you are done.
Managing Certificate Revocation Lists¶
In addition to CA certificates, you must have updated Certificate Revocation Lists (CRLs). CRLs contain certificate blacklists that OSG software uses to ensure that your hosts are only talking to valid clients or servers. To maintain up to date CAs, you will need to run the
fetch-crl is installed when you install the rest of the software and you do not need to explicitly install it.
If you do wish to install it manually, run the following command:
root@host # yum install fetch-crl
If you do not wish to change the frequency of
fetch-crl updates (default: every 6 hours) or use syslog for
skip to the service management section
The following sub-sections contain optional configuration instructions.
Note that the
nosymlinks option in the configuration files refers to ignoring links within the certificates directory (e.g. two different names for the same file). It is perfectly fine if the path of the CA certificates directory itself (
infodir) is a link to a directory.
Changing the frequency of
To modify the times that
fetch-crl-cron runs, edit
Logging with syslog¶
fetch-crl can produce quite a bit of output when run in verbose mode. To send
fetch-crl output to syslog, use the following instructions:
Change the configuration file to enable syslog:
logmode = syslog syslogfacility = daemon
Make sure the file
/var/log/daemonexists, e.g. touching the file
/etc/logrotate.dfiles to rotate it
fetch-crl is installed as two different system services. The fetch-crl-boot service runs
fetch-crl and is intended to only be enabled or disabled. The
fetch-crl-cron service runs
fetch-crl every 6 hours (with a random sleep time included). Both services are disabled by default. At the very minimum, the
fetch-crl-cron service needs to be enabled and started, otherwise services will begin to fail as existing CRLs expire.
Start the services in the order listed and stop them in reverse order. As a reminder, here are common service commands (all run as
|To...||Run the command...|
|Start a service||
|Stop a service||
|Enable a service to start on boot||
|Disable a service from starting on boot||
To get assistance, please use the this page.
Some guides on X.509 certificates:
- Useful commands: http://security.ncsa.illinois.edu/research/grid-howtos/usefulopenssl.html
- Install GSI authentication on a server: http://security.ncsa.illinois.edu/research/wssec/gsihttps/
- Certificates how-to: http://www.nordugrid.org/documents/certificate_howto.html
See this page for examples of verifying certificates.
|All CA Packages||CA File Location||
|All CA Packages||Index files||
||Latest version also available at http://repo.opensciencegrid.org/cadist/|
|All CA Packages||Change Log||
||Latest version also available at http://repo.opensciencegrid.org/cadist/CHANGES|
|osg-ca-certs or igtf-ca-certs||contain only CA files|
|osg-ca-scripts||Configuration File for osg-update-certs||
||This file may be edited by hand, though it is recommended to use osg-ca-manage to set configuration parameters.|
The index and change log files contain a summary of all the CA distributed and their version.
|osg-ca-scripts||Log file of osg-update-certs||
|osg-ca-scripts||Stdout of osg-update-certs||
|osg-ca-scripts||Stdout of osg-ca-manage||
|osg-ca-scripts||Stdout of initial CA setup||