Public Key Cryptography

Publc key cryptography is a technology which allows two systems which are exchanging data to have the following benefits:

  • Encryption: Data is kept secret between the two systems, and no third party should be able to access it. Generally when people think of TLS (i.e. SSL or HTTPS), they are thinking of the encryption benefits.
  • Trust: This benefit is less commonly considered, but is equally important. Using cryptography is a way for each party to be sure of the identity of the other. This means that your sending system will not accidentally disclose data to someone who should not receive it, and your receiving system will not accept data from soneone who shouldn't be sending it (and potentially reply back with sensitive data as well).

    It is important to consider that TLS does not automatically give you complete trust in both directions, although it can. A common example is a web-based banking website: These sites use a private key with a signed public certificate that lets you (the consumer) be sure that they are actually the bank you are trying to access. TLS does not however give the bank any assurance of who you are. They will rely on usernames and passwords (or other things) for that.

In order to establish a secure connection, at a minimum the server (the party which is accepting incoming connections) needs to have a "private key". This private key is actually just a special block of data that can be used to decrypt data. The private key is called "private" because it needs to be kept secure within the server. Anyone who has a copy of this private key can decrypt data which is destined for the server.

Every private key also has a corresponding "public certificate". This public certificate is used to encrypt data which is then decrypted by the private key. The public key is called public because it is not a secret. It can be shared with anyone, and anyone may then use it to encrypt data for the private key to descrypt. To summarize, at a minimum the server will have a private key, and the client will have a copy of the corresponding public certificate.

TLS Mutual Authentication

TLS Mutual Authentication is a communication mode which is even more secure than standard TLS. It can be thought of as a setup where both the server and the client have a kind of "secret password", and neither side trusts the other until both parties have provided their password. This prevents a sender from disclosing data to someone who isn't the intended recipient, and prevents the receiver from accepting data from someone who isn't an authorized sender. In addition to these features, the data is fully and securely encrypted.

Using TLS Mutual Authentication (also known as Client Authenticated Handshake), two public/private key pairs are used. One private key is held by the server, with the corresponding public certificate being held by the client. The other private key is held by the client, with a corresponding public key being held by the server.

As a note, a keystore file containing private keys is commonly referred to as a keystore, but a keystore file containing public certificates is commonly referred to as a truststore. These do not neccesarily need to be two separate files (the CustomCertificateTlsSocketFactory within the HL7 over HTTP library uses a single file for instance) but many applications will separate these out.)

Using these two key pairs, the connection is fully encrypted, and each party has assurance that the other party is actually who they claim to be (since each party is holding a private key that only they should possess). This is especially important in a setting in which health transactions are being exchanged, since it prevents either side of the connection from being "spoofed".

In order to support TLS mutual authentication, at a minimum the following must occur in order to guarantee to the server that the client is who they say they are:

Certificate Authorities (CAs)

Private keys are sometimes generated by a third party called a certificate authority. Certificate authorities provide an additional layer of trust by allowing you to be sure that the public key you have received is legitimate.

Certificate Authorities have a special kind of public certificate called a "root certificate", which is then used to sign any private keys they issue. Many of these root certificates are bundled into Java (and into most popular web browsers). This explains why you do not need to import any public certificates in order to trust that your Bank website is authentic when you access it using your browser: Your browser came bundled with trusted public certificates for Verisign, Thawte, and other popular certificate authorities.

Many companies, governments, etc. will operate their own private Certificate Authorities. If you are using a private CA, you may need to import that CA's trusted root certificate into your truststore/keystore as well.

Java Keystores

A Keystore is a special kind of file which holds public certificates and private keys.

This documentation here outlines ways to create a Java KeyStore (jks) file which contains certificates and private keys for use in encrypted connections. These key files are often received in a variety of formats (often they are in a format which is generated by the popular OpenSSL tool suite) but the keys and certificates need to be imported into a special kind of container format known as a "KeyStore" in order to be used by Java applications.

Fortunately, most JDK distributions contain an application called "keytool" which can be used to manipulate KeyStore files.


Every private key or trusted certificate in a keystore will have an "alias". The alias is simply a friendly name by which the key is accessed. Depending on your setup, you may wish to configure your application to only use a specific key/certificate within a keystore, and this is done using its alias name.


There are two types of passwords in a keystore. The keystore itself will have a store password, which is required in order to access the contents of the keystore. By convention, this password is often "changeit" wlthough it is good security practice to not use this default.

In addition, each private key may also have a key password. This is a secondary password which is required in order to access a specific key within the keystore.

Creating Keys

Creating a KeyPair

There are several ways of creating a KeyPair (a private key and corresponding public certificate). The easiest way is to generate one yourself. This is called creating a "self-signed" key. See Generating Selfsigned Keys for information on how to do this.

Importing Keys

If the key is coming from someone else, you will need to import it into a keystore before you can use it. See Creating Keystore by Importing for information on how to do this. This is often needed when a key has been generated by a Certificate Authority.