Version History

Table of Contents

1. eHealth Exchange Certificate Chain Overview#Introduction

   1. Motivation & Scope

   2. eHealth Exchange Certificate Chain Overview#Document Audience

   3. eHealth Exchange Certificate Chain Overview#Prerequisites

2. eHealth Exchange Certificate Chain Overview#Portecle

   1. eHealth Exchange Certificate Chain Overview#Start Portecle

   2. Examine Stand-Alone Certificates

   3. Export the PEM-Encoded Certificate

   4. Locate CA Certificate via AIA

3. Retrieving and Converting Certificates

4. Importing the Certificates

5. eHealth Exchange Certificate Chain Overview#Troubleshooting

   1. Invalid .p7c File

   2. eHealth Exchange Certificate Chain Overview#Untrusted Import

   3. eHealth Exchange Certificate Chain Overview#SSL Handshake Errors

6. Future Document Enhancements

7. Links / Additional Reading

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 Troubleshooting - Invalid .p7c File.

4. When finished, click OK to resume examining the current certificate.