EJBCA
This guide outlines step-by-step instructions for seamlessly integrating EJBCA with a Luna HSM device or Luna Cloud HSM service. EJBCA is a robust Certificate Authority (CA) software of enterprise quality, developed using Java (JEE) technology. It offers high performance, platform independence, flexibility, and a component-based structure that can function independently or be seamlessly integrated into other applications. The integration between Luna HSM or Luna Cloud HSM service and EJBCA utilizes the widely recognized PKCS#11 interface. EJBCA efficiently generates 2048-bit RSA keys on the Luna HSM or Luna Cloud HSM service, which are then used for tasks such as Certificate and CRL signing.
The key benefits of this integration are:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration has been tested and verified on the following platforms:
| HSM Type | Platform Tested |
|---|---|
| Luna HSM | RHEL 7 RHEL 6 |
| Luna Cloud HSM | RHEL 7 |
EJBCA has been tested in both High Availability (HA) and FIPS-compliant modes.
Prerequisites
The prerequisites for this integration are:
Set up Luna HSM
As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later on used by EJBCA.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
/usr/safenet/lunaclient/bin/lunacm
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v10.2.0-111. Copyright (c) 2020 SafeNet. All rights reserved. Available HSMs: Slot Id -> 0 Label -> EJBCA Serial Number -> 11280780175877 Model -> LunaSA 7.3.0 Firmware Version -> 7.3.0 Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode Slot Description -> Net Token Slot FW HW Status -> FM Ready
Enable partition policies 22 and 23 to allow activation and auto-activation, in case you are using PED-authenticated HSMs.
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
To configure a PED-based Luna HSM properly, make sure to set the ProtectedAuthenticationPathFlagStatus to 1 in the Misc section of the Chrystoki.conf file. This setting is essential to ensure secure authentication processes.
Set up Luna HSM High-Availability Group
Refer to Luna HSM documentation for HA steps and details regarding configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly setting in HA for failover to work so that if the primary goes down due to any reason, all calls get automatically routed to the secondary until the primary recovers and starts up.
Set up Luna HSM in FIPS Mode
To configure Luna HSM in FIPS Mode, update the configuration file by adding or modifying the following setting within the [Misc] section:
RSAKeyGenMechRemap=1
This setting ensures that older calling mechanisms are redirected to the approved RSA key generation methods (186-3 with primes and 186-3 with aux primes) required for FIPS compliance. By making this configuration change, Luna HSM will be properly set up to operate in FIPS mode, adhering to the approved RSA key generation standards.
The configuration setting mentioned above, RSAKeyGenMechRemap=1, is not required for the Universal Client. It is applicable only for Luna Client 7.x.
Managing User Access to Your HSM
Initially, only the root user can access the Hardware Security Module (HSM). However, you can grant access to specific non-root users by including them in the hsmusers group. This group is automatically created when you install the client software. Even if you later uninstall the client software, the hsmusers group remains intact, ensuring you can upgrade your software without losing your user access settings.
To add users to the hsmusers group
If you wish to permit non-root users or applications to interact with the HSM device, you must assign these users to the hsmusers group. Make sure that the users you intend to add to the hsmusers group are already established on the client workstation. Only users added to the hsmusers group will be granted access to the HSM device. Follow these steps to add a user to the hsmusers group:
Ensure that you possess sudo privileges on the client workstation.
Add a user to the hsmusers group using the command:
sudo gpasswd --add [username] hsmusers
Replace username with the actual username you want to include in the hsmusers group.
To remove users from the hsmusers group
If you need to withdraw a user's authorization to access the HSM device, you can remove them from the hsmusers group. Carry out the following steps to remove a user from the hsmusers group:
Confirm that you hold sudo privileges on the client workstation.
Eliminate a user from the hsmusers group using the command:
sudo gpasswd --add [username] hsmusers
Replace username with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.
Any user you remove will retain access to the HSM device until the client workstation is rebooted.
Set up Luna Cloud HSM
Follow these steps to set up your Luna Cloud HSM:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
This integration has been certified on the RHEL platform.
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
tar -xvf cvclient-min.tar
Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.
source ./setenv
To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Set up EJBCA server
To set up your EJBCA server, visit the official EJBCA documentation page. There, you'll find comprehensive guidance and instructions on how to get your EJBCA server up and running successfully.
Set up EJBCA on AWS
Setting up EJBCA on AWS involves a few key steps that you need to follow:
Deploy EJBCA from AWS Marketplace: First, make sure you have deployed PrimeKey EJBCA Cloud from the Amazon Web Services (AWS) Marketplace. You should be able to access it once it's up and running. You can refer to the EJBCA Cloud documentation for guidance.
Install and Configure Luna HSM Client: Next, install the Luna HSM client on your EJBCA instance. It's crucial to configure the client properly. You should establish an NTLS connection between this client and your Luna HSM device. This connection ensures the secure handling of cryptographic operations.
Configure EJBCA Portal: Finally, you'll want to configure the EJBCA portal to fit your specific requirements. For detailed instructions on this step, consult the EJBCA Cloud AWS Launch Guide. This guide will provide you with the necessary information to configure the EJBCA portal as needed.
By following these steps, you can effectively set up EJBCA on AWS, ensuring that it operates securely and aligns with your specific needs.
Integrating Luna HSM with EJBCA
To integrate the EJBCA Application Server with either a Luna HSM device or the Luna Cloud HSM service, follow the procedure outlined below:
Set up Thales Luna Crypto Library for EJBCA
Create PKCS11 crypto token on EJBCA
Create certificate profiles for end entities
Set up Thales Luna Crypto Library for EJBCA
To set up Thales Luna Crypto Library on your EJBCA system, follow these steps:
Locate the Thales Luna Crypto Library: Begin by locating the Thales Luna Crypto Library file, which should be in one of the following paths:
-
/usr/lunasa/lib/libCryptoki2_64.so
-
/usr/lunapci/lib/libCryptoki2_64.so
-
Program Files/LunaPCI/cryptoki.dll
-
/usr/safenet/lunaclient/lib/libCryptoki2_64.so
-
/opt/thales/dpodclient/libs/64/libCryptoki2.so
Configure the Crypto Token Library Location: If you find the library in a location different from the ones listed above, open the [ejbca_installation_directory]/conf/web.properties file and add the following code, replacing [any_crypto_token_lib_name] with a suitable name and [path_to_luna_crypto_library] with the actual path where the Luna Client Crypto library is located:
cryptotoken.p11.lib.xx.name=cryptotoken.p11.lib.xx.file= /libCryptoki2_64.so
Build EJBCA: Once you have correctly configured the Thales Luna Crypto Library, proceed to build EJBCA by executing the following commands:
ant clean deployear
Create PKCS11 crypto token on EJBCA
To create a PKCS11 crypto token within EJBCA, follow these steps:
Access EJBCA Admin Page: Open your web browser and navigate to the EJBCA admin page using the following link: https://[EJBCA Server IP Address]/ejbca/adminweb.
Navigate to Crypto Tokens: In the EJBCA admin page, locate and select Crypto Tokens under CA Functions. This action will direct you to the Manage Crypto Tokens page.
Initiate Token Creation: Scroll down to the bottom of the table on the Manage Crypto Tokens page and click Create new. This action will take you to the New Crypto Token page.
Configure the New Token: In the New Crypto Token page, provide a name for your token in the Name field. For the purposes of this guide, we'll use Thales as an example for the Crypto Token Name. Then, from the Type dropdown menu, select PKCS#11.
Crypto Token Details: Proceed to enter the necessary details to create a PKCS11 token. Ensure that you use the Luna crypto library name you added earlier. The Authentication Code corresponds to the Luna HSM Crypto Officer password.
EJBCA will automatically populate the PKCS#11 library, Reference Type, and Reference fields if your crypto library is correctly configured. In the case of multiple PKCS#11 libraries, make sure to select the Luna crypto library you've configured.
Save Your Configuration: After providing the required information, click Save. You should receive a confirmation message indicating the successful creation of your CryptoToken.
Generate keys for EJBCA
To create encryption keys for your EJBCA system using the EJBCA Admin web portal and the Thales Crypto Token, follow these steps:
Access Thales Crypto Token: Begin by accessing the Thales Crypto Token within the EJBCA Admin web portal.
Configure Key Details: Scroll down to the bottom of the page, and you'll find a section where you can specify key details. Start by entering a meaningful Key Name. In the Key Size drop-down menu, select the desired key size that suits your requirements.
Generate Key Pairs: To generate your encryption keys, click the Generate new key pair button. For comprehensive key management, be sure to repeat this procedure two more times, creating additional keys for the Root CA and Sub CA.
Create Root CA
To create your Root CA with the Luna HSM PKCS#11 cryptographic token, follow these steps:
Verify Token Availability: In the EJBCA web portal, navigate to Crypto Tokens and confirm that the PKCS#11 token is listed within the Manage Crypto Tokens table. Ensure that the entry displays the Thales Luna PKCS#11 library and slot ID, and that the crypto token is in an Active and Used state.
Create the Root CA: From the left pane, select the Certification Authorities tab and proceed to add a CA name. For illustration purposes, we'll use ExampleRootCA as the CA name.
Configuration Details: Click Create and adjust the settings as outlined below:
| Setting | Configuration |
|---|---|
| Signing Algorithm | Choose SHA256WithRSA |
| Crypto Token | Select Thales |
| defaultKey | Set to defaultKey |
| certSignKey | Set to signKey |
| Description | Provide a description such as Root CA for Example Inc |
| Subject DN | Enter CN=ExampleRootCA,O=Example Inc,C=RS |
| Validity | Set to 20 years |
| Default CRL Distribution Point | Click Generate |
| CRL Expire Period | Set to 1 year |
| CRL Overlap Time | Specify 2 days |
Complete Creation: After configuring the details, click the Create button. Once the operation is finished, your new certificate authority (CA) will be added to the list of CAs.
Configure sub-CAs
To configure sub-CAs, follow these instructions carefully:
Clone Sub-CA template
Start by accessing the Certificate Profiles page from the list of available certificate profiles.
Find the SUBCA profile and click the Clone button located next to it.
In the Name of new certificate profile field, provide a name for the new certificate profile.
Click Create from Template. This action will create a new certificate profile with properties copied from the SUBCA profile. Please note that the exact configuration of certificate profiles may vary based on your specific requirements and standards.
Create sub-CA
From the List of Certificate Profiles field, select Example Sub-CA and click the Edit button.
Make the following changes to this profile, as shown in the example below:
| Setting | Configuration |
|---|---|
| Available bit lengths | 2048 bits |
| Validity | 15 years |
| Allow validity override | Off |
| CRL Distribution Points | On |
| Use CA defined CRL Dist. Point | On |
| Available CAs | ExampleRootCA |
Click Save.
Now, proceed to create the CA responsible for issuing certificates to servers. Access the Certification Authorities page and enter a name (e.g., ExampleServerCA) in the Add CA box.
Click the Create button and implement the following changes, as indicated in the example below:
| Setting | Configuration |
|---|---|
| Signing Algorithm | SHA256WithRSA |
| Crypto Token | Thales |
| defaultKey | myKey |
| Description | CA in charge of issuing certificates for servers within the organization |
| Subject DN | CN=ExampleServerCA,O=Example Inc,C=RS |
| Signed By | ExampleRootCA |
| Certificate Profile | Sub-CA |
| Validity | 15 years |
| Default CRL Distribution Point | Click Generate |
| CRL Expire Period | 14 days |
| CRL Overlap Time | 12 hours |
Click the Create button to finalize the basic CA hierarchy.
Create certificate profiles for end entities
Here's a step-by-step procedure to create certificate profiles for end entities:
Access Certificate Profiles Page: Start by opening the Certificate Profiles page from the list of available Certificate Profiles.
Clone the SERVER Profile: Locate the SERVER profile and click the Clone button next to it.
Specify New Profile Name: In the Name of new certificate profile field, provide a distinctive name for your new certificate profile. For this guide, we'll use ExampleServer as an example.
Create from Template: Click the Create from Template button. This action will generate a new certificate profile with properties copied from the SERVER profile.
Modify Certificate Profile: Now, select the ExampleServer certificate profile and click Edit. Make the following adjustments to the certificate profile:
-
Set Available bit lengths to 1024 and 2048.
-
Enable CRL Distribution Points.
-
Ensure that Use CA defined CRL Dist. Point is activated.
-
Choose ExampleServerCA from the list of Available CAs.
Save Changes: Finally, click Save to save the modifications. With this step, you have successfully created the basic certificate profiles for your end entities.
Create end entity profiles
Follow this step-by-step method to generate end entity profiles:
Access End Entity Profiles: Begin by clicking the End Entity Profiles button.
Add a New Profile: In the Add Profile text box, enter a name for your end entity profile, such as Server, and then click Add.
Edit the End Entity Profile: Select the Server profile you just created and click Edit End Entity Profile.
Specify Subject DN Attributes: Add the following Subject DN attributes and set them all as Required and Modifiable:
-
O (Organization)
-
C (Country, ISO 3166)
Modify Server Profile: Make the following adjustments to the Server profile:
| Setting | Configuration |
|---|---|
| Username | Set as Server |
| Password | Set as Server |
| Batch Generation (clear text pwd storage) | Activate On |
| CN (Common Name) | Specify Server |
| Subject DN | CN=ExampleServerCA,O=Example Inc,C=RS |
| O (Organization) | Set as Example Inc |
| C (Country, ISO 3166) | Specify RS |
| Default Certificate Profile | Choose ExampleServer |
| Available Certificate Profiles | Select ExampleServer |
| Default CA | Choose ExampleServerCA |
| Available CAs | Select ExampleServerCA |
| Default Token | Set to User Generated |
| Available Tokens | Choose User Generated |
Save Changes: Finally, click Save to save the modifications to your end entity profile.
Set up Publish Queue Process Service
When you're publishing certificates and CRLs to remote locations, it's crucial to ensure uninterrupted service even in the event of a network outage. Follow these steps to configure the Publish Queue Process Service:
Access the Services Page: Start by navigating to the Administration > Services page in the EJBCA interface.
Add a New Service: In the Add Service box, enter a name for your service. In this guide, we'll use Publish Queue Process Service as the service name.
Confirm the New Service: Click Add to create the service.
Edit the Service: Select the Publish Queue Process Service tab and click the Edit Service button.
Configure Service Details: Provide the necessary information:
| Setting | Configuration |
|---|---|
| Select Worker | Choose Publish Queue Process Service. |
| Select Interval | Opt for a Periodical Interval. |
| Period | Set the interval to 1 minute. |
| Select Action | Choose No Action. |
| Active | Ensure that it is On. |
| Pin to Specific Node(s) | Specify the node you want to assign this service to (e.g., ca.example.com). |
| Description | Provide a brief description, such as Publish certificates and CRLs from the publisher queue. |
Save Changes: Click the Save button to confirm and save your service configuration.
By following these steps, you'll have successfully set up the Publish Queue Process Service, allowing EJBCA to seamlessly publish certificates and CRLs, even during network interruptions.
Configure CRL updater service
The CRL updater plays a vital role in generating and regenerating CRLs and certificates as soon as they expire. To configure the CRL updater for your EJBCA system, follow these steps:
Access the Services Page: Start by navigating to the Administration > Services page in your EJBCA interface.
Add a New Service: In the Add Service box, provide a name for your service. For this guide, we'll use CRL Updater as the service name.
Create the Service: Click the Add button to create the service.
Edit the CRL Updater Service: Select the CRL Updater service and click the Edit Service button.
Configure the Service Details: Enter the necessary information, aligning with the example provided below:
| Setting | Configuration |
|---|---|
| Select Worker | Choose CRL Updater. |
| CAs to Check | Specify the CAs you want to monitor, for example, ExampleRootCA and ExampleServerCA. |
| Select Interval | Opt for a Periodical Interval. |
| Period | Set the interval to 5 minutes. |
| Select Action | Select No Action. |
| Active | Ensure that it is set to On. |
| Pin to Specific Node(s) | Specify the node where this service should be assigned, e.g., ca.example.com. |
| Description: | Provide a concise description, such as "Updates the CRLs if necessary. Checks are made every 5 minutes." |
Save and Apply Changes: Click the Save button to confirm your configuration and apply the changes.
With these steps, you've successfully configured the CRL Updater service, ensuring that CRLs and certificates are promptly updated as needed. This marks the completion of the integration of Luna HSM or Luna Cloud HSM with your EJBCA system.
