You are here: Integration with Your Application > Supported Integrations > Java > Using Java Keytool with Luna SA

Using Java Keytool with Luna HSM

This page describes using Java keytool with Luna HSM, to implement a keychain.

Luna SA 5 JSP configuration

Luna JSP is installed as part of the Luna Client software installation. After that, two additional steps are required for a Linux platform.

Copy the library file to the JDK/JRE installation directory tree.
root@c-sa5:~# cp -p /usr/safenet/lunaclient/jsp/lib/LunaProvider.jar $JAVA_HOME/jre/lib/ext/
root@c-sa5:~# cp -p /usr/safenet/lunaclient/jsp/lib/libLunaAPI.so $JAVA_HOME/jre/lib/ext/
Modify the file $JAVA_HOME/jre/lib/security/java.security to add the Luna provider (otherwise JSP dynamic registration will be needed in the Java code).
security.provider.3=com.safenetinc.luna.provider.LunaProvider

Your decision where to place the LunaProvider will depend on your specific environment. It does not have to be the default (security.provider.1). It might be best to have the provider at the bottom. (See "Linux and UNIX Installation")

Alternatively, you can choose to perform JSP dynamic registration in your Java code. "Dynamic Registration Sample"

Java -- Encryption policy files for unlimited strength ciphers

Additionally, you might need to apply the unlimited strength ciphers policy. The unlimited strength ciphers policy files can be downloaded from Oracle.

The US_export_policy.jar and local_policy.jar are to be copied to JAVA_HOME/jre/lib/security (or the equivalent directory that applies to your setup).

[root@my-sa5client]# echo $JAVA_HOME

/usr/java/default

[root@my-sa5client]# cp -p local_policy.jar /usr/java/default/jre/lib/security/

[root@my-sa5client]# cp -p US_export_policy.jar /usr/java/default/jre/lib/security/

Keytool Usage and Examples

Elsewhere in this documentation it is suggested that you use the provided "salogin" tool if your software is not HSM-aware. When using Java, that is not necessary. Instead, you can manually create a keystore file to specify your HSM partition. This can be specified by partition label or by slot number. Two sample keystore file contents are shown below. The naming of the files is not important - only the contents.

The keytool examples below refer to a keystore file named bylabel.keystore. Its content is just one line:

tokenlabel:a-partition-name

where a-partition-name is the name of the partition you want the Java client to use.

Here is the (one line) content of a keystore file that specifies the partition by slot number:

slot:1

where 1 is the slot number of the partition you want the Java client to use.

To test that the Java configuration is correct, execute:

my-sa5client:~/luna-keystores$ keytool -list -v -storetype Luna -keystore bylabel.keystore

The system requests the password of the partition and shows its contents.

Here is a sample command to create an RSA 2048 bit key with SHA256withRSA self-signed certificate. This example uses java 6, other versions might be slightly different.

keytool -genkeypair -alias keyLabel -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -storetype Luna -keystore bylabel.keystore -validity 365

Enter keystore password:

What is your first and last name?

[Unknown]: mike

What is the name of your organizational unit?

[Unknown]: appseng

What is the name of your organization?

[Unknown]: safenet

What is the name of your City or Locality?

[Unknown]: ottawa

What is the name of your State or Province?

[Unknown]: on

What is the two-letter country code for this unit?

[Unknown]: ca

Is CN=mike, OU=appseng, O=safenet, L=ottawa, ST=on, C=ca correct?

[no]: yes

Enter key password for <keyLabel>

(RETURN if same as keystore password):

With the Luna provider there is no concept of a key password and anything entered is ignored.

The following is a more elaborate sequence of keytool usage where the final goal is to have the private key generated in the HSM through keytool “linked” to its certificate.

Import CA certificate

It is mandatory to import the CA certificate – keytool verifies the chain before importing a client certificate:

my-sa5client:~/luna-keystores$ keytool -importcert -storetype Luna -keystore bylabel.keystore -alias root-ugoca -file Ugo_CA.crt

It is not required to import this certificate in the Java default cacerts keystore.

Generate private key

Generate the private key. It is NOT important that the sigalg specified matches the one used by the CA. You can also have OU, O, L, ST, and C different from the ones in the CA certificate.

my-sa5client:~/luna-keystores$ keytool -genkeypair -alias java-client2-key -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -storetype Luna -keystore bylabel.keystore

Enter keystore password:

What is your first and last name?

[Unknown]: java-client2

What is the name of your organizational unit?

[Unknown]: SE

What is the name of your organization?

[Unknown]: SFNT

What is the name of your City or Locality?

[Unknown]: bgy

What is the name of your State or Province?

[Unknown]: bg

What is the two-letter country code for this unit?

[Unknown]: IT

Is CN=java-client2, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT correct?

[no]: yes

Enter key password for <java-client2-key>

(RETURN if same as keystore password):

Verify that the private key is in the Luna partition:

my-sa5client:~/luna-keystores$ keytool -list -v -storetype Luna -keystore bylabel.keystore

Enter keystore password:

Keystore type: LUNA

Keystore provider: LunaProvider

Your keystore contains 2 entries

Alias name: root-ugoca

Creation date: Oct 4, 2012

Entry type: trustedCertEntry

Owner: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT

Issuer: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT

Serial number: 1

Valid from: Thu Oct 04 09:02:00 CEST 2012 until: Tue Oct 04 09:02:00 CEST 2022

Certificate fingerprints:

MD5: A2:15:4F:94:70:2B:D2:F7:C0:96:B1:47:F2:1D:03:E9

SHA1: B3:4A:68:0A:8D:12:39:86:11:CE:EF:22:1B:D1:DE:8D:E9:19:2B:F4

Signature algorithm name: SHA256withRSA

Version: 3

*******************************************

Alias name: java-client2-key

Creation date: Oct 4, 2012

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate[1]:

Owner: CN=java-client2, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT

Issuer: CN=java-client2, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT

Serial number: 506d42dd

Valid from: Thu Oct 04 10:03:41 CEST 2012 until: Wed Jan 02 09:03:41 CET 2013

Certificate fingerprints:

MD5: 7A:37:72:6B:8A:05:B6:49:91:70:0F:C4:04:1F:69:D9

SHA1: 05:CD:9F:A5:37:0B:A6:A3:65:24:56:40:5E:29:2D:95:2D:53:8F:5F

Signature algorithm name: SHA256withRSA

Version: 3

Create the CSR

Create the CSR to be submitted to the CA.

my-sa5client:~/luna-keystores$ keytool -certreq -alias java-client2-key -file client2-ugoca.csr -storetype Luna -keystore bylabel.keystore

Enter keystore password:

Now have the CSR signed by the CA. Have the issued certificate exported to include the certificate chain. Without the chain, keytool fails with the error:

java.lang.Exception: Failed to establish chain from reply

If you do not have the chain, you can use the steps in the section below to build the chain yourself.

To translate a PKCS#7 exported certificate from DER format to PEM format use the following:

my-sa5client $ openssl pkcs7 -inform der -in Luna_Key.p7b -outform pem -out Luna_Key-pem.p7b

Microsoft CA exports certificates with chain only in PKCS#7 PEM encoded format.

Import client certificate

Now import the client certificate:

user@myserver:~/luna-keystores$ keytool -importcert -storetype Luna -keystore bylabel.keystore -alias java-client2-key -file java-client2.crt

Enter keystore password:

Certificate reply was installed in keystore

Ensure that it is linked to the private key generated previously – the chain length is not 1 (“Certificate chain length: 2)

user@myserver:~/luna-keystores$ keytool -list -v -storetype Luna -keystore bylabel.keystore
Enter keystore password:

Keystore type: LUNA
Keystore provider: LunaProvider

Your keystore contains 2 entries

Alias name: root-ugoca
Creation date: Oct 4, 2012
Entry type: trustedCertEntry

Owner: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT
Issuer: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT
Serial number: 1
Valid from: Thu Oct 04 09:02:00 CEST 2012 until: Tue Oct 04 09:02:00 CEST 2022
Certificate fingerprints:
     MD5: A2:15:4F:94:70:2B:D2:F7:C0:96:B1:47:F2:1D:03:E9
     SHA1: B3:4A:68:0A:8D:12:39:86:11:CE:EF:22:1B:D1:DE:8D:E9:19:2B:F4
     Signature algorithm name: SHA256withRSA
     Version: 3

*******************************************
*******************************************

Alias name: java-client2-key
Creation date: Oct 4, 2012
Entry type: PrivateKeyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=java-client2, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT
Issuer: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT
Serial number: 5
Valid from: Thu Oct 04 10:07:00 CEST 2012 until: Fri Oct 04 10:07:00 CEST 2013
Certificate fingerprints:
      MD5: 4B:F0:9E:BC:EB:6A:88:2B:87:3A:76:35:7C:DE:4B:B4
      SHA1: F1:0C:BC:E3:A1:97:E4:8B:24:2D:44:43:7A:EA:71:52:B3:C3:20:D7
      Signature algorithm name: SHA256withRSA
      Version: 3
Certificate[2]:
Owner: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT
Issuer: EMAILADDRESS=ugo@computer.org, CN=Ugo CA, OU=SE, O=SFNT, L=bgy, ST=bg, C=IT
Serial number: 1
Valid from: Thu Oct 04 09:02:00 CEST 2012 until: Tue Oct 04 09:02:00 CEST 2022
Certificate fingerprints:
      MD5: A2:15:4F:94:70:2B:D2:F7:C0:96:B1:47:F2:1D:03:E9
      SHA1: B3:4A:68:0A:8D:12:39:86:11:CE:EF:22:1B:D1:DE:8D:E9:19:2B:F4
      Signature algorithm name: SHA256withRSA
      Version: 3

How to build a certificate with chain ...

When you receive the client certificate without the chain, it is possible to build a PKCS#7 certificate that includes the chain (and then feed it to keytool -importcert). In short, the “single” certificates without the chain can be “stacked” together by manually editing a PEM cert file; this PEM cert file can then be translated into a PKCS#7. How? Like this:

Prerequisites. Have all the certs in .crt format. The cert in this format is represented as an ASCII file starting with the line
-----BEGIN CERTIFICATE-----
and ending with
-----END CERTIFICATE-----
For example, if the client cert is issued by a subCA and the subCA is signed by a root CA, you will have 3 cert files – the client cert, the subCA cert, and the root CA cert. If the certs are not in .crt format, openssl can be used to transform the format that you have into .crt format. See notes below.
Open a new text file, calling it, for example, cert-with-chain.crt. Insert into this file the content of the certificates in the chains. For the above example, you must insert FIRST the client cert, THEN the subCA cert, THEN the root CA cert. The content of the file would then resemble the following:
-----BEGIN CERTIFICATE-----
             <-- client cert goes here
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
            <-- subCA cert goes here
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
            <-- root CA cert goes here
-----END CERTIFICATE-----
Use the following openssl command to convert the new certificate with chain, that you just created above, to a PKCS#7 certificate with chain:
my-sa5 $ openssl crl2pkcs7 -nocrl -certfile HSM_Luna-manual-chain.crt -out HSM_Luna-manual-chain.p7b -certfile root_CA.crt

Keytool is then able to import this .p7b certificate into the Luna keystore and correctly validate the chain.

Additional minor notes

Command to add a CA to the default CA cert store “cacerts”:
root@myserver:~# keytool -importcert -trustcacerts -alias root-ugoca -file /home/ugo/luna-keystores/Ugo_CA.crt -keystore /etc/java-6-sun/security/cacerts
Use the following openssl command to convert a PKCS#7 certificate DER-encoded into a PKCS#7 PEM-encoded certificate:
user@myserver:~/tmp/$ openssl pkcs7 -inform der -in java-client2.p7b -out java-client2-pem.p7b
Use the following openssl command to convert a PKCS#7 DER-encoded certificate into a .crt PEM certificate :
user@myserver:~/tmp/$ openssl pkcs7 -print_certs -inform der -in Ugo_CA.p7b -out Ugo_CA-p7-2-crt.crt
Use the following openssl command to convert a PEM certificate with chain to a PKCS#7 with chain:
user@myserver:~/tmp/$ openssl crl2pkcs7 -nocrl -certfile HSM_Luna-manual-chain.crt -out HSM_Luna-manual-chain.p7b -certfile Ugo_CA.crt

Show the Table of Contents