Using Fortanix Data Security Manager with Keyfactor EJBCA (Primekey)

1.0 Introduction

This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with Enterprise Java Beans Certificate Authority (EJBCA). 

It also provides the information required to:

• Create an application (app) in Fortanix DSM.

• Configure Fortanix DSM as a crypto token in EJBCA.

• Generate key pairs using the crypto token to create a Certificate Authority (CA).

• Integrate Fortanix DSM with EJBCA using one of the following methods:

  • Using the native Fortanix DSM crypto token (available in EJBCA version 8.0 or later)

  • Using the PKCS#11 driver (required for EJBCA versions earlier than 8.0).

2.0 Prerequisites

Ensure the following:

• sudo privilege or Root access on the EJBCA server.

• Internet connectivity from the EJBCA server to the Fortanix DSM service.

• Admin access to the EJBCA UI to configure the Crypto Token.

NOTE

EJBCA versions 8.0 or later include native Fortanix DSM integration. In these versions, users can create a crypto token directly using the Fortanix DSM option without manually installing the PKCS#11 driver or configuring the DSM endpoint. For earlier EJBCA versions, integration requires installation of the Fortanix PKCS#11 library and manual configuration of the DSM endpoint.

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

3.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. In the DSM left navigation panel, click the Groups menu item, and then click ADD GROUP to create a new group.

   

2. On the Adding new group page, do the following:

   1. Title: Enter a name for your group.

   2. Description (optional): Enter a short description of the group.

3. Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click ADD APP to create a new app.

   

2. On the Adding new app page, do the following:

   1. App name: Enter the name for your application.

   2. ADD DESCRIPTION (optional): Enter a short description of the application.

   3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.

   4. Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

3.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click VIEW API KEY DETAILS.

3. From the API Key Details dialog box, copy the API Key of the app to use it later.

4.0 Create a Crypto Token

EJBCA supports two methods to create a crypto token using Fortanix DSM:

• Using Native Fortanix DSM Crypto Token (Recommended for EJBCA 8.0 and later)

• Using PKCS#11 Integration (Legacy Method)

4.1 Using Native Fortanix DSM Integration (Recommended)

This method is recommended for EJBCA versions (8.0 or later) that provide built-in Fortanix DSM support.

Perform the following steps:

1. Access the EJBCA adminweb with a web browser.

2. Click Crypto Tokens from the CA Functions drop down.

3. Click Create new to create a new crypto token.

4. On the New Crypto Token page,

   1. Name: Enter the name of the crypto token.

   2. Type: Select Fortanix DSM from the drop down list.

   3. Fortanix Base Address: Enter the DSM SaaS URL that you are using. For example, https://eu.smartkey.io.

   4. Authentication Code: Enter the API key obtained in Section 3.5: Copying the API Key.

   5. Repeat Authentication Code: Re-enter the API key value.

   6. Click Save to add a new crypto token.

   

   The new crypto token has been generated successfully.

   

5. Click Generate new key pair to generate a new key pair.

   Example:

   • Alias: signKey2

   • Key Algorithm: RSA

   • Key Specification: 4096

   

6. The keys are created successfully, and the crypto token can now be used to create a CA.

4.2 Using PKCS#11 Integration (Legacy Method)

This is the legacy and manual method of creating the crypto token using PKCS#11 library.

4.2.1 Install PKCS#11 Driver

Perform the following steps to install the Fortanix PKCS#11 driver:

1. SSH to the EJBCA server.

2. Download the Fortanix PKCS#11 driver.

   curl -L https://download.fortanix.com/clients/4.2.1500/fortanix-pkcs11-4.2.1500-0.x86_64.rpm -o fortanix-pkcs11-4.2.1500-0.x86_64.rpm

3. Install the Fortanix PKCS#11 driver.

   sudo dnf localinstall -y fortanix-pkcs11-4.2.1500-0.x86_64.rpm
   rm -rf fortanix-pkcs11-4.2.1500-0.x86_64.rpm

4. Change to the wildfly user and open the web.properties file to edit.

   sudo su - wildfly
   vim /opt/ejbca/conf/web.properties

5. Add the following to the end of the web.properties file.

   cryptotoken.p11.lib.60.name=Fortanix
   cryptotoken.p11.lib.60.file=/opt/fortanix/pkcs11/fortanix_pkcs11.so

6. Save and close the file and exit the wildfly account.

   :wq
   exit

4.1.2 Generate a Crypto Token

Perform the following steps:

1. Restart the Wildfly Application Server.

   sudo systemctl restart wildfly

2. Access the EJBCA adminweb with a web browser.

3. Click Crypto Tokens in the left navigation panel.

   

4. Click the Create new... link to create a new crypto token.

   

   1. In the Type field, select PKCS#11 NG from the drop down menu.

      

   2. Select Fortanix from the PKCS#11 : Library drop down menu.

   3. Select Slot ID from the PKCS#11 : Reference Type drop down menu.

   4. Use the default value for the PKCS#11 : Reference field.

   5. Type a Name for the Crypto token, for example, Fortanix.

   6. Type the Fortanix App API key for the Authentication Code and the Repeat Authentication Code fields.

   

5. Click Save to save the changes.

   

6. Use the default name for the key (signKey), select the key size (RSA4096), and select Sign and Encrypt for the key usage.

   

7. Click Generate new key pair.

   

8. Repeat Steps 6-7 to create the defaultKey and testKey.

   

9. The three keys are created, and the crypto token can now be used to create a CA.