Using Certificates

CILogon is retiring our X.509 certificate services. See CILogon X.509 Certificate Retirement Plan for details.

The CILogon Service (https://cilogon.org) provides certificates for secure access to cyberinfrastructure. CILogon certificates are standard RFC 5280 X.509 end entity certificates, which are supported by a wide variety of software. On this page, we provide tips and pointers for using certificates.

Protect Your P12 File

Your web browser may save your usercred.p12 certificate file with world-readable permissions. Use the chmod command to protect it:

$ chmod 0600 usercred.p12

Convert from P12 to PEM

The "Get New Certificate" button at https://cilogon.org provides a link to your certificate and private key in PKCS12 (P12) format. To convert it to PEM format for OpenSSL-based applications, use the openssl command:

$ openssl pkcs12 -in usercred.p12 -nokeys -out usercert.pem

$ openssl pkcs12 -in usercred.p12 -nocerts -out userkey.pem

Use chmod to ensure your private key is not world-readable:

$ chmod 0600 userkey.pem

Finding CILogon Certificates

If you choose the "Download Certificate" link at https://cilogon.org (available only in select CILogon "skins"), the CILogon Service launches a Java Web Start application on your desktop that saves their certificate and private key in PEM format in the default Globus Grid Security Infrastructure (GSI) location, which is /tmp/x509up_u${UID} on Unix or ${tmpdir}/x509up_u${UID} on Windows or ${tmpdir}/x509up_u${user.name} if ${UID} is not defined.

Verifying CILogon Certificates

CILogon certificates are signed by the CILogon CAs. Links to CA certificates, CRLs, etc., are provided on the CILogon CA Downloads page.

For example, to verify the signature on a certificate issued by the CILogon Basic CA using OpenSSL:

$ openssl x509 -subject -noout -in /tmp/x509up_u${UID}

subject= /DC=org/DC=cilogon/C=US/O=Example/CN=John Smith A251

$ openssl verify -CAfile cilogon-basic.pem /tmp/x509up_u${UID}

/tmp/x509up_u501: OK

Displaying Certificate Subject DNs

The Subject Distinguished Name (DN) uniquely identifies the "subject" (i.e., holder or owner) of the certificate. Internally it is represented as a (binary) ASN.1 sequence of RelativeDistinguishedName components. It is common to view Subject DNs as simple character strings, though the conversion from ASN.1 to string is lossy, so using the ASN.1 data directly when possible is preferable. To view the two common string representations of Subject DNs, you can use the following OpenSSL commands:

$ openssl x509 -in /tmp/x509up_u${UID} -noout -subject

subject= /DC=org/DC=cilogon/C=US/O=Example/CN=John Smith A251

$ openssl x509 -in /tmp/x509up_u${UID} -noout -nameopt RFC2253 -subject

subject= CN=John Smith A251,O=Example,C=US,DC=cilogon,DC=org

$ openssl asn1parse -in /tmp/x509up_u501${UID}

[...]

The first command shows the old OpenSSL "oneline" (compat) format (which is the OpenSSL default), and the second command shows the RFC 2253 format (which is frequently seen in Java and LDAP applications). The two formats are equivalent, and it just depends on the application which format is preferred. The third asn1parse command shows the full ASN.1 contents of the certificate including the Subject DN.

Portal Delegation

See Portal Delegation for instructions on integrating the CILogon Service with your web application or portal.

Certificate Expiration

See Certificate Expiration for some tips on monitoring for and managing certificate expiration.

Use P12 Files with Globus

The grid-proxy-init command can read usercred.p12 files directly. Simply move your usercred.p12 file to the location expected by grid-proxy-init, then enter your password when prompted:

$ mkdir ~/.globus

$ mv usercred.p12 ~/.globus

$ chmod 0600 ~/.globus/usercred.p12

$ grid-proxy-init

Enter GRID pass phrase for this identity:

Your identity: /DC=org/DC=cilogon/C=US/O=Example/CN=John Smith A251

Creating proxy ................................................ Done

Your proxy is valid until: Tue Feb 15 05:34:28 2011

Using P12 Files with Firefox

Some browsers will prompt you to import the usercred.p12 file into the browser or operating system when you click on the "Download Your Certificate" link. Firefox does not do this. Firefox will simply save the file to disk. You must then manually import the usercert.p12 file into Firefox. To do so, open the Options / Preference panel. (The location of Options or Preferences varies depending on the operating system and Firefox version. For Windows, "Tools->Options". For Mac OS X, "Firefox->Preferences". For Linux, "Edit->Preferences".) Select the "Advanced" icon, then "Encryption" tab, then click the "View Certificates" button. (Example of Options panel in Firefox.) Then select the "Your Certificates" tab and click the "Import" button. Navigate to the directory where you saved the usercred.p12 file and open it. You will be prompted to "enter the password that was used to encrypt this certificate backup". Type in the same password you entered on the cilogon.org site. You should now see a new certificate from CILogon. Click the "OK" button to exit the Firefox Certificate Manager.

Verifying an HTTPS Certificate with Java

Your HTTPS site should have a valid certificate that is acceptable by web browsers and Java applications. You can use a simple URLReader.java program to test your site's HTTPS certificate. After downloading the URLReader.java file to your local system, compile and run it as follows:

$ javac URLReader.java

$ java URLReader https://example.org/ > /dev/null

$ java URLReader https://example.edu/ > /dev/null

Exception in thread "main" javax.net.ssl.SSLHandshakeException:

sun.security.validator.ValidatorException: PKIX path building failed:

sun.security.provider.certpath.SunCertPathBuilderException: unable to

find valid certification path to requested target

If there is no error output (as in the case of https://example.org/ above), your HTTPS certificate checks out OK. However, if you see an Exception (as in the case of https://example.edu/ above), this indicates a problem with your HTTPS certificate. Please consult your certificate vendor's documentation about how to properly install your certificate.

Web site certificate testers are also available from Comodo and DigiCert.

General Tips

References