Open topic with navigation

Home >

SDK Reference Guide > Java Interfaces > Using Java Keytool with Luna HSM

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.

  1. 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/
  2. 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. ("Linux Luna Client Installation  ")

Alternatively, you can choose to perform JSP dynamic registration in your Java code. "JSP 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:  

  1. 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.   
  2. 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-----
  3. 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

  1. 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
  2. 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
  3. 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
  4. 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

 

 

 

 

 

Luna PCI-E 6.0 Product Documentation
007-011329-007 Rev. A May 2015 Copyright 2015 SafeNet, Inc. All rights reserved.

Open topic with navigation