JLab TLS/SSL-Enabled Services and the Supporting PKI

Jefferson Lab Root Certificate Authority -- Client Instructions


JLab maintains its own Certificate Authority to create and sign TLS/SSL certificates used to secure connections to numerous web and other network services. You must install JLab's signing certificate into your web browsers, email, and other clients that use TLS/SSL for secure connections. Without installing this certificate, some clients may generate warnings, while others may simply not connect.

JLAB Managed systems receive the JLab root certificate by default and place it in the system-wide certificate trust store, Firefox' trust store, and the trust store associated with the primary Java JVM installation (Java OpenJDK installation on Linux -- the Oracle JVM trust store is not automatically maintained). Most applications use these trust stores and so should not generate warnings regarding JLab issued certificates. For applications that do not use these certificate repositories, or that fail to receive the certificate automatically, users can install the certificate manually.

Note: Some programs give you the option of adding an exception, or otherwise ignoring whatever warning condition is detected. Such exceptions should never be made unless you are very certain that the exception is safe. A far better approach is to install the JLab root certificate so that your system or application will accept certificates issued by JLab by default.

JLab Root Signing Certificate

The certificate file that must be installed is available via the link below. Its identifying "fingerprint" (also, occasionally called the "thumbprint") is also provided. When installing/trusting any certificate, its fingerprint should be confirmed using a trusted source to insure the certificate is not forged.

  • Certificate File (Base64 Encoded): JLabCA.crt
  • Certificate File (Binary (DER) Encoded): JLabCA.cer
  • Fingerprint: 1e 20 1e 1e 0c 0c ec ab d8 c5 f2 9b 8e 4c 28 51 94 96 9b 9f
  Depending on the program, the fingerprint is sometimes shown with colons between
  each pair of digits. This does not constitute a mismatch, it is simply 
  an attempt to make it easier to read.
  
  Both of the links above are for the same certificate in two different formats. You only
  need one or the other in any single system or application. Both formats are provided to make it 
  easier in cases where you have a system that prefers one format over the other.

Note: For convenience, the root certificate file is also available at

  • (Base64) -- /site/etc/openssl/JLabCA.crt (on Windows systems, this is K:\etc\openssl\JLabCA.crt)
  • (Binary) -- /site/etc/openssl/JLabCA.cer (on Windows systems, this is K:\etc\openssl\JLabCA.cer)

Legacy JLab Root Signing Certificate

The certificate below is being retired over the next several months (by the end of 2017). During that transition period, some systems will continue to use certificates issued by the legacy PKI, so systems need to keep the old root certificate in place as well.

  • Certificate File (Base64 Encoded): JLabWinCA.crt
  • Certificate File (Binary (DER) Encoded): JLabWinCA.cer
  • Fingerprint: e4 9e bf 21 a0 a2 59 2c 8b 2a 21 44 1e 4e 53 f3 f0 d8 fb e7

Note: For convenience, the legacy root certificate file is also available at

  • (Base64) -- /site/etc/openssl/JLabWinCA.crt (on Windows systems, this is K:\etc\openssl\JLabWinCA.crt)
  • (Binary) -- /site/etc/openssl/JLabWinCA.cer (on Windows systems, this is K:\etc\openssl\JLabWinCA.cer)

Instructions

Instructions are provided below for Thunderbird, and several common web browsers -- Firefox, Internet Explorer and Chrome. Instructions are also provided for subversion. Instructions for other applications will be added if needed.

Step 1 -- Download and save the certificate for installation

Most web browsers allow you to doanload and open certificate files in one step, and then provide the option to install the certificate if desired. For other applications, you will need to download and save the certificate file on your system, and then install it into the application.

  • To save on your desktop, right-click the link above and select "Save Link As"
  • Navigate to a convenient location and save the file

Step 2 -- Install the certificate in Common Applications

Install the certificate in Firefox

Assuming you are viwewing this page in Firefox, the certificate can be installed directly (without first saving it to a file on your system).

  • Click the Certificate File link above. You will get the Certificate Download dialog box.
  • Check all three check boxes, indicating that this certificate should be trusted to:
    • identify Web Sites
    • identify email users
    • identify software developers
  • Click the "view" button to examine the certificate to compare the SHA1 fingerprint against that provided above.
  • Click "OK" to complete the installation.

Thunderbird

If you use Thunderbird as an email client, you must first download and save the certificate file as described in step 1. Then, the filel is installed into Thunderbird using the steps below.

  • From within Thunderbird, go to Tools -> Options.
  • Click on the "Advanced" tab near the top of the dialog box.
  • Click on the "Certificates" sub-tab.
  • Click the "View Certificates" button
  • Select the "Authorities" tab.
  • Click the "Import" button to import the file you saved previously.
  • Navigate to the file you saved previously and click OK to open it.
  • You will get a new dialog box with check boxes allowing you to indicate which purposes this certificate should be trusted for. Check all three boxes.
  • Click the view button and compare the "SHA1 Fingerprint" to the value shown above. If they do not match, cancel the import operation and contact the helpdesk
  • Once you have confirmed the fingerprint value, click close, then OK on the previous dialog to complete the import operation. Then, click OK on the Certificate Manager dialog and, finally click OK on the options dialog box to return to Thunderbird.

Upon completion of the steps above, Thunderbird should now happily connect to JLab TLS/SSL-enabld mail servers without generating warnings. If you get any warnings or errors from here on, they should be reported and the cause found and fixed.

Microsoft Edge

Edge is Microsoft's new web browser that is available in Windows 10. For JLab Domain Windows systems, the certificate shoudl be installed by default, so you should not need to perform these steps.

When you click on the certificate link provided above, Edge will download the file by default and save it in your Downloads directory. Once the donwload is complete, you should get a dialog bar at the bottom of the browser windows askign whether you wish to open the file or View Downloads.

  • Click the "Open" button in the dialog bar
  •  
  • You will get a window providing information about the new certificate.
  • Select the "details" tab at the top to compare the SHA1 thumbprint to the one provided above.
  • After confirming the fingerprint, click the "General" tab
  • Click "Install Certificate" near the bottom.
  •  
  • A wizard will start to install the certificate.
  • You will be prompted for which "Certificate Store" should be used for the certificate. Select "Place all certificates in the following store"
  • Click "browse" and select the "Trusted root certification authorities"
  • Click next, then finish to complete the import

Internet Explorer (IE)

With IE, when you click on the URL link above, you will get a dialog asking to open or save the file.

  • Click on the link above and when asked, select "open"
  • You will get a window providing information about the new certificate.
  • Select the "details" tab at the top to compare the SHA1 thumbprint to the one provided above.
  • After confirming the fingerprint, click the "General" tab
  • Click "Install Certificate" near the bottom.
  •  
  • A wizard will start to install the certificate.
  • You will be prompted for which "Certificate Store" should be used for the certificate. Select "Place all certificates in the following store"
  • Click "browse" and select the "Trusted root certification authorities"
  • Click next, then finish to complete the import

Chrome

Chrome on Windows uses the same certificate store as IE. So, if you've installed the certificate for Internet Explorer, it should already be available to Chrome. If you use Chrome but not IE, the process of installing it is similar. Chrome on mobile devices uses a different strategy and you shoudl refer to the notes on Mobile devices below.

  • Click on the links above to download the current and legacy certificate files
  • Chrome will start the download and let you know that this type of file can be harmful, asking you to confirm your desire to download and keep the file -- select "Keep"
  • NOTE: There is nothing intrinsically harmful about certificate files. However, downloading and installing (trusting) a compromised or counterfeit certificate is.
  • At the bottom of the Chrome window, you will see the downloaded file, with a drop down arrow allowing you to choose to open the file -- select "Open"
  • You will get a window providing information about the new certificate.
  • Select the "details" tab at the top to compare the SHA1 thumbprint to the one provided above.
  • After confirming the fingerprint, click the "General" tab
  • Click "Install Certificate" near the bottom.
  • A wizard will start to install the certificate.
  • You will be prompted for which "Certificate Store" should be used for the certificate. Select "Place all certificates in the following store"
  • Click "browse" and select the "Trusted root certification authorities"
  • Click next, then finish to complete the import

Safari (Mac OS X)

Safari uses the System Keychain for trusted root certificate authorities. You need to install the certificate into this Keychain and mark it as trusted.

  • After clicking the .cer link for the Root Certificate to install, open your "Downloads" folder.
  • Double click (or Right/Command Click) the Certificate and it should open with the Keychain Utility. At this point you will need to enter an Administrator password.
  • Locate the Certificate listed under the "System Keychain" (It will have a Red "X" on it to indicate that it is not trusted.)
  • Double click the Certificate to open the properties of the Certificate.
  • Click the triangle next to the word "Trust." This should drop down the options for trusting the Certificate.
  • Select the dropdown box next to "When using this certificate:" and select "Always Trust"
  • Close the Properties box and you will then be prompted to enter the Administrator Password again.
  • After the password has been entered, you should now see that the Certificate listed in Keychain now has a Blue "plus sign" where the Red "X" use to be.
  • Close the Keychain Access Utility and the process is complete.

Installing the JLab Root Certificate for Mobile Devices

Mobile devices vary widely from one OS (Android, iOS, Windows Phone) to another and even from one version or manufacturer to another. For example, the process is quite different for Android Lolipop vs. Marshmallow, or for Android Marshmallow on a Samsung phone or tablet than on an LG model (for example) running the same OS version. In many cases, however, clicking the link above to download the desired certificate, then opening the certificate on the device will perform the installation.

Android General Remarks

For Android based mobile devices, installing a trusted root certificate normally requires you to download and save the desired certificate onto the device's SD card or internal storage, then invoke a process to install the certficate from storage. For details, you will need to refer to your specific device/version documentation, or search for the process details on the internet.

iOS (iPhone, iPad) General Remarks

Browse to this site on the iOS Device that you want to install the certificate on, then follow these steps:

  • Click the .cer link for the Root Certificate to install, this will open the "Install Profile" window.
  • Click "Install" in the upper right hand corner of the "Install Profile" window.
  • You will then be prompted to enter your passcode for you device.(If one is in use.)
  • You will now be given a warning about installing the certificate. Click "Install" in the right hand corner.
  • You will now have a pop up to complete the install, Click "Install" on the pop up menu.
  • The Profile will now say that it is verified and the process is now complete.

Windows Phones and Tablets

For Windows tablets like the Microsoft Surface Pro and others that run Windows, the process is identical to that described above for IE, Edge, Firefox, etc. If these devices are JLab owned (and therefore required to be members of the JLab Windows Domain), installation of the certificate should be automatic. For Windows Phone and similar devices (that do not run the full Windows OS), installation can be performed by tapping the link to download and save the certifciate, then tapping the downloaded file to initiate the installation process.

Installing the JLab Root Certificate into your Subversion Configuration

By installing the JLab root certificate into your subversion configuration, subversion will inherently trust certificates that are issued by the JLab PKI as long as they match the name you asked to connect to, they are within their validity period and have not been revoked (assuming your subversion client performs revocation checking). This is useful since certificates expire and must be replaced from time to time and such changes will trigger warnings if you explicitly trusted the individual server certificate previously by telling subversion to accept the certificate permanently.

To install the jlab root certificate into subversion --

  • Download and save the root certificate using the link near the top of the page
  • Copy the certificate file to a convenient location (like the .subversion subdirectory in your home directory> saving it as "JLabWinCA.crt"
  • edit the "servers" file in your subversion directory
  • Add a line in the global section of the servers file like
    ssl-authority-files = /home/yourusername/.subversion/JLabWinCA.crt
  • Note: If you already have an ssl-authority-files entry defined in your subversion config, add the path to theh JLabWinCA.crt file, separating it from the previous entry with a semicolon

Connecting Without Installing the Jlab Root Certificate into Subversion

If you do not install the JLab root certificate in your Subversion configuration, when you connect to an https-based subversion server URL, the client will inform you that

Error validating server certificate for 'https://someserver.jlab.org:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
Certificate information:
 - Hostname: someserver
 - Valid: from Mon, 11 Jul 2016 13:04:04 GMT until Tue, 09 Jul 2019 16:26:29 GMT
 - Issuer: jlab, org
 - Fingerprint: <hex fingerprint>
(R)eject, accept (t)emporarily or accept (p)ermanently?

You can choose to reject the connection, or accept it temporarily (for this session only), or accept it permanently. The last option stores the certificate into your subversion configuration so that if you connect to the same server again, you will not be prompted.

The fingerprint given is the fingerprint of the subversion server"s certificate -- not of the root certificate provided above. So, you should compare the thumbprint provided to the thumbprint below for the particular server you are connecting to.

SHA1 Fingerprints for current certificates of JLab https subversion servers is provided below

Subversion Server Certificate Fingerprint
svnccc d4:9b:4a:b9:54:be:ef:ab:89:bd:f8:fe:58:65:16:dc:9c:c4:38:d9
svncasa ed:aa:8a:9d:d9:13:32:32:ff:50:5e:65:6a:26:b4:ea:d1:c5:7d:45
qweaksvn 00:81:e6:f7:33:6c:83:aa:34:d3:5b:5b:cf:59:b4:5b:00:63:8e:46
jlabsvn d7:fb:15:9b:be:04:58:03:a2:8d:c5:a5:bc:49:83:42:3a:d5:42:40
halldsvn c4:1d:45:5c:77:de:83:de:94:a8:76:e7:a3:df:4a:70:17:d7:71:19
clas12svn f6:fd:49:2e:c7:79:09:93:c4:d6:c0:30:8e:44:6c:aa:e3:32:0b:2f
phys12svn 27:6f:7d:62:e5:a2:77:1c:a0:8d:9a:d9:80:7a:9f:7b:1f:e2:40:b1