Sunday, December 16, 2012

Key Generation using ERACOM and Keytool


Java Keystore (keytool) setup

1       Introduction

A keystore is a password-protected file which stores the keys and certificates. The keytool application can import, export and list the contents of a keystore. The keytool can also be used to generate self-signed certificates for test purposes.
Following are the keytool command attributes:
§  -genkey (Java 1.5) or –genkeypair (Java 1.6): This flag generates a key pair (a public key and associated private key). Wraps the public key into an X.509 v3 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.
§  -genseckey (Java 1.6): The –genseckey flag generates a secret key and stores it in a new entry identified by the name specified in the –alias flag.
§  -keyalg: keyalg specifies the algorithm to be used to generate the key. The default value of –keyalg when –genkey / –genkeypair flag is set, is “DSA”, while the value is “DES” when –genseckey flag is set.
NOTE: AES\DES algorithms are not available in Java 1.5.0
§  -keysize: The –keysize specifies the size of each key to be generated. By default the value is 1024 (when using –genkey / –genkeypair), 56 (when using -genseckey and -keyalg is "DES") and 168 (when using -genseckey and -keyalg is "DESede").
§  -alias: The –alias flag refers to a particular entity in the keystore.
§  –validity: Certificates generated by the system are valid for just under 90 days by default. The flag –validity allows to change the length of validity for a certificate to n days.
§  -keystore: The keytool uses as default a keystore file ".keystore" located in the user’s home directory. To use another keystore file use the -keystore flag.
§  -storetype:  The flag specifies the key store type that should be used. Below are the supported keystore types:

Sr
Store Type
Description
1
JKS
Java KeyStore. Oracle's KeyStore format. It is the Default keystore type.
2
JCEKS
Java Cryptography Extension KeyStore. More secure version of JKS.
3
PKCS12
Public-Key Cryptography Standards #12 KeyStore. RSA's KeyStore format.
4
PKCS12S2
It is a second version of PKCS12 type keystore.
5
JCERACFKS
Java Cryptography Extension RACF KeyStore. It is a RACF (Resource Access Control Facility) keying keystore and is available only on z/OS systems with RACF installed.

§  -list: The –list flag is used to list the content of the keystore.
§  -delete: The flag is used to delete the keystore the entry identified by alias flag. The user is prompted for the alias, if no alias is provided at the command line.

2       Creating a RSA Key

RSA is a public-key cryptography based on factoring large integers. Both DSA and RSA algorithms can be used to generate key-pairs using –genkey or   -genkeypair. The commands to generate RSA Keys in the Java Keystore are as follows:
·         Generate an RSA keypair: 

keytool -genkey -alias RSAKey -keyalg RSA -validity 365 -keystore keystore/msmkeystore.jks

·         Enter keystore password: mysecret

What is your first and last name?

      [Unknown]: www.mobilefish.com

What is the name of your organizational unit?

      [Unknown]:Research and Development

What is the name of your organization?

      [Unknown]: Mobilefish.com

What is the name of your City or Locality?

      [Unknown]: Zaandam

What is the name of your State or Province?

      [Unknown]: Noord-Holland

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

      [Unknown]: NL

Is CN=www.mobilefish.com, OU=Research and Development, O=Mobilefish.com, L=Zaandam, ST=Noord-Holland, C=NL correct?

      [no]: y



Enter key password for <RSAKey>

         (RETURN if same as keystore password):

·         To view the fingerprints of certificates in the keystore, type:

keytool -list -keystore keystore/msmkeystore.jks

·         To view the personal information about the issuer and owner of the certificate, type:

keytool -list -v -keystore keystore/msmkeystore.jks

·         To remove entries from the keystore, enter the following command:

keytool -keystore keystore/msmkeystore.jks -delete –alias RSAKey



3       Creating a AES (or DES) Key (Java 1.6.0)
AES is a symmetric key algorithm; hence we prefer to generate a single secret key using the flag –genseckey. Further, the default Keystore type is JKS for the Java keytool which cannot store symmetric keys. Hence the keystore type is changed to JCEKS for AES encryption algorithm. The commands to generate AES Keys in the Java Keystore are as follows:
·         Generate the secret key (Using AES as encryption algorithm): 

 keytool -genseckey -alias AESKey -keyalg AES -keysize 128  -validity 365 -keystore keystore/msmkeystore.jks -storetype JCEKS

·         To view the fingerprints of certificates in the keystore, type:

keytool -list -storetype JCEKS

NOTE: AES keysize should be 128 bit in order for the SunJCE / IBMJCE Provider to initialize the key.

4       Mobile Security Properties
  •          JCEProvider.KeyStoreProvider: Name of the Provider for cryptology operations. Eg: SunJCEProvider or IBMJCE.
  •          JCEProvider.KeyStoreFile: Path to JKS Keystore
  •          JCEProvider.KeyStorePIN: PIN for JKS Keystore
  •          JCEProvider.TokenPIN: PIN for Key Token in JKS Keystore
  •          JCEProvider.CryptoKey.Alias: Alias Name for Key in JKS Keystore
  •          JCEProvider.CryptoKey.CipherAlgorithm: Algorithm for generating the Alias Key
  •          JCEProvider.CryptoKey.CipherMode: Mode to be used during encryption or decryption using the Alias Key
  •          JCEProvider.CryptoKey.CipherPadding: Padding type to be used during encryption or decryption using the Alias Key


5       Notes
1         Symmetric cannot be generated using keytool for Java 1.5.0.
2         The keystore generated from the keytool of Java 1.6.0 cannot be used for the application running Java 1.5.0 (and vice versa).
3         Sun and IBM JCE Providers supports PKCS5Padding for AES but support PKCS1Padding for RSA.
4         The IBM Websphere JDK does not comes with JCE Provider or any other SUN Provider, but is substituted by IBMJCE Provider and other IBM versions of the providers (IBMPKCS11, IBMJSSEProvider etc). Adding SUNJCE Providers to IBM Websphere application library may cause java.lang.UnsatisfiedLinkError: sun/misc/Unsafe.registerNatives().
5         IBM JCE Provider (and probably others) does not allow private keys for encryption and public key for decryption.
6         IBM JCE Provider used with RSA algorithm (PKCS1Padding and ECB mode) and public key used for encryption while private key used for decryption gives the following exception: javax.crypto.BadPaddingException: Not PKCS#1 block type 2 or Zero padding
7         Path for the msmkeystore.jks can be specified as (classes\\certs\\msmkeystore.jks) for Windows but should be specified as (classes/certs/msmkeystore.jks) for Linux in ‘300-mobile-security.properties’.



LINUX: ERACOM Hardware Security Module setup

1       Installation

1         Install PTKC Runtime and PTKC SDK Package from “Eracom 3.3” Folder.
2         Install PTKJ Runtime and PTKJ SDK Package from “PTKJ3.06” Folder.
3         Install an additional package called PCI HSM-Provider from “\Eracom 3.3\pci_hsm_access_provider” Folder if using a real HSM board.
Sample installation commands:
Sample installation commands:
mount -o loop 007553-003MI_ptkc.iso /mnt/eracom
./safeNet-install.sh
chmod a+x eracom-install.sh
./eracom-install.sh

NOTE: IT IS IMPORTANT THAT THE ERACOM SOFTWARE SHOULD BE INSTALLED WITH THE SAME USER PERMISSIONS AS THE WEBSPHERE USER IN THE LINUX BOX.

2       HSM Slot and Key Creation Commands:
1)      ctconf –c3
Create a new User slot (Creates slot 3).
2)      ctstat
Show the status of the Tokens and the Objects in the Protect Toolkit.
3)      ctconf –n3 
Initialize the token in the specified slot (Here Slot 3).
4)      ctkmu p –s3 
     Initialize the User PIN or to change an existing PIN (either the User or SO PIN). If the specified slot (Here Slot 3) contains a token without an initialized user PIN this command will prompt for the current SO PIN and then for the new User PIN (123456) . If the PIN is initialized the current PIN will be prompted for before the new PIN may be specified.
5)      ctkmu c –s3 -t aes -z128 -n AESTestKey03 –aWUxED
(c) Create a (–aWUxED) CKA_WRAP, CKA_UNWRAP, CKA_EXPORTABLE, CKA_ENCRYPT and CKA_DECRYPT Key of (-t) type “aes” and (-z) size “128”, with the (-n) name “AESTestKey03” in (-s3) slot number 3.

AVAILABLE KEYS:

Single Key Types
Key Pair Types
DES
RSA (Public)
Double DES
RSA (Private)
Triple DES
DSA (Public)
AES  (16, 24, or 36 bytes)
DSA (Private)
IDEA
DH (Public)
CAST128 (1 to 16 bytes)
DH (Private)
RC2 (1 to 128 bytes)
EC (Public)
RC4 (1 to 256 bytes)
EC (Private)
SEED


6)      ctkmu l –s3 
List the keys or the objects stored on the token in the specified slot.  Lists actual keys and certificates in the specified slot.
7)      ctkmu c –s3 -t aes –k 2 -z128 -n WrapKey –aWUxED
(c) Create a (–aWUxED) CKA_WRAP, CKA_UNWRAP, CKA_EXPORTABLE, CKA_ENCRYPT and CKA_DECRYPT Key of (-t) type “aes”, (-k) –num-comp and (-z) size “128”, with the (-n) name “AESTestKey03” in (-s3) slot number 3.
Note: -K option corresponds to the number of key components required to be entered or number to be generated (when –g parameter is specified).

3       Copy Jar and Lib files to JRE:
Here ““/opt/” is considered as the installed location of Websphere and Eracom PTKC and PTKJ SDK. Please change the path depending on the path of installation on the System.
1)      Copy jprov.jar from “/opt/ERACjprov/lib” to “/opt/WebSphere/70/java/jre/lib/ext”
2)      Copy jcprov.jar from “/opt/PTK/lib” to “/opt/WebSphere/70/java/jre/lib/ext”
3)      Copy libcryptoki.so from “/opt/PTK/lib” to “/opt/WebSphere/70/java/jre/lib/ext”
4)      Copy libjcprov.so from “/opt/PTK/lib” to “/opt/WebSphere/70/java/jre/lib/ext”
5)      Copy libjcryptoki.so from “/opt/PTK/lib” to “/opt/WebSphere/70/java/jre/lib/ext”
6)      Sample Commands:
cd /opt/PTK/lib
cp -i jcprov.jar  /opt/WebSphere/70/java/jre/lib/ext
cp  libcryptoki.so  /opt/WebSphere/70/java/jre/lib/ext
cp -i libjcryptoki.so  /opt/WebSphere/70/java/jre/lib/ext
cp -i libjcprov.so  /opt/WebSphere/70/java/jre/lib/ext

NOTE: FOLLOWING FILES ARE SPECIFICALLY FOR HSM SW SIMULATOR. YOU MAY NEED TO COPY ADDITIONAL FILES FOR THE ACTUAL HSM BOARD. PLEASE REFER THE MANUAL FOR DETAILS.

4       Add EracomProvider Entry to Java Security:
1)      Go to Websphere JRE and find the java.security file under {WEBSPHERE_HOME}/70/java/jre/lib/security Folder
2)      Add the following entry to the java.security file under “List of providers” section  security.provider.13=au.com.eracom.crypto.provider.slot0.ERACOMProvider
Note: Please change the number of the provider from “13” to the next number from the last provider in the list.

5       Setting up the Library Path:
Please add the following shell commands to the Server Startup Script
LD_LIBRARY_PATH=/opt/PTK/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
PATH=/opt/PTK/bin:$PATH
export PATH
Here “/opt/PTK/lib” and “/opt/PTK/bin” paths depends on the path of installation of PTKC SDK Package on the System.
For Example the Server Startup Script is located in /opt/wasapps/was/70/profiles/NFCSrv01/bin/startServer.sh
Add the above lines in Blue at the start of such startServer.sh script

NOTE: RESTART THE WEBSPHERE TO SET THE LIBRARY PATH


WINDOWS: ERACOM Hardware Security Module setup
1       Creation of Slots:
  1. Go to gCtAdmin (SW) and open Adapter Management.
  2. Then select File -> Create Slots
  3. Enter the number of slots to be created, the slots are created and it will go to login again.
  4. Then go in Edit -> Tokens, select the Slot which is uninitialized token.
  5. Press “Initialise”, enter the Token label, Security Officer and User Pin.
  6. The user pin is used to access the slot for encryption and decryption in MSM.
  7. Click “Done” to finish. Hence Slot is created and initialized successfully.


2       Creation of Secret Keys:
  1. Go to KMU(SW) to open Key Management Utility. And select the token with the label name specified before.
  2. In case if it shows an exception go to step 3 to initialize the token using CRYPTOKI Utility.
  3. Else enter the User PIN.
  4. From the top menu tool bar, select “Secret Key” for AES Key or Key Pair for Public-Private Key.
  5. For “Secret Key”, select the Mechanism as "AES", Label Name (Key Alias), Key Size (128) and make sure to select "Encrypt", "Decrypt" options to enable it for encryption and decryption.
  6. Press Ok to successfully create the Eracom Secret Key.


3       Testing the Keys:
  1. Go to Browser (SW) i.e. CRYPTOKI Token Browser
  2. Skim through the branches to find the slot created earlier.
  3. Right Click on the slot label and select “init token”, and say Ok (for all keys and PIN setup for the slot are erased).
  4. To find all the keys in the slot, double click on the "Objects" label and all the keys under the slot will appear.
  5. We can copy or delete the key and use it for Encryption and Decryption.

 References
o   Oracle Java SE Documentation: keytool - Key and Certificate Management Tool
o   IBM Guide: keytool - Key and Certificate Management Tool
o   Java Quick Guide
o   The Most Common Java Keytool Keystore Commands

Posted by at
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)