INTRODUCTION

This document describes the xsede-ca-certificates package, which is provided
as a RPM as well as tar.gz and jks.

DESCRIPTION

This xsede-ca-certificates package installs/updates the bundle of CA
certificates trusted by XSEDE.  

  RPM / Yum
  The RPM can be installed via the XSEDE production Yum repository.  If not
  already done, use the instructions below to configure and trust the XSEDE
  production repository:

  http://software.xsede.org/production/repo/repoconfig.txt

  Then install the xsede-ca-certificates packages using the following
  command:

  yum install xsede-ca-certificates 

  By default the bundle is installed to the Trusted Certificates directory (by
  default /etc/grid-security/certificates/) but the RPM is relocatable and can
  be installed to an alternate location using the --prefix to the rpm
  command and a url to the RPM, for example

  rpm -i http://software.xsede.org/production/repo/centos/6/x86_64/xsede-ca-certificates-1.0-0.noarch.rpm --prefix=/tmp/certificates

  The changelog for the RPM can always be accessed using the following command.
  
  $ rpm -q --changelog 
  
  FILES FROM RPM
  
  The files in the RPM destined for the Trusted Certificates directory are
  marked as configuration files (identified with the directive %config(noreplace)
  in the RPM spec file) subjecting these files to the standard RPM treatment of
  configurtation files such as the below.
  
  1. Any locally modified files in the Trusted Certificates directory such as
     signing policy files will be retained as they are and the ones from the
     RPM will be named with the ..rpmnew. suffix (per standard RPM
     processing). The rpm command will notify the administrator in this case and
     the administrator is expected to manually resolve any differences and delete
     the .rpmnew files after the installation of the RPM is complete.
  
  2. Any CA certificate files deleted by the administrator will be re-installed
     automatically and silently if they are part of the RPM being installed or
     updated. Any local additions of CA certificate files will be preserved and
     if also part of the RPM being installed, will henceforth be considered to be
     owned by the RPM, if they do not conflict with those from the RPM. If they
     do conflict, the versions from the RPM will be saved with the ".rpmnew"
     suffix. The administrator is expected to review the differences between the
     old file and the one that has come from the RPM (available with the ".rpmnew
     suffix) and decide if the one with the .rpmnew suffix should replace the old
     one and if so, make the change manually.

  Tar.gz / JKS

  Both the tar.gz and jks packages will continue to be available at
  http://software.xsede.org/security.  The tar.gz unzips into a directory
  called 'certificates' and can be manually moved to
  /etc/grid-security/certificates.  E.g.,

  mv certificates /etc/grid-security
   

CERTIFICATE REVOCATION LISTS (CRLs)

This specific RPM only supplies the crl_url files that point to the URLs for
downloading of CRL files for the respective CA Certificates.

In order to download and maintain the CRLs, the standard fetch-crl (FetchCRL3 version)
utility supplied in a separate RPM may be used. The fetch-crl utility will retrieve
certificate revocation lists (CRLs) for the set of installed trust anchors,
based on crl_url files or IGTF­style info files.

Here are some tips for configuring the fetch-crl utility:

1. Setup the relocatable CA directory path in /etc/fetch-crl.conf
   By default it would be /etc/grid-security/certificates but if you installed
   the xsede-ca-certificates RPM to a different location, you would need
   to specify that in /etc/fetch-crl.conf

2. Run it manually once (without the -q option) to make sure there are no errors.

    $ sudo fetch-crl -l $HOME/tmp/
    $ ls $HOME/tmp/*.r* | wc
    NOTE: The number of *.r* files must be double the number of *.pem files.

3. Enable the included cron job/service.

   # service fetch-crl-cron start
   # chkconfig fetch-crl-cron on

4. Setup logging/email options:
   a. Modify /etc/cron.d/fetch-crl and remove the -q option to /usr/sbin/fetch-crl
   b. Setup logging/email for the cron job in the cron job file as allowed by
      your version of cron.

5. Enable the included boot-time fetching of CRLs, if desired.

   # service fetch-crl-boot start
   # chkconfig fetch-crl-boot on

DEFECT AND ISSUE REPORTING

Please report any defects and issues to help@xsede.org