HSM modules available in the Admin GUI

You can manage crypto tokens fully in the EJBCA Admin GUI or CLI. and the Admin GUI automatically displays the HSMs available in your system.

When creating a new Crypto Token (Crypto Tokens>Create New) you can select between Soft and PKCS#11 crypto tokens.

• The PKCS#11 option is only available if EJBCA is able to find any known PKCS#11 modules in the file system.

If EJBCA finds known PKCS#11 modules in the file system, you can select PKCS#11 as Type. As PKCS#11 Library there is a list of the available known HSMs found in the file system.

If the PKCS#11 option is not available or your desired HSM is not in the list of available Libraries, there are a few options to configure:

• If you are using JBoss 7 you must make the java PKCS#11 classes exportable. For more information, see Application Servers.

• You can configure PKCS#11 modules that are not already known to EJBCA in conf/web.properties. See conf/web.properties.sample how to add new known modules and override existing (overriding should not be needed since you can add new locations with the same name).

For more information on creating and using Crypto Tokens for HSMs, see Managing Crypto Tokens and Managing CAs.

The following sections describe the underlying operations and technical features of using HSMs and PKCS#11.

Configuring HSMs

The GUI configuration of CAs is backed by a properties field where properties unique to a particular CAs usage of the HSM is specified. All implemented HSM modules are using the same property keywords to define the identity and the purpose of the keys to be used. These keywords are:

• certSignKey: Key used when signing certificates, can be RSA or ECDSA.

• crlSignKey: Key used when signing CLSs, can be RSA or ECDSA.

• keyEncryptKey: Key used for key encryption and decryption, this must be an RSA key.

• testKey: Key used by HSM status checks, can be RSA or ECDSA.

• hardTokenEncrypt: Key used for hardtoken encryption and decryption. PUK will be decrypted by this key.

• defaultKey: Key used when no other key is defined for a purpose. If this is the only definition, then this key will be used for all purposes.

• pin: Optional pin code used for auto-activation of CA token, see below. Not recommended for high security set-ups, but very useful in some cases.

You may omit defaultKey if you want to be sure that the right key is used, but then all the other keys must be specified. It is recommended that the certificate and CRL signing keys are linked to the same key since different keys are rarely supported by verifying applications.

When implementing support for a new HSM the KeyStrings class could be used to manage the key properties described above. When it is an JCA/JCE API for the HSM it could also be wise to extend the BaseCAToken class.

The same activation code must be used for all keys used by a CA.

There are four additional key properties that can (optionally) be used when renewing CA keys and to produce roll-over certificates. Some of these (in particular the next keys) are only used when using API methods (such as WS).

• previousCertSignKey : Alias of the previous signature key, as opposed to certSignKey which is the current signature key.

• previousSequence: Sequence identifying the previous signature key, as opposed to the current sequence that is held in the CA token. This sequence will replace the current sequence in the caRef field when signing a request with the CAs previous key.

• nextCertSigningKey: Alias of a new generated key on the HSM. When updating a CA signed by an external CA this is used to send a request, but the CA is still active using the old key. When the certificate response is received this key is activate and moved to certSignKey/crlSignKey.

• nextSequence: Sequence identifying the next signature key.

Supported and tested HSMs are described below, with sample configurations and HSM specific documentation.

As of EJBCA 3.6, the recommended HSM connector to use the PKCS#11 interface. Older JCE implementations are deprecated and removed. Contact PrimeKey if you need to migrate.

Testing PKCS#11 keys for use by EJBCA

To test keys on the HSM for use by EJBCA, you can use the EJBCA Client Toolbox.

The command gives further instructions about the parameters required, PKCS#11 library and slot.

Auto-activation of Crypto Tokens

The pin property is used to be able to automatically activate a CA token. The activation code may be specified in the property field with the keyword pin. If this property is not specified, then the CA has to be manually activated after each restart or re-deployment of EJBCA. Manual activation is done in the Admin GUI under Basic Functions > View Information or using the cli bin/ejbca.sh ca activateca.

The pin property can use a clear text password or an encrypted one.

These two properties contain the same password. The obfuscated pin value can be obtained with the command bin/ejbca.sh encryptpwd:

HSMs and DSA or ECDSA

Support for DSA or ECDSA in HSMs are dependent on the support for the algorithms in the HSM. You have to check if that support is available.

For more information on HSMs and ECDSA, see ECDSA Keys and Signatures.

Generic PKCS#11 provider

A PKCS#11 wrapper has been used to implement support for tokens with PKCS#11 libraries. The PKCS#11 provider is tested with:

• Utimaco CryptoServer

• nCipher nShield/netHSM

• SafeNet ProtectServer

• SafeNet Luna

• AEP Keyper

• ARX CoSign

• Bull TrustWay.

Besides the keys previously described, the Crypto Token property field (matching with user friendly values of the Crypto Token in the Administration GUI) should contain the following properties:

• sharedLibrary: Path to the HSM PKCS#11 library (/etc/utimaco/libcs2_pkcs11.so, /usr/safenet/lunaclient/lib/libCryptoki2_64.so etc)

• slotLabelType: Type of slot reference, see below

• slotLabelValue: Value of the slot reference (1, myslot etc).

The slot label type can be one of the following

• SLOT_NUMBER: Any positive integer, can be used to refer to slots in any HSM with consecutive slot numbering.

• SLOT_INDEX: Any positive integer, prefaced by an 'i'.

• SLOT_LABEL: The PKCS#11 standard allows for using strings for labeling slots. This label may also be an integer or an 'i' followed by an integer (like a number or an index)

• SUN_FILE: The slot specified by a SUN config file. The slot label can be left blank.

Optionally a few extra properties fields can be used:

• attributesFile: A file specifying PKCS#11 attributes (used mainly for key generation).

• keyspec: Key specification used when generating new HSM keys from within the admin GUI. Keyspec that is used as first choice when generating new keys in the GUI of form "1024" for RSA keys, "DSA1024" for DSA keys and secp256r1 for EC keys. If keyspec is not given EJBCA tries to generate a key with the same specification as the current cert signing key.

An attributes file is in the format specified in the JavaTM PKCS#11 Reference Guide and the examples further down in this file.

Prior to EJBCA 3.11 there were no default attributes used when no attributesFile existed. Now there is a built-in default configuration used when no attributesFile is specified. Unless you have some strange HSM not working well with the defaults (see below) you should NOT use an attributesFile. Below is an example of an 'attributesFile' (that should not be used) which will give generated keys same attribute values as the default:

The only known occasion where the default is not working is when the module protected slot of a Thales/nCipher HSM is used; then the file must exist and have CKA_PRIVATE = false (see below).

The default attributes that are applied to each key generated by EJBCA will assure that:

• All needed operations could be done.

• The private part of the key is stored in the HSM but not the public part (which is in a certificate that is stored on the HSM).

• It will be impossible to read the private part of the key from the HSM.

The default configuration will also disable certain signing mechanisms. The disabled mechanisms are for signing when the data to be signed is hashed by PKCS#11 before using the private key in the HSM. When these mechanisms are disabled, the sun PKCS#11 wrapper provider will do the hashing instead of the of the HSM. This speeds up the signing in most cases, especially when your HSM is on another host and will not have any security impacts as no secret in the HSM is used for the hashing.

However it will be possible not disable these hash/signing mechanisms, see the PKCS#11 section of '$EJBCA_HOME/conf/cesecore.properties'. You could try not to disable the mechanisms if you get the error CKR_FUNCTION_NOT_SUPPORTED (0x54) from PKCS#11 when signing.

The tool EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool is used to administrate and generate keys. Use it without parameters to get all valid options. Keys are generated either using a default specified slot and PKCS#11 library, or using a configuration file.

• To generate keys using the built-in default with a specified slot and PKCS#11 library, use:

• To generate keys using a configuration file, use:

The contents of the configuration file is specified in the PKCS#11 wrapper documentation from Oracle. Generally it is sufficient to use the default but with some HSMs it may be necessary to define certain PKCS#11 attributes for the generated key.

Note that all keys to be used have to be generated prior to the application server is started.

The default attributes attempt to automatically set CKA_LABEL also when generating keys using the clientToolBox. You can set CKA_LABEL, which is hex encoded characters, also with an attributesFile, either by setting the CKA_LABEL value:

or by setting an empty CKA_LABEL string with two spaces before and nothing, not even a space after. This placeholder will then be dynamically replaced with the key alias value, hex encoded:

Utimaco CryptoServer

The Utimaco PKCS11 module have a configurable timeout (AppTimeout) that clears all session information if you do not use the keys for some time. The default time-out is 30 minutes, which may be way too short if your CA is not very active. We recommend that you set this timeout to a longer value, several days. Put a configuration file in /etc/utimaco/cs2_pkcs11.ini:

The timeout in this example of 172800 seconds will allow your CA to idle for a long time.

When using a PKCS#11 token you should first create keys with the command: $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate

Each CA should have its own slot.

Each slot must have been initialized before keys could be generated on the them. This includes setting a user PIN for it. The slot must also require login. Tools for doing this is not provided from EJBCA. The HSM vendor should provide this tool.

Here follows an example on how to initialize a slot and generate keys to be used by EJBCA. The password is user1:

You can view the pkcs11 objects created with the command:

This is a example of a property field when creating the CA:

Utimaco have an emulator for their CryptoServer LAN HSM that can be used for test and development. If you have the emulation kit there is a howto in doc/howto/cryptoserver-lan-emulator.txt with steps to follow in order to use it with EJBCA.

You can check the status of a CryptoServer LAN device, for example the emulator with:

nCipher nShield/netHSM

This subsection describes how the nShield card from nCipher is used.
First the card has to be installed and admin and operator card sets has to be created. This is described in step 1.
Step 2 describes environments variables that must be set before generating keys and installing a new CA.
Step 3-5 describe PKCS#11 keys are generated and how different CAs within an installation is configured to use these keys. In earlier versions of this manual it was also described how the nCipher JCA provider could be used by EJBCA. This has been removed since PKCS#11 keys are better in every respect.

Step 1. Install the nShield card

1. Make sure you have all necessary software and drivers installed and created the user and group nfast. In Linux should the software be installed to /opt/nfast or the location environment variable NFAST_HOME is pointing to.

2. Login as the nfast user: sudo su nfast

3. Set the nCipher box to initialization mode by setting the switch to mode I.

4. Clear the nCipher box by pressing the reset button on the device.

5. Check that the mode is in pre-initialization mode and not in operational:

   nfast@donny:/home/lars/work$ /opt/nfast/bin/enquiry

   Server:

   enquiry reply flags none

   enquiry reply level Six

   serial number 41C5-BA04-6D2C

   mode operational

   version 2.23.6

   speed index 147

   rec. queue 442..642

   level one flags Hardware HasTokens

   version string 2.23.6cam5, 2.22.6cam7 built on Apr 25 2005 18:15:46

   checked in 00000000431dca98 Tue Sep 6 18:58:00 2005

   level two flags none

   max. write size 8192

   level three flags KeyStorage

   level four flags OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred

   module type code 0

   product name nFast server

   device name

   EnquirySix version 4

   impath kx groups

   feature ctrl flags none

   features enabled none

   version serial 0

   remote server port 9004

   Module #1:

   enquiry reply flags none

   enquiry reply level Six

   serial number 41C5-BA04-6D2C

   mode pre-initialisation

   version 2.22.6

   speed index 147

   rec. queue 9..152

   level one flags Hardware HasTokens InitialisationMode PreMaintInitMode

   version string 2.22.6cam7 built on Apr 25 2005 18:15:46

   checked in 00000000426636cd Wed Apr 20 13:02:37 2005

   level two flags none

   max. write size 8192

   level three flags KeyStorage

   level four flags OrderlyClearUnit HasRTC HasNVRAM HasNSOPermsCmd ServerHasPollCmds FastPollSlotList HasSEE HasKLF HasShareACL HasFeatureEnable HasFileOp HasLongJobs ServerHasLongJobs AESModuleKeys NTokenCmds LongJobsPreferred

   module type code 6

   product name nC1002P/nC3022P

   device name #1 nFast PCI device, bus 0, slot 13.

   EnquirySix version 5

   impath kx groups DHPrime1024

   feature ctrl flags LongTerm

   features enabled StandardKM

   version serial 24

   rec. LongJobs queue 8

   SEE machine type gen1AIF 

6. Create the security world with the command:

   $ /opt/nfast/bin/new-world -i -Q 1/1

   15:04:50 WARNING: Module #1: preemptively erasing module to see its slots!

    

   Create Security World:

   Module 1: 0 cards of 1 written

   Module 1 slot 0: empty

   Module 1 slot 0: unknown card

   Module 1 slot 0:- passphrase specified - overwriting card

   Card writing complete.

    

   security world generated on module #0; hknso = 6807e0b031c4f797b739ec33ca7dba05279cf54f

   $ 

   The -Q K/N option tells how many administration cards that are created N. K of these cards will be needed to restore a module with a backup of the security world. 1/1 is a bad choice in production but will do in this example. Choose K>=3 and N>K in production.

7. Change mode on the switch on the device to mode O.

8. Press the Clear button again.

9. Check with enquiry that the mode has changed to Operational
   Example on creation of operator cards:

   $ /opt/nfast/bin/createocs -m 1 -Q 2/3 -N ejbca -M -p -T 0

    

   Creating Cardset:

   Module 1: 0 cards of 3 written

   Module 1 slot 0: Admin Card #1

   Module 1 slot 0: empty

   Module 1 slot 0: blank card

   Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 1')

   Module 1: 1 card of 3 written

   Module 1 slot 0: remove already-written card #1

   Module 1 slot 0: empty

   Module 1 slot 0: blank card

   Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 2')

   Module 1: 2 cards of 3 written

   Module 1 slot 0: remove already-written card #2

   Module 1 slot 0: empty

   Module 1 slot 0: blank card

   New passphrases do not match; please try again.

   Module 1 slot 0:- passphrase specified - writing card (naming `EJBCA card 3')

   Card writing complete.

    

   cardset created; hkltu = 8d30f2ab5bdccacd8a4333aefed2c0ea1ff0e6db

   $ 

   This will generate 3 cards of the card set named ejbca. Any 2 of these cards will be needed when generating keys and starting ejbca. Different card sets could be used for different CAs.

   The preload command (see below) must always be called as the same user unless the directory /opt/nfast/kmdata/preload is removed.
   If you get a HostDataAccessDenied error when running preload or starting JBoss, it is because the file permissions on the directory /opt/nfast/kmdata/preload is wrong. It's probably because you (sometime) ran preload as another user, such as root or nfast.

10. Load the card set so that keys protected by the card set could be generated:

    $ /opt/nfast/bin/preload -c ejbca pause

    Loading cardsets:

    ejbca on modules 1

     

    Loading `ejbca':

    Module 1 slot 0: `ejbca' #3 (`EJBCA card 3')

    Module 1 slot 0:- passphrase supplied - reading card

    Module 1 slot 0: `ejbca' #3 (`EJBCA card 3'): already read

    Module 1 slot 0: empty

    Module 1 slot 0: `ejbca' #2 (`EJBCA card 2')

    Module 1 slot 0:- passphrase supplied - reading card

    Card reading complete.

     

    Loading complete; now pausing 

Step 2. Setup the environment
Login as the user that is running the application server. This user must be a member of the nfast group. The following environment variables should be set for this user:

• JAVA_HOME (/usr/local/jdk1.6.0_16 or similar)

• APPSRV_HOME (/home/jboss/jboss-5.1.0.GA or similar)

• EJBCA_HOME (/home/jboss/ejbca or similar)

• NFAST_HOME (/opt/nfast)

Step 3. Create PKCS#11 keys that should be used on the nShield card

1. Start a new window and login as the same user (jboss user).

   An ECC key could not be used with preload (at least not the curve secp160r1). Such a key is generated OK and could be used as long as the current preload is running. But if all preload processes are stopped and then if then preload is restarted the key could not be used. This means that ECC could only be used with a 1/n OCS.

2. Now 3 keys protected by the key set ejbca are created like this:

   $ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 defaultRoot i1

   Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 4096 defaultRoot i1

   PKCS11 Token [SunPKCS11-NFastJava] Password:

   Creating certificate with entry default.

    

   $ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 cryptRoot i1

   Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-d165e440baa8dc9963780c682836ba17513e8cbf key (RSAPrivate) on modules 1

   Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 2048 cryptRoot i1

   PKCS11 Token [SunPKCS11-NFastJava] Password:

   Creating certificate with entry crypt.

    

   $ ~nfast/bin/preload -c ejbca $EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 test i1

   Loaded pkcs11 uc17cfc7c330e613af5709789ff823a476177e233c-27cfdae84bf4298f2dde83cd00980a81bcf095bf key (RSAPrivate) on modules 1

   Executing ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /opt/nfast/toolkits/pkcs11/libcknfast.so 1024 test i1

   PKCS11 Token [SunPKCS11-NFastJava] Password:

   Creating certificate with entry test. 

Step 4. Start EJBCA with nShield HSM
To start EJBCA, preload must be running with the required key stores loaded. In this example this was done in step 2. Preload is now used to start jboss:

Step 5. Create a new CA in the web GUI of EJBCA
Choose PKCS#11 as CA Token Type.

Properties are defined according to the Generic PKCS#11 provider section above.

All preloaded operator card sets (OCSs) has its own slot. It is not possible to predict the slot ID. But the index of the slot in the slot list is predictable. slotListIndex must therefore be used. If only one OCS is preloaded this index is always 1.

If several CAs are sharing the same OCS (and hence slot) each key (identified by a key label) may only be used for one CA but the test key. Same test key could be used for all CAs.

Example with previous generated keys where signRoot is used for CAs signing, and defaultRoot is used for everything else (encryption):

When preload is used no authentication code is needed to activate a CA. You could give any value for the authentication code when activating. The pin property could be used in the configuration to automatically activate a CA. The value of this property could be anything.

nCipher load balancing

If you want to use the Loadsharing with multiple modules, be it PCI cards of NetHSM's then you must ensure you have a 1/N OCS and the N quorum to be able to have enough cards to be inserted in every HSM you want to load balance the key at server/CA start up when logging in.
Same security world got to be loaded in all modules participating.
After setting up the first netHSM, do the following on the second:

• Use the panel of the second netHSM to configure the rfs

• Use the panel of the second netHSM to load the security world

• Use the panel of the second netHSM to configure clients

• on each client run: /opt/nfast/bin/nethsmenroll

With load balancing you need to have CKNFAST_LOADSHARING=1. Preload implicitly sets CKNFAST_LOADSHARING.

Example of starting jboss:

When activating a CA you need a smart card from the OCS of the corresponding slot inserted in both HSMs. The OCS got to be 1/n since preload can not be used.
Sample catoken.properties for generating the initial ManagementCA on the netHSM.

AEP Keyper

The document xxxxxxKeyperInstallation.pdf (xxxxxx is six digits) in the KeyPer UserGuides describes how the HSM is installed, the details start in section 3.5 (Configuring the Keyper HSM for the first time). As default there is only one slot - 0. The document xxxxxxKeyperP11.pdf describes the PKCS#11 interface in details.

ARX CoSign

This HSM only works on Windows. The installation is done with an installer and the setup with a GUI.
All generated keys will be on slot 1. The PIN code used when activating the keys could be anything since the authentication is made when login on to the user that runs EJBCA. The shared library is called C:\windows\system32\sadaptor.dll

Bull Trustway Proteccio

The Installation and User's Guide describes how the HSM is installed and how how PKCS#11 tokens are created and how a backup of a token is done. But it might be helpful to mention some additional things:

1. A virtual HSM correspond to a PKCS#11 token.

2. The number of the virtual HSM corresponds to the PKCS#11 slot ID of the token.

3. The PKCS#11 user PIN is the PKCS#11 application authentication in the Personalizing a virtual HSM step.

4. If CIK startup mode is selected for the virtual HSM personalization you must start the HSM manually before EJBCA can use it.

5. Make sure that backup-restore work before taken the HSM in production since the first versions did not backup the certificate of a key which is needed by the java wrapper.

Bull Trustway PCI Crypto Card

This is an old HSM. New installations will probably use Proteccio.

Do the installation of the card according to Install_and_Use_cc2000.pdf. When the card is installed it is ready to use with EJBCA. Only one slot (slot index 0) is available. The slot is not protected by any PIN so an undefined pin (empty) property may be used in the configuration.

When using PKCS11HSMKeyTool and starting EJBCA, libcc2000_tok.so and libgpkcs11cc2000.so must be in the library path. Examples:

SafeNet Luna

SafeNet ProtectServer

SmartCard-HSM

SmartCard-HSM is a lightweight hardware security module in a Smart Card, MicroSD or USB form factor providing a remotely manageable secure key store to protect your RSA and ECC keys.

• Accessing your SmartCard-HSM from EJBCA

• Shared control over key usage

SoftHSM

SoftHSM2 works very well with EJBCA, and after initializing a slot you can use it by creating a new Crypto Token in the Admin GUI.

The user PIN is what you will use to activate the token in EJBCA.

To use it as a normal user, make /var/lib/softhsm/tokens available to your normal user (for writing in order to create keys), and /etc/softhsm/* readable by the user.

After setting privileges, you can use softhsm as normal user.

The Ubuntu package for SoftHSM2 is not always initializing properly (depending on the Ubuntu version you are running) so you may have to create missing directories etc. If you get an ERROR: Could not initialize the library when running the above there is a directory missing, and a token not initialized.

Now you can initialize additional slots. Note that if you provide the --slot parameter to SoftHSM2 it will most likely not become the slotnumber you specify.

To list the slots, use the following command:

PKCS11 Spy

You can debug PKCS11 sessions and all calls made, using OpenSC's P11Spy. As of EJBCA 6.8.0, P11Spy is by default included in the known P11 implementation in con/web.properties.

Stop JBoss, install P11Spy, and set the environment variables used in the JBoss terminal:

Then start JBoss and create a new PKCS11 Crypto Token using the PKCS11Spy PKCS#11 Library.

Support for new HSMs

EJBCA uses PKCS#11 so in theory can support any HSMs that provide a decent PKCS#11 implementation. If the HSM is peculiar you may have to provide specific attribute parameters as descibed for an 'attributesFile' above.

Using SHA256WithRSAandMGF1 (RSASSA-PSS)

Out of the box in Java PKCS#11 RSASSA-PSS is not supported. The software in EJBCA supports it, but the Java PKCS#11 provider does not.

At the time of writing, Oracle Java does not have support for SHA256WithRSAandMGF1 (also known as RSASSA-PSS) in the PKCS#11 provider. PrimeKey has made a patch which is waiting for approval in the OpenJDK. You can get a compiled patch together with an installation script for Debian-based operating systems from PrimeKey.

This issue is registered in the EJBCA issue tracker as ECA-2014.

The patch should work on all HSMs that have support for SHA256WithRSAandMGF1.

With the patch applied you can create CAs using HSMs with the SHA256WithRSAandMGF1 (and SHA384 and SHA512) algorithm.

Extending Sun PKCS#11 to set CKA_MODIFIABLE=false

In order to change the CKA_MODIFIABLE attribute of a private key to FALSE directly after it has been generated the Sun PKCS#11 implementation must be extended. This extension must be done by adding classes to Installed Extensions classpath. See https://docs.oracle.com/javase/tutorial/ext/basics/install.html

This is achieved by putting the '$EJBCA_HOME/dist/ext/cesecore-p11.jar' in one of the directories that is defined by the 'java.ext.dirs' system property. You can put the jar in '$JAVA_HOME/jre/lib/ext'. You may also change the property to include the directory of the jar. Here is an example:

Ensure to keep '$JAVA_HOME/jre/lib/ext' in the classpath.

To enable the feature in EJBCA, set 'pkcs11.makeKeyUnmodifiableAfterGeneration=true' in $EJBCA_HOME/conf/cesecore.properties.

If you use '$EJBCA_HOME/dist/ejbcaClientToolBox.sh' you do not have to set the java.ext.dirs setting as the configuration is performed by the script.

Everything will work without this jar in the classpath, but if it is not in classpath, the CKA_MODIFIABLE will be TRUE for every key that is generated and a warning written to the log.

The reason to set CKA_MODIFIABLE to FALSE is that it should not be possible to set CKA_DERIVE to TRUE. If CKA_DERIVE is true it might be possible to extract the private key from some HSMs (CVE-2015-5464), although most vendors have now patched this by not allowing weak key derivation schemes.

Certain HSMs (for example SoftHSM2) refuses to set CKA_MODIFIABLE to FALSE (the PKCS#11 standard says that this behavior is OK).

In summary, the configuration requires careful testing. Tests can be performed using the clientToolBox tool with a generate-test cycle:

If you also generate keys using the Admin GUI, this should also be tested, together with restarting JBoss between generation and usage.