Generating Self-signed Public/Private Keys
Public and Private keys are cryptographic certificates which, when used together may be used to securely encrypt or sign data when transmitting it from one system to another. A description of this process is found here.
In Java, public and private keys are each placed in a special file called a keystore. The private key in a keystore must be kept secure. It should be very carefully guarded. The public key in a keystore (which is referred to as a "truststore") does not need to be kept secure. It may be emailed or copied freely.
Creating the key
First, the private key is created using an application called keytool. Note that in the example below:
- You must choose a password for the keystore. It is possible to store more than one public or private key in a single keystore, but the same keystore password must be used each time.
- The certificate is set to expire after 5 years (1826 days), according to the validity argument. You may wish to adjust this appropriately.
- Every private or public key in a keystore has an alias. This alias will be needed by the HL7 over HTTP client or server modules to specify which key in the keystore should be used. It is required even if only one key is located in the keystore. It is generally a good idea to use a descriptive alias which specifies what the key is for (e.g. adt_messages_to_fictitiouslab).
Enter keystore password: thepassword
Re-enter keystore password: thepassword
What is your first and last name?
[Unknown]: (provide a sensible value)
What is the name of your organizational unit?
[Unknown]: (provide a sensible value)
What is the name of your organization?
[Unknown]: (provide a sensible value)
What is the name of your City or Locality?
[Unknown]: (provide a sensible value)
What is the name of your State or Province?
[Unknown]: (provide a sensible value)
What is the two-letter country code for this unit?
[Unknown]: (provide a sensible value)
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes
Enter key password for <my_app_alias>
(RETURN if same as keystore password): (hit enter)
When this is complete, you now have a keystore containing a private key. This keystore must be kept in a secure location and not copied unneccesarily!
Exporting the public key
Once you have a keystore containing a self-signed private key, your next step is to export this key to create a truststore. First you must extract the key from the private keystore.
Enter keystore password: thepassword
Certificate stored in file <public.cert>
The resulting file "public.cert" contains the public key in a format called PEM. If you are communicating with a remote party (i.e. at another organization) you will want to provide a copy of this file to them. Public Key certificates to not need to be kept secret, but you should be careful that they are not tampered with if you send them externally.
If you send your public key to an outside party, it is a good idea to separately verify that they key hasn't been tampered with. One way to accomplish this is to use OpenSSL to generate an MD5 hash of the certificate. If this command is run by the sender, and also run by the receiver, and the values match, you can be reasonably confident that the key has not been tampered with.
(stdin)= c587e8b28c735fc0773e37c4594ce937
What Next?
You will now want to provide a copy of your public certificate to the person who will be sending you messages. If they are using the relay as well, they might want to see Creating a Client Keystore for information on what to do with it.