Requesting or Renewing Host certificates

This guide describes how to request a new host certificate or renew an existing one, and what to do with the new/renewed certificate.

If the host already has a valid certificate, skip step 1a) and continue with step 1b)

1a) Request a new host certificate

To request a new host certificate, follow the procedure on the Dutchgrid CA website. Part of this procedure involves downloading and executing a shell script. Executing the script has to be done as user root on server vlaai, in directory /export/perm/share/grid-security/hostname/year (which should probably be created first!). For example, for host graszode in year 2008:

# mkdir -p /export/perm/share/grid-security/graszode/2008
# cd /export/perm/share/grid-security/graszode/2008
# sh ./makerequest.sh .

This will create a few files, including one called userkey.pem

Complete the administrative procedure as described on the CA web page and continue with step 2).

1b) Renewing an existing (valid) host certificate

To renew a host certificate, follow the procedure on the Dutchgrid CA website. Part of this procedure involves downloading and executing a shell script. Executing the script has to be done as user root on server vlaai. Create a new directory /export/perm/share/grid-security/hostname/year to hold the new key/certificate pair. Then execute the downloaded script, providing the existing certificate as parameter (according to convention, it should be present in the directory corresponding to the previous year) and use options -d to store the output files in the desired directory:

# mkdir -p /export/perm/share/grid-security/tbn01/2008
# cd /export/perm/share/grid-security/tbn01/2008
# ls -l ../2007/usercert.pem
-rw-r--r-- 1 root root 5146 Jan 30  2007 ../2007/usercert.pem
# dca-rekey-pack.sh -d . ../2007/usercert.pem

This will create a few files, including one called userkey.pem

Complete the administrative procedure as described on the CA web page and continue with step 2).

2) Installing the key/certificate pair on the host

After some time, the CA will send a mail with the location of the generated host certificate. As root on vlaai, download the certificate from the given location into the directory where the output files of the request are stored. Rename the downloaded certificate to usercert.pem.

# cd /export/perm/share/grid-security/tbn01/2008
# wget link-to-host-certificate
# mv WXYZ.pem usercert.pem

In the parent directory, /export/perm/share/grid-security/hostname, two symbolic links need to be created that point to the most recent host key and certificate (if they already exist, remove the links first).

# cd ..
# ls -l user*.pem
lrwxrwxrwx 1 root root 17 Aug  4 18:25 usercert.pem -> 2007/usercert.pem
lrwxrwxrwx 1 root root 16 Aug  4 18:25 userkey.pem -> 2007/userkey.pem
# rm -f usercert.pem userkey.pem
# ln -s 2008/usercert.pem
# ln -s 2008/userkey.pem

In order to allow the host to retrieve its host key (and certificate), create a file release.state with a recent time stamp (still to be done as root in the directory /export/perm/share/grid-security/hostname):

# touch release.state
# chown apache:apache release.state

Continue with step 3) to install the new/renewed key/certificate pair on the host. This needs to be within the expiration time of 60(?) minutes.

3) Installing the key/certificate pair on the host

Login as root on the host on which the key/certificate pair needs to be installed. The procedure below assumes that a local tool trustedget is available. For all Quattor-managed hosts at NDPF, this should be the case.

If the host is running gLite 3.1 middleware that is configured via Yaim, then Yaim can install the key/certificate on all locations and take care of restarting services. The local Yaim function config_host_certs() takes all steps required to download the files from vlaai and install them with correct ownership and permissions. Note that for some node types, additional Yaim functions need to be executed (e.g, for DPM servers). The safest way is to force Yaim to run again.

TODO: insert a link to the Wiki entry on running Yaim by hand, once it is written

If Yaim cannot be used, or if the host still runs gLite 3.0, the following steps can be taken to download and install the host key and certificate (in fact, this is what the Yaim function does). This assumes that the tool trustedget is present on the host.

Verify that the key/certificate pair can be downloaded:

# /usr/local/sbin/trustedget https://vlaai.nikhef.nl/retrieve.php?willdo
200 Will release tbn01

This means that it is possible to download the host key. If the resulting message is "403 Release for tbn01 expired", then the file release.state at the server either does not exist, is not owned by user and group apache, or has a timestamp that is too far in the past. In that case, downloading the key is not possible. The certificate may always be downloaded.

To download the certificate:

# /usr/local/sbin/trustedget https://vlaai.nikhef.nl/retrieve.php?cert > /etc/grid-security/hostcert.pem

Ensure the permissions on the certificate are 0644 (world-readable).

To download the key:

# /usr/local/sbin/trustedget https://vlaai.nikhef.nl/retrieve.php?key > /etc/grid-security/hostkey.pem

Ensure the permissions on the key are 0400 (only readable for root). After downloading the key, the timestamp of the key file on the web server is reset to "1 Jan 1970" and downloading of the key is no longer possible.