Host and Service Certificates¶
Host and service certificates are used to securely identify your system and to establish encrypted connections between services and clients in the OSG. Host certificates can be used by any service running on your system. In contrast, service certificates are used to identify specific services on your machine. For example, HTCondor-CE typically uses a host certificate while RSV, Gratia, Tomcat, and Apache httpd use service certificates. Technically, the primary difference between a host certificate and service certificate is in the common name (CN) field of the certificate. A host certificate's CN contains the hostname (e.g. mymachine.mydomain.edu) while a service certificate will prepend a service name to the hostname (e.g. http/mymachine.mydomain.edu for an Apache httpd service certificate).
Since October 2015 the OSG has run its own OSG CA service that handled host and service certificate requests. At the end of May 2018, this service will be retired; see the policy details here. To replace the OSG CA service, we suggest using one or more of the following services depending on your site's needs:
- InCommon: an IGTF-accredited CA for services that interact with the WLCG; requires a subscription, generally held by an institution
- Let's Encrypt: a free, automated, and open CA frequently used for web services; see the security team's position on Let's Encrypt for more details
Certificates issued from the OSG CA before the service retirement will still be valid until they expire. Therefore, we recommend that you request certificates for any currently existing or planned hosts and services prior to retirement.
After reading this document you should be able to apply for and install a host or service certificate on a grid resource. This document does not explain how to apply for a grid user certificate. To learn how to apply for a grid user certificate click here instead!
Before requesting a new host or service certificate, you should use openssl to check if you have a valid certificate already. If so, you may safely skip this document:
[email protected] $ openssl x509 -in /etc/grid-security/hostcert.pem -subject -issuer -dates -noout subject= /DC=org/DC=opensciencegrid/O=Open Science Grid/OU=Services/CN=host.opensciencegrid.org issuer=/DC=org/DC=cilogon/C=US/O=CILogon/CN=CILogon OSG CA 1 notBefore=Jan 4 21:08:09 2010 GMT notAfter=Jan 4 21:08:09 2011 GMT
Requesting InCommon Host Certificates¶
Many institution in the United States already subscribe to InCommon and offer certificate services. If your institution is in the list of InCommon subscribers, continue with the instructions below. If your institution is not in the list and Let's Encrypt certificates do not meet your needs, please contact us.
Generate a Certificate Signing Request (CSR) and private key:
[email protected] # openssl req -nodes -new -newkey rsa:2048 -sha256 -out req.pem -keyout hostkey.pem
When prompted, use your institution's information for the
State or Province,
Organization Namefields then the hostname for the
Your institution may require more information in the request. Try using the CSR generated above in your initial request.
Set the permissions on the private key:
[email protected] # chmod 0600 hostkey.pem
Find your institution-specific InCommon contact (e.g. UW-Madison InCommon contact) and submit the CSR that you generated above, asking for the certificate to be signed by the InCommon IGTF CA
- After the certificate has been issued by your institution, download it on its intended host and copy over the key you generated above.
Verify that the issuer
InCommon IGTF Server CA:
$ openssl x509 -in <PATH TO CERTIFICATE> -noout -issuer issuer= /C=US/O=Internet2/OU=InCommon/CN=InCommon IGTF Server CA
Requesting Host Certificates Using Let's Encrypt¶
Let's Encrypt is a free, automated, and open CA frequently used for web services; see the security team's position on Let's Encrypt for more details. Let's Encrypt can be used to obtain host certificates as an alternative to InCommon if your institution does not have an InCommon subscription.
letsencrypt software (AKA
certbot) can be obtained from the EPEL 7 yum repo:
[email protected] # yum install certbot
If you have any service running on port 80, you will have to disable it temporarily to obtain certificates, as letsencrypt needs to bind on it temporarily in order to verify the host. For instance, if you already have an HTCondor-CE set up with the HTCondor-CE View service running, stop the HTCondor-CE View service, as it listens on port 80.
Run the following command to obtain the host certificate with Let's Encrypt:
[email protected] # certbot certonly --standalone --email <ADMIN_EMAIL> -d <HOST>
Set up hostcert/hostkey links:
[email protected] # ln -s /etc/letsencrypt/live/*/cert.pem /etc/grid-security/hostcert.pem [email protected] # ln -s /etc/letsencrypt/live/*/privkey.pem /etc/grid-security/hostkey.pem [email protected] # chmod 0600 /etc/letsencrypt/archive/*/privkey*.pem
Before the host certificate expires, you can renew it with:
[email protected] # certbot renew
To automate renewal monthly with a cron job; for example you can create
/etc/cron.d/certbot-renew with the following contents:
* * 1 * * root certbot renew
Requesting Host/Service Certificates Using the Command Line¶
The OSG PKI Command Line Clients are tested to work on Python version 2.4+. They have not been tested on Python version 3. In order to proceed you will also need:
- an X.509 user certificate
- Grid Admin privileges
As with all OSG software installations, there are some one-time (per host) steps to prepare in advance:
- Ensure the host has a supported operating system
- Obtain root access to the host
- Prepare the required Yum repositories
- Install CA certificates
If you would like to request a host or service certificate without obtaining Grid Admin privileges, see this section.
Requesting Grid Admin privileges¶
A Grid Admin is a person associated with a Virtual Organization (VO) that has
been given privileges to automatically approve host certificate requests for a
given domain and any sub-domain. For example, a Grid Admin for the
domain would be able to approve host or service certificate requests for
Installing the OSG PKI command line client¶
The scripts needed to request host or service certificates are contained in the
osg-pki-tools RPM. Install it by running the following:
[email protected] # yum install osg-pki-tools
Please refer to this documentation for full documentation of the osg-pki-tools.
Validating your X.509 user certificate¶
Make sure you can create a valid grid proxy with
grid-proxy-init. For example :
[email protected] $ voms-proxy-init Enter GRID pass phrase for this identity: Your identity: /DC=org/DC=opensciencegrid/O=Open Science Grid/OU=Services=People/CN=Alain Roy 424511 Creating temporary proxy ................................................................................. Done Contacting glow-voms.cs.wisc.edu:15001 [/DC=org/DC=opensciencegrid/O=Open Science Grid/OU=Services/CN=glow-voms.cs.wisc.edu] "GLOW" Done Creating proxy ..................................................................... Done Your proxy is valid until Fri Dec 2 01:32:47 2011
Requesting host certificates¶
The osg-gridadmin-cert-request script only supports requesting host
certificates that are in the same domain. The certificates are stored with the
<hostname>.pem and the corresponding key is stored as
<hostname>-key.pem. For example:
To request a host certificate for
[email protected] $ osg-gridadmin-cert-request -H host.opensciencegrid.org
To request a host certificate for
host.opensciencegrid.orgwith Subject Alternative Names (SANs), use the
-aflag for each SAN:
[email protected] $ osg-gridadmin-cert-request -H host.opensciencegrid.org -a host1.opensciencegrid.org -a host2.opensciencegrid.org
To request more than one host certificate, you can provide a file with one host per line and optional SANs separated with spaces. The following example would request three certificates; one for
host1.opensciencegrid.org, one for
host2.opensciencegrid.org, and one for
host.opensciencegrid.orgwith the SANs
host1.opensciencegrid.org host2.opensciencegrid.org host.opensciencegrid.org host1.opensciencegrid.org host2.opensciencegrid.org
If the above contents were saved to
hostfile, run the following command to request multiple certificates:
[email protected] $ osg-gridadmin-cert-request -f hostfile
Installing host certificates¶
Finally, install the certificate in the default location
[email protected] # cp ./host.opensciencegrid.org.pem /etc/grid-security/hostcert.pem [email protected] # chmod 444 /etc/grid-security/hostcert.pem [email protected] # cp ./host.opensciencegrid.org-key.pem /etc/grid-security/hostkey.pem [email protected] # chmod 400 /etc/grid-security/hostkey.pem
Requesting and installing a service certificate¶
Requesting service certificates¶
To request a service certificate, use the same osg-gridadmin-cert-request command used to request host certificates
but prepend the service name,
<SERVICE>, to the requested hostname:
[email protected] $ osg-gridadmin-cert-request -H <SERVICE>/host.opensciencegrid.org
All methods for requesting host certificates can also be used to request service certificates
Installing service certificates¶
Since a single host can run multiple services, service certificates must be placed in their own directory.
Create a directory indicating the name of the service,
[email protected] # mkdir /etc/grid-security/<SERVICE>
Copy and rename the service certificate and key to the
<SERVICE>directory that you created above:
[email protected] # cp ./<SERVICE>-host.opensciencegrid.org.pem /etc/grid-security/<SERVICE>/<SERVICE>cert.pem [email protected] # cp ./<SERVICE>-host.opensciencegrid.org-key.pem /etc/grid-security/<SERVICE>/<SERVICE>key.pem
For example, the service certificate for an Apache httpd service should be installed in
Set the appropriate permissions on the service certificate and key
Set the ownership of the directory and its underlying files to the Unix user, indicated as
<USER>, who runs the service:
[email protected] # chown -R <USER>:<USER> /etc/grid-security/<SERVICE>/
For example, both the Apache and Tomcat services are run by the
[email protected] # chown -R tomcat:tomcat /etc/grid-security/http/
Requesting Host/Service Certificate Using OIM¶
If you do not have Grid Admin privileges, please use OIM to request any host or service certificates that you may need. The OSG PKI Certificate Request & Management System can be found at: https://oim.opensciencegrid.org/oim/certificate. Alternatively, you can request Grid Admin privileges here after obtaining your user certificate.
Frequently Asked Questions¶
Can I use any host to request a certificate for a different host?¶
YES, you can use any host to create a certificate request as long as the hostname for the certificate is a fully qualified domain name.
May I reuse my host certificate as a service certificate?¶
NO! For security reasons, please do not use clones of your host certificate for additional certificates even though it's technically possible.
How do I renew a host/service certificate?¶
There is no separate procedure. Simply ask for a new certificate the same way you asked for it the previous time.
I get a "GSS authentication failure" when users try to authenticate with my site?¶
You likely used an alias for the host instead of the fully qualified domain name when you generated the certificate request. This can cause the GSS authentication failures similar to the following when a user tries to authenticate to the host after your certificate is installed:
GSS authentication failure GSS Major Status: General failure GSS Minor Status Error Chain: accept_sec_context.c:gss_accept_sec_context:403: Error during delegation: Delegation protocol violation Failure: GSS failed Major:000d0000 Minor:00000001 Token:00000000
How can I check if I have a host certificate installed already?¶
By default the host certificate key pair will be installed in
/etc/grid-security/hostkey.pem. You can
use openssl to access basic information about the certificate:
[email protected] # openssl x509 -in /etc/grid-security/hostcert.pem -subject -issuer -dates -noout subject= /DC=org/DC=opensciencegrid/O=Open Science Grid/OU=Services/CN=host.opensciencegrid.org issuer= /DC=org/DC=cilogon/C=US/O=CILogon/CN=CILogon OSG CA 1 notBefore=Apr 8 00:00:00 2013 GMT notAfter=May 17 12:00:00 2014 GMT
How can I check the expiration time of my installed host certificate?¶
If you installed the Certificates Script Package you can use grid-cert-info to retrieve information about the certificate:
[email protected] # grid-cert-info -file /etc/grid-security/hostcert.pem -startdate -enddate Jan 4 21:08:41 2010 GMT Jan 4 21:08:41 2011 GMT
Alternatively you can use openssl:
[email protected] # openssl x509 -in /etc/grid-security/hostcert.pem -dates -noout notBefore=Jan 4 21:08:41 2010 GMT notAfter=Jan 4 21:08:41 2011 GMT
- CILogon documentation for requesting InCommon certificates
Useful OpenSSL commands (from NCSA) - e.g. how to convert the format of your certificate.
Another Let's Encrypt setup reference Under Getting your host certificate, we follow the first "Setting up" section.