Install BlackVault Library and integrate with Java


The BlackVault communicates over the network using PKCS#11. For a host to communicate with the BlackVault, the BlackVault’s PKCS#11 library, TLS certificates, and pkcs.dat must be installed first. Additionally, the Java files nss.cfg and must be correctly setup.




1. Insert the BlackVault HSM Setup CD into your computer, on it you will find a file called bv-setup.exe


2. Run bv-setup.exe


3. Windows asks if you want the installer to make changes to computer, select yes.



4. The installer asks, “Would you like to configure the BlackVault for Java?” select yes.


5. The first window you will see is the overview window. It goes over what will be installed. Select Next to continue.


6. Next the installer asks for the Java directory currently being used on Windows. Browse for the desired top-level Java directory (usually in C:/Program Files/Java/jre8 or C:/Program Files(x86)/Java/jre8) then press next


7. Next the installer asks for the BlackVault IP address and TLS Port. Enter those there and press next.


8. Next, the installer asks for the location of the directory to install the necessary files to. Either use the default location, or to select a new location, click browse and specify the new location.


9. Next, the installer asks for which components to install, the Engage BlackVault Cryptography Provider (CNG/Authenticode and PKCS#11 libraries), or just the PKCS#11 Library



10.  The installer then gives a summary of items to be installed press install to continue.


11. The installer then installs all the components, including a Microsoft Visual C++ Redistributable.


12.  Once the installer finishes press finish.




1. Copy the BlackVault Setup CD to a directory on your system.  In that directory do the following:


2. chmod +x


3. sudo ./



4. press enter

5. The appropriate PKCS11 library libbv is installed in /usr/local/lib. Then the script asks for an install directory (default to your home folder). Enter the install directory (or leave blank for default and press enter.


6. The script then asks for if you would like to “Include a BlackVault IP and Port?  (ex:  123.456.789 1234) {y/N]” for the pkcs.dat file. To continue,  press “y”, then the enter key. Next type the ip address and port number of the BlackVault and press the enter key again.


7. The TLS certificates are installed in /etc/ssl/certs.


8. At this point the BlackVault is setup to work with any non-Java application written to the PKCS11 API such as applications written in C or C++.  Select y and press enter to continue setting up java.


9. The Script asks for the “Java JRE/JDK directory” then displays the environment variable $JAVA_HOME. Press enter if this is the correct directory. If it is not change it now then press enter.

10. The script now asks, “Verify installation? [y/N]”.   Choose “y” if you wish to have the script run Java keytool to list the keys stored on the BlackVault.   


11. Log in as User on the BlackVault.  Provided no keys have been created, the expected result would look something like the following:



12. In order for full settings to take restart the system, as environment variables were changed .


Signing with Java Jarsigner and the BlackVault HSM


To do code signing per industry best practices, along with creating and storing the key inside a secure HSM, a code signing certificate associated with the key is required. This section first describes how to create a key, and then how to create the certificate.

If a key already has been created by Java, you can skip the first section and move onto Jarsinger operation


Key and Certificate Creation


Before signing code, you need a key and certificate for that key. Keytool is used for this purpose as described below.


Keytool is a key and certificate management utility that allows users to administer their own public/private key pairs and associated certificates. It is used in self-authentication or data integrity and authentication services, using digital signatures. It also allows users to cache public keys (in the form of certificates) of their communicating peers.

If you have completed the previous steps in this guide (Java configured correctly, and PKCS#11 library installed), perform the following using a command terminal:


  1. To create a key
    For Java enter the following commandkeytool -genkey -keystore NONE -storetype PKCS11 -alias KeyNameHere -keyalg RSA -keysize 2048 -storepass 123456
    1.  Although Java requires a storepass entry (typically used for authenticating the keystore), the BlackVault HSM authenticates itself and does not use this password.
    2. keysize is the size of the algorithm
    3. keyalg is what key algorithm you want to use
    4. alias is the name of the key
    5. keystore and storetype is telling Java to use the PKCS#11 functions of Java


  1. After entering the keytool command Java will prompt for Identifying information. This is used for the self-signed certificate that is created by the BlackVault HSM at the same time the key is created.


  1. It will then prompt if all entries are correct. When you are sure the information is correct, type yes and then press the enter key.
  2. After creating the key, verify the key is stored in the BlackVault by listing the keys from the BlackVault with the following command.
    For java keytool has a list key function: keytool -list -keystore NONE -storepass 123456 -storetype PKCS11

If a self-signed certificate is sufficient skip to the next section, if you would like a certificate signed by an independent certificate Authority perform the following:

  1. Next a certificate signing request (CSR) is generated from the key just created by performing the following steps.
    For Java enter the following command:  keytool -certreq -alias KeyNameHere -keyalg RSA -file CSRNameHere.csr -keystore NONE -storetype PKCS11
  • keystore and storetype is telling Java to use the PKCS#11 functions of Java
  • alias is the name of the key
  • keyalg is what key algorithm you want to use
  • keysize is the size of the algorithm
  • storepass is normally used for authenticating the keystore, but the BlackVault HSM authenticates itself and does not use this password. Java requires it anyways
  • file is the filename that the CSR will output to.


  1. Get the CSR signed by a Certificate Authority (i.e. Digicert, Verisign, etc)
  2. After obtaining the certificate from a Certificate Authority it will need to be attached to the key from which it is derived. To do this it must be imported into the BlackVault
    For Java enter the following command: keytool -import -trustcacerts -alias KeyNameHere -file CaFileHere.pem -keystore NONE -storetype PKCS11
  • keystore and storetype is telling Java to use the PKCS#11 functions of Java
  • alias is the name of the key
  • file is the location and file name of the certificate that was created by a certificate authority


Jarsigner Operation


Everything is setup now to start code signing. To do a sample code signing to verify everything is working do the following:

  1. sign code
    For Java, use the following command: jarsigner -keystore NONE -storetype PKCS11 /Path/To/Your/Jar KeyNameHere
  • keystore and storetype is telling Java to use the PKCS#11 functions of Java
  • KeyNameHere is the name of the key on the BlackVault
  • /Path/To/Your/Jar is the location and file name of the jar that is needing to be signed.


  1. Verify code

For Java, use the following command: jarsigner -verify /Path/To/Your/Jar

  • /Path/To/Your/Jar is the path to the jar that needs to be verified

  • Provided everything was set up correctly, the output will show the information of your certificate as well as the information of the CA that signed the certificate.

  1.  If the output is something different than the Verify failed and the code that you try to verify was changed from what was originally signed.

Engage logo 990000 rev 2.000
9565 Soquel Drive Dr,
Aptos, CA 95003
Telephone: +1-831-688-1021
Toll Free : +1-877-ENGAGE4
Designed, Fabricated, and Assembled
in America icon
Supported Worldwide