Creating Direct Anchors, Trust Bundles and Keystores

Version History

Overview

Direct Project users will need to establish real-world trust relationships with other Direct Project users on their own terms, but once they have established this real-world trust, they can be sure that a Direct Project network will securely deliver Direct Project messages to the trusted Direct Project user.  In order to build a secure platform for the transmission of protected health information, the Direct Project must specify acceptable protocols and technologies that Direct Project implementers will use to communicate secure network messages over multiple possibly insecure, temporary inter-network interfaces for Direct Project users.

Direct Project security specifications dealing with Trust

One of the goals of the Direct Project security specifications is to enable message handling trust between participants.  The identify of a sender must be verified when the information from that sender is received.  A Direct Project participant should be allowed to specify other participants they trust to exchange information.  Exchanging and reading of X509 certificates helps accomplish this.  The X509 Certificate has certain properties that allow software to verify that the certificate was sent to the person or organization it was intended to. The Certificate is signed by a second certificate that is owned by the Certificate Authority.  Proof that the Certificate was issued by the trusted CA is possible by inspecting certificate. The root certificate, also known as the Trust Anchor, holds the derived chain of trust.  If you hold the Trust Anchor certificate, you may use it to prove that a certain certificate that was issued by the CA, thus proving that it is trustworthy.

Creating an organizational certificate

This is your local certificate (private key) for identifying yourself within a Direct exchange.

# Generate the local keystore files (only if the gateway.jks, cacerts.jks do not exist).  USE THE SAME PASSWORD FOR ALL CERTIFICATES AND KEYSTORES.
keytool -genkey RSA -keysize 1024 -keystore directKeystore.jks -keypass {PASSWORD} -storepass changeit -validity 365 -alias gateway -dname "cn={DOMAIN_NAME} ou={ORG_UNIT} o={ORGANIZATION}"
keytool -v -export -rfc -alias gateway -file {DOMAIN_NAME}.cer -keystore gateway.jks -keypass changeit -storepass {PASSWORD}
keytool -v -import -keypass changeit -noprompt -trustcacerts -alias {DOMAIN_NAME} -file {DOMAIN_NAME}.cer -keystore cacerts.jks -storepass {PASSWORD}

Creating a Direct anchor

This is your public key that will be shared with Direct partners you wish to exchange messages with.  Direct supports different certificate formats (PEM, PKS12, PKS7)

# Generate the anchor from the directKeystore.jks.  For this first example, we are exporting to a DER certificate.
keytool -v -export -rfc -alias gateway -file {DOMAIN_NAME}.der -keystore directKeystore.jks -keypass changeit -storepass changeit
	
# Convert to PEM format, if desired.
keytool -exportcert -alias pem -file pemFile.pem -rfc -keystore cacerts.jks

# Convert to PKSC12, if desired.
keytool -importkeystore -srckeystore cacerts.jks -destkeystore pkcs12File.p12 -srcstoretype JKS -deststoretype PKCS12 -deststorepass [PASSWORD_PKCS12]
	

Creating a trust bundle

Trust Bundles are a collection of trust anchor certificates. Trust bundles are packaged into a single file using the PKCS7 standard and distributed via a known URL (the location is discovered out of band).

Importing anchors into keystores

Run this command to import an anchor (direct_test.der in this example) into the local trust store (cacerts.jks)

keytool -v -import -keypass changeit -noprompt -trustcacerts -alias localhost -file direct_test.der -keystore cacerts.jks -storepass changeit