eHealth Exchange Certificate Chain Overview

Owned by Tran Tang
Jul 03, 2019
6 min read

Version History

Version#

Date

Modified By

Description of Modification

1.0

03/06/2014

Christopher May

Initial version

Table of Contents

  1. 112951383

    1. 112951383
    2. 112951383
    3. 112951383
  2. 112951383
    1. 112951383
    2. 112951383
    3. 112951383
    4. 112951383
  3. 112951383
  4. 112951383
  5. 112951383
    1. 112951383
    2. 112951383
    3. 112951383
  6. 112951383
  7. 112951383

Introduction

Motivation & Scope

Members of the eHealth Exchange secure their communications using x.509 certificates whose chain of trust begins with the same Root Certificate Authority (CA), thus facilitating trust between organizations without the need to exchange certificates.  For this reason, an organization must be able to import certificates forming a chain of trust when joining the community as well as when a new Root CA is introduced to the Exchange.  This document covers the procedures and common troubleshooting steps to streamline that process.

Document Audience

This document is intended for technical users who are familiar with basic public-key infrastrucure (PKI) and x.509 concepts.

Prerequisites

The following tools are used throughout this document:

  1. Portecle, or another keystore / certificate manipulation tool (e.g., Keystore Explorer).
  2. openssl - on Linux, this can be installed via the distro's package manager; on Windows, the openssl package can be added to Cygwin or installed as a standalone binary.
  3. keytool - part of the Java Development Kit (JDK).

Portecle

Portecle is a free GUI application for managing keystores and x.509 certificates.  This section is a short primer on the subset of Portecle's functionality necessary to import the chain of trust certificates, omitting steps that can be performed using only keytool or openssl.

Start Portecle

java -jar portecle.jar

Examine Stand-Alone Certificates

  1. Select Examine --> Examine Certificate (keyboard shortcut: Ctrl+E).

  2. Locate and select the relevant certificate file (select Files of Type "All Files" if the certificate's file extension is being filtered by default, e.g., .p7c and .der).

  3. Click Examine (keyboard shortcut: Enter).

  4. To view x.509 extensions, click Extensions (keyboard shortcut: Alt+E).  The following extensions will be referenced in this document:

    1. Subject Key Identifier (SKI)  - provides a means of uniquely identifying that the current certificate contains a particular public key.
    2. Authority Key Identifier (AKI) - provides a means of uniquely identifying the public certificate whose corresponding private key was used to sign the current certificate.
    3. Authority Information Access (AIA) - indicates how to access CA information and services for the issuer of the current certificate.

Note:  When viewing an extension, the value will be listed under "Extension Value" at the bottom half of the window.

Note:  If the loaded file contains multiple certificates, navigate between them using the left and right arrows along the top (keyboard shortcuts: Alt+← / Alt+→).

Note:  Although keytool and openssl can also be used to examine certificates, this step was included because Portecle is the only tool of the three that can export a PEM-encoded certificate based on the information examined from a PKCS#7 file containing multiple certificates.  For reference, below is a non-exhaustive list of commands to examine certificates:

  • keytool -printcert -v -file <certfile.p7c>

  • (PKCS#7): openssl pkcs7 -inform DER -text -print_certs -in <certfile.p7c>

  • (PEM-encoded) openssl x509 -text -print_certs -in <certfile.pem>

Export the PEM-encoded Certificate

While examining a certificate:

  1. Click PEM Encoding (keyboard shortcut: Alt+P).
  2. Click Save (keyboard shortcut: Alt+S).
  3. Enter the file name, INCLUDING the .pem extension (this must be added manually, despite the Files of Type default of "PEM Files (*.pem)".
  4. Click Save (keyboard shortcut: Enter).
  5. Click OK (keyboard shortcut: Enter) to resume examining the certificate.

Note:  A good rule of thumb for naming certificate files is to use information from the Subject's OU (e.g., if the Subject is "OU=Entrust NFI Test Shared Service Provider, OU=Certification Authorities, O=Entrust, C=US", a good file name might be "NFI-Test.pem").

Locate CA Certificate via AIA

While examining a certificate:

  1. Click Extensions (keyboard shortcut: Alt+E).
  2. Select "Authority information access."
  3. In the Extension Value, click the "CA Issuers" link whose URI starts with http.  If this throws an error, see 112951383.
  4. When finished, click OK to resume examining the current certificate.

Retrieving and Converting Certificates

These instructions cover retrieving PKCS#7 certs and converting them to PEM-encoding.

Starting with the leaf certificate:

  1. Examine the current certificate using Portecle and take note of the AKI.
  2. Locate the parent cert via AIA.
  3. Examine the parent cert and verify that its SKI matches the AKI from the first step (if there are multiple certificates, check them all until a match is found).
  4. Export the PEM-encoded certificate.
  5. Repeat steps 1-4, unless the current cert is the Root CA (if this is the case, the AIA extension will be missing, and the cert's SKI and AKI will be identical).

Importing the Certificates

These instructions cover importing the chain of trust, beginning with the root and ending with the Certificate Signing Request (CSR) reply.

Starting with the Root CA:

  1. keytool -importcert -trustcacerts -file <certfile.pem> -alias <alias> -keystore <keystore.jks> [-storepass <password>]
  2. Enter the keystore password when prompted (default: changeit), or specify the password in advance by appending the following flag to the keytool command: -storepass <password>
  3. When importing a Root CA, type yes at the "Trust this certificate? [no]" prompt; for all other cases, this prompt indicates that the certificate being imported is not next in the chain of trust.  See 112951383 to determine whether the certificate is farther down the chain or it belongs to a different chain.
  4. Repeat steps 1-3, unless the current cert is the leaf CSR reply (if this is the case, the success message will be "Certificate reply was installed in keystore" instead of "Certificate was added to keystore").

Note:  When importing a CSR reply, the alias must match that of the certificate the CSR was originally generated from.  For all other certificates, alias should indicate useful information about the Subject (see: 112951383).

Note:  A reference truststore containing both the new and old eHealth Exchange chains of trust is available for download.

Troubleshooting

Invalid .p7c File

The AIA for the eHealth Exchange Intermediate CA (http://dcomweb1.managed.entrust.com/AIA/CertsIssuedToDComRootCA.p7c) is base64 encoded on a single line instead of the expected PKCS#7 file.  To allow Portecle, keytool, and openssl to examine these certificates:

  1. Download the PKCS#7 file:
    1. At the "No certificates found" prompt, click OK (keyboard shortcut: Enter).
    2. At the "Do you wish to try opening the URL in a web browser?" prompt, click Yes (keyboard shortcut: Alt+Y) and download the file.
  2. Convert the encoded file by issuing the following openssl command:
    1. openssl base64 -d -A -in <name_of_encoded_file.p7c> -out <new_file.p7c>

Untrusted Import

If the "Trust this certificate? [no]" prompt appears on a non-Root CA import, compare that certificate's AKI to the SKI of every other certificate in the chain; the matching certificate must be imported before the current one. If no match is found, follow the steps for 112951383.  If the Root CA found using that procedure matches the one that has already been imported, work backwards to import the correct chain.  If they do not match, either the leaf certificate was signed by the wrong CA, or the imported Root CA is not the correct one.  Contact the signer of the leaf certificate to see which Root CA to use.

SSL Handshake Errors

If there is an SSL handshake failure (or other trust error) during communication, verify that each endpoints' leaf certificates share the same CA.  If not, contact the signer of both leaf certificates to determine which certificate is signed by the correct CA; otherwise, double-check that the chain of trust has been imported into both the keystore and the truststore.  In the event that both endpoints do not intend to share the same chain of trust, they must import each others' public leaf certificates into their truststore.

Future Document Enhancements

  1. Better way of denoting <variables> and [<optional variables>].

  2. Generating a CSR.

  3. There are other ways the .p7c can be invalid; make this generic and provide other solutions.

  4. Script / command-line method to take a single pkcs7 file with multiple certs, and turn it into multiple files with one cert each.

  5. Screenshots for Portecle functionality.

  6. Move Portecle tutorial to its own page, include in links.

  7. OpenSSL and keytool tutorials, including what commands can and cannot be emulated using Portecle.

  8. Glossary (CSR, PKI, etc.).

  9. Testing the chain (and when to use 112951383).

Links / Additional Reading

  1. RFC 5280 - X.509 PKI (ietf.org)

  2. RFC 2315 - PKCS #7 (ietf.org)

  3. Chain of trust (wikipedia.org)

  4. X.509 (wikipedia.org)

  5. Public-key infrastructure (wikipedia.org)

  6. /wiki/spaces/CONNECTWIKI/pages/8585431 (atlassian.net)

  7. /wiki/spaces/CONNECTWIKI/pages/11174264 (atlassian.net)