Monday, February 9, 2015

Peer Systems in EJBCA Enterprise 6.3.0 - introduction and tutorial

We hope that you'll get as excited as we are about our latest new EJBCA feature: Peer Systems. We'd like to take this blog post to tell you all a little about what this means and how EJBCA Peer Systems will improve your PKI, as well as give a simple tutorial on how it works.
Peer Systems is a protocol for communicating between EJBCA nodes securely. Its purpose is to allow propagation of data and information in a synchronous fashion, without requiring a safe connection or an isolated network. In previous iterations of EJBCA the only means of communication were either the WebService API or direct database publishing. Web services is on one hand too slow to use for data heavy applications like very high speed certificate publishing, while database publishing needs database specific security measures or a closed network, seldom an option for OCSP.
Two requirements have prompted Primekey to move towards developing a brand new feature set:
  1. The need from the PKI Appliance platform to be able to set up OCSP responders without redeploying the application, requiring steps to be performed via the CLI or set up special database rules.
  2. The value of enabling our users to spend less time digging into the server configuration, setting up database connections. VA machines can often be physically or geographically inaccessible from their respective CAs, and Peer Systems is a step in the right direction making things easier to set up using only the GUI.
Note that this feature is for EJBCA Enterprise customers only. If you'd like to find out how to enroll, please contact us.

Initial Concepts

This tutorial will cover an installation involving two machines in a PKI setup, a Certificate Authority (CA) and a Validation Authority (VA) serving as an OCSP responder for the CA. We will be building on concepts introduced in earlier versions of EJBCA 6, so if you're not familiar with the creation of End Entities or OCSP Key Bindings, feel free to check our User Guide.

Establishing Trust

For this tutorial, all communication will be initiated on the CA, so our connection will be one way. The first thing we need to do is to establish trust between the two machines (CA and VA), and we will do so by creating an Authentication Keybinding on the CA.
  1. Click on the Internal Key Bindings item in the menu and choose the AuthenticationKeyBinding tab.
  2. Create an authentication keybinding using the crypto token of your choice. The crypto token chosen will be the one providing keys for the TLS connection.
  3. Return to the AuthenticationKeyBinding overview page. Notice that your newly created keybinding isn't enabled, and doesn't have a certificate. Let's fix that.
  4. Click on the CSR button in the Action column.
  5. On the CA machine create an End Entity and issue the keybinding certificate. Make sure that Key Usage: Digital Signature and Key Encipherment and Extended Key Usage: Client Authentication are set in the Certificate Profile.
  6. Return to the AuthenticationKeyBinding overview page on the CA machine. Import the certificate you got in the previous step to your authentication keybinding by clicking the Update button.
  7. Enable your keybinding.
A properly set up Authentication Keybinding

Setting up the Outgoing Peer on the CA

Now we'll talk about how to set up our CA and VA as Peers.
  1. Incoming connections are disabled by default, so first of all on the VA, click on Peer Systems in the admin menu and then click on the Allow incoming connections checkbox.
  2. Now go to the CA, and enter the Peer Systems page here as well.
  3. Click on the Add button under Outgoing Peer Connectors.
  4. Create new Peer, making sure to enter the VA's address (matching the VA's server side TLS certificate) and the selected authentication keybinding.
A newly created Outgoing Peer on the CA

Setting up the Incoming Peer on the VA

  1. Click the Ping button for the Outgoing Peer (on the CA) and you'll get the reply "Unable to connect to peer. Unauthorized." Not to worry, you simply have to add rights on the VA.
  2. Import the CA certificate of the CA (used to issue the certificate for the End Entity on the CA in the steps above) as an External CA.
  3. Go to the VA, and under the Incoming Connections section you should see the incoming connection from the CA. To the right you'll see the button Create Authorization (see screen shot for required options).
  4. Either add the incoming peer to an existing role or go right ahead and create a new one.
  5. In the next screen, choose the required rights for the incoming connection and click on Create Authorization.
  6. Returning to the Peer Systems screen, there should be a newly created role under the First matching role column of your created peer.
  7. Returning to the CA, you should be able to ping the VA as before, now receiving a response.
  8. Congratulations, you've established trust.
Authorizing an Incoming Peer

Setting up a Validation Authority Peer Publisher

The last step is to set up a Validation Authority Peer Publisher, which happily works just like the old VA Publisher.
  1. On the CA, go to Publishers and create a new publisher.
  2. Choose Validation Authority Peer Publisher as a type and choose the newly created peer as a Peer System.
  3. Click Save and Test Connection and you're done!
You've now set up VA Publishing between CA and VA, without having to grant any database rights or allowing direct database access over network to your VA. Cheers!

More information
Basic information on EJBCA Enterprise PKI is available here.
EJBCA is a registered trademark of PrimeKey Solutions AB in the EU, the United States, Japan and certain other countries.

1 comment:

Unknown said...

Thanks so much for this blog post. It made peer connector implementation much easier to understand than could the official documentation alone. I would love to see more tutorials of this quality for ejbca, particularly around clustering with jboss/wildfly. Thanks again.