ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
PrivateServer™ HSM Integration with Oracle WebLogic
January 2014
Document Version 1.3
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Notice The information provided in this document is the sole property of Algorithmic Research Ltd. No part of
this document may be reproduced, stored or transmitted in any form or any means, electronic,
mechanical, photocopying, recording or otherwise, without prior written permission from Algorithmic
Research Ltd.
Copyright © 2014 by Algorithmic Research Ltd. All rights reserved.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Table of Contents
Introduction .......................................................................................................................... 4
Requirements ....................................................................................................................... 4
PrivateServer Installation and Configuration ........................................................................ 5
PrivateServer Installation ........................................................................................................................... 5
PrivateServer Configuration ....................................................................................................................... 6
Signing Engine Configuration ..................................................................................................................... 8
Java Client Installation ............................................................................................................................. 10
Install Oracle WebLogic Server ........................................................................................... 11
Create New WebLogic Domain ................................................................................................................ 12
Configure WebLogic Server to Work with PrivateServer ..................................................... 13
Configure PrivateServer JCA/JCE provider ............................................................................................... 13
Generate a Keystore ................................................................................................................................ 14
Configure Oracle WebLogic Server .......................................................................................................... 15
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Introduction This step-by-step guide will help you set up ARX PrivateServerTM HSM as the signing engine for Oracle
WebLogic server. The WebLogic server will use ARX PrivateServer Hardware Security Module (HSM) to
store the sensitive RSA private key which is used to establish SSL connection between the WebLogic
server and its clients. Also, the private key can be used to sign outgoing messages. PrivateServer has a
standard JCE/JCE provider, which is used by the WebLogic server to perform all the required cryptography
on the HSM.
ARX PrivateServer is highly secure (FIPS 140-2 Level 3), high capacity, network attached, HSM that
provides a secure environment for data encryption and key management. PrivateServer conducts
sensitive cryptographic operations, secure key storage, and management of a large number of keys.
Requirements Two servers are required to set up your system:
ARX PrivateServer v4.8 or higher
Oracle WebLogic Server 10 and higher
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
PrivateServer Installation and Configuration The process of installing PrivateServer HSM and its client is described in full detail in the PrivateServer Installation and Operation Guide. Please refer to the manual for detailed description of each of the installation steps.
PrivateServer Installation
To set up your PrivateServer follow the steps below:
1. Install the PrivateServer client on a Windows machine by running the client setup.
2. Make sure that the following features are installed:
a. Legacy client
b. PrivateSafe USB driver
c. Signing Engine
3. Connect the USB smart card reader to the Windows machine.
4. Run the PrivateServer management application from All Programs -> ARX -> PrivateServer Client ->
PrivateServer Management.
5. Select Client -> Generate Cards and generate a set of smart cards (Root, init and Startup). For
more information refer to Chapter 4: Preparing Smartcards in the PrivateServer Installation and
Operation Guide. It is recommended to create backup for the Init and Startup smart cards.
6. Select Client -> Generate Users menu option and generate smart card for the administrative user
first. For more details refer to Chapter 4: Preparing Smartcards in the PrivateServer Installation
and Operation Guide.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
7. Initialize the PrivateServer with the newly generated set of smart cards (Init and Startup). For
more information refer to Chapter 5: Operating the System in the PrivateServer Installation and
Operation Guide.
8. Set the PrivateServer IP address. For more information refer to Chapter 6: Configuring the System
in the PrivateServer Installation and Operation Guide.
PrivateServer Configuration
Perform the following steps to create the WebLogic user in PrivateServer database:
1. Add your PrivateServer IP address to the servers list, from Client -> Add PrivateServer menu.
2. Select Server -> Connect to connect to the PrivateServer with administrative user.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
3. Select View -> Users to switch to the users view. Select User -> Create to create a user for the
WebLogic user, which will be the owner of the sensitive RSA key.
4. Enter the WebLogic user data. Usually, such user does not need any special authorizations, so you
can leave all authorization mask clear. However, since this is a critical user in the system, set the
Minimum Access Level to Non-secure LAN, authenticated and encrypted session. This setting will
require strong user authentication with software key media.
5. Click OK to create the WebLogic user.
6. Select Client -> Generate Users and generate software token key media for the WebLogic user.
For more details refer to Chapter 4: Preparing Smartcards in the PrivateServer Installation and
Operation Guide.
7. Test the key media by establishing an authenticated connection with the PrivateServer.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Signing Engine Configuration
The signing engine is a client side component that provides support for PKCS#11 API. This APIs is used by
the PrivateServer JCA/JCE provider to access the HSM and perform the required cryptographic
operations.
To configure the signing engine on the WebLogic machine:
1. Open the directory C:\Program Files\ARX\PrivateServer Client\extlogin\Encrypted_Pass and copy the
64 bit dll to the Windows\system32 directory and the 32 bit dll to the Windows\SysWow64 directory.
2. To create an encrypted password file run as administrator the genpass.exe utility from
C:\Program Files\ARX\PrivateServer Client\extlogin\Encrypted_Pass\win32 and enter the media
password. Make sure that the file cspass.dat was created in
C:\Program Files\ARX\PrivateServer Client\utils directory.
3. Select Client -> Settings menu and click on Signing Engine tab.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
4. Click New button to add a new slot.
a. In the Signing Engine group box choose Server Based and choose the IP of your PrivateServer from
the combo box.
b. In the Authentication Type group box choose File Media and enter the path to the software key
media of the WebLogic user.
c. In the User and Password Details group box enter the WebLogic user name.
d. Check Use Extended Login Module and enter extlogin.dll in the name of the extended login module.
5. Click Apply button to save your settings.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
6. Click Test button to check your configuration setting.
If the test fails check your configuration or restart the machine.
7. Press OK.
Java Client Installation
Verify that the Java feature is installed in the CryptoKit installation:
1. Go to Add remove programs in the Control panel.
2. Click on ARX CryptoKit.
3. Click Change and then select Modify option and click Next.
4. In the Application interface support verify that Java_API feature in installed. If not check it and
click Next.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Install Oracle WebLogic Server The following section describes the general steps needed to install Oracle WebLogic Server. For additional
information refer to Oracle documentation.
To install Oracle WebLogic Server do the following:
1. Download the Oracle WebLogic Server installer from
http://www.oracle.com/technetwork/middleware/weblogic/downloads/wls-main-097127.html
download Windows x86 with 32-bit JVM (1.2 GB) that includes Installers of Oracle WebLogic
Server, Oracle Coherence and Oracle Enterprise Pack for Eclipse.
2. Run the installation.
3. In the Oracle WebLogic welcome window, click Next.
4. Choose the Middleware Home Directory and click on Next.
5. If required, register for security updates and click Next.
6. Choose Install type Custom and click Next.
7. Select all the Products and components.
8. Select the local JDK and click Next.
9. Accept the default Product Installation directory and the home directory for the Oracle WebLogic
Server and then click Next.
10. Select the desired installation type and click Next.
11. To complete the installation, click Next and then Done.
12. To configure WebLogic Node Manager to run as an operating system service:
a. Copy the file nodemanager.properties to
($WEBLOGIC)\wlserver_10.3\common\nodemanager
b. Run the script: ($WEBLOGIC)\wlserver_10.3\server\bin\installNodeMgrSvc.cmd
($WEBLOGIC) specifies the location where WebLogic was installed, the default is
C:\Oracle\Middleware.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Create New WebLogic Domain
To create a new WebLogic domain, do the following:
1. Run the QuickStart from Start -> All Programs -> Oracle Enterprise Pack for Eclipse -> QuickStart.
2. Click on Getting Started with WebLogic Server, select Create a new WebLogic domain, and then
click Next.
3. Select Generate a domain configured automatically to support the following Oracle products and
then click Next.
4. Specify the name and location for the Domain.
5. In the Configure Administrator Username and Password window, specify a username and a
password, which must have a minimum length of 8 characters. Confirm the password and click
Next.
6. In the Configure Server Start Mode and JDK window, accept the defaults and click Next.
7. In the Select optional configuration window, accept the defaults and click Next.
8. In the Configuration summary window, click Create.
9. To complete the creation of the WebLogic Domain, click Done.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Configure WebLogic Server to Work with
PrivateServer To configure the WebLogic server to use PrivateServer you need to setup the PrivateServer JCA/JCE
provider, generate a set of RSA key and certificate and to configure the WebLogic server to use the new
key.
Configure PrivateServer JCA/JCE provider
1. Check where the WebLogic Server is installed ($WEBLOGIC), the default is C:\Oracle\Middleware.
2. Check where PrivateServer Client is installed ($PSV), the default is C:\Program Files\ARX.
3. Copy the PrivateServer JCA/JCE provider (arjca.jar and ckit.jar files) from $PSV\ARX
CryptoKit\JavaCkit to $WEBLOGIC\jdk160_29\jre\lib\ext.
4. Install the unlimited strength JCE jurisdiction policy files:
a. Download the archive containing the Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files from:
http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-
downloads-java-plat-419418.html#jce_policy-6-oth-JPR
b. Extract the local_policy.jar and US_export_policy.jar files from the Java Cryptography
Extension (JCE) Unlimited Strength Jurisdiction Policy File archive, and copy them into
$WEBLOGIC\jdk160_29\jre\lib\security.
5. Edit the Java security file java.security in the $WEBLOGIC\jdk160_29\jre\lib\security directory.
Find the place in the file where the list of installed providers is declared. It should look as follows:
security.provider.1=sun.security.provider.Sun
security.provider.2=…
In order to make ARX provider to be the default provider, for the functionalities it supports, put it
first in the list and adjust the priorities for others, so the list will look as follows:
security.provider.1=COM.arx.jca.ARJCA
security.provider.2=sun.security.provider.Sun
security.provider.3=…
6. Copy the arjca.conf file from $PSV\ARX CryptoKit\JavaCkit into the user home directory. For
example on Windows7: C:\Users\UserName.
Verify that the value of extractable parameter in the file is 0.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
Generate a Keystore
To generate a new set of server keys and certificate using Java Keytool:
1. Open a command line window and navigate to $WEBLOGIC\jdk160_29\jre\bin.
2. Generate a new keystore a self signed certificate and key pair by entering the command:
keytool -genkey -keystore ($HOME)\psvks -storepass 12345678
-alias psvalias -keypass 12345678 -keyalg RSA -keysize 2048
-sigalg SHA1withRSA -storetype ARJKS
You will be asked who is the Subject of the certificate request. The Common Name (CN) is the
first and last name and you must specify the name or IP address of the host machine.
3. Create a certificate request for the key that was created in the previous step by entering the
command:
keytool -certreq -alias psvalias -file ($HOME)\certreq.txt
-keypass 12345678 -keystore ($HOME)\psvks -sigalg SHA1withRSA
-storepass 12345678 -storetype ARJKS
4. Submit the certificate request to your Certificate Authority (CA) to receive a signed certificate.
5. Change the order of the installed providers in the java.security file and place COM.arx.jca.ARJCA in
the fifth position.
6. Import the Certificate Authority root certificate to the key store with the command:
keytool -import -trustcacerts -alias trustalias
–file ($HOME)\yourCA.cer -keystore ($HOME)\psvks
-storepass 12345678 -storetype ARJKS
Answer yes (Y) to the question: Trust this certificate? [no]:
7. Delete the self signed certificate that was generated in the first step from the HSM using the
PrivateServer Management utility.
8. Change the order of the installed providers in the java.security file and place COM.arx.jca.ARJCA in
the first position.
9. Import the signed certificate to the key store with the command:
keytool -import -alias "psvalias, 01"
-file ($HOME)\signedCert.cer -keystore ($HOME)\psvks
-storepass 12345678 -storetype ARJKS
Answer yes (Y) to the question: Trust this certificate? [no]:
If you already obtained a set of keys and certificates using Microsoft CAPI enrollment procedure, perform
the following:
1. Change the order of the installed providers in the java.security file and place COM.arx.jca.ARJCA in
the first position.
2. Open a command line window and navigate to $WEBLOGIC\jdk160_29\jre\bin.
3. Import the Certificate Authority root certificate to the key store with the command:
keytool -import -trustcacerts -alias trustalias
-file ($HOME)\yourCA.cer -keystore ($HOME)\psvks
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
-storepass 12345678 -storetype ARJKS
Answer yes (Y) to the question: Trust this certificate? [no]:
4. If the keys already appear in the HSM, get the alias of the private key by entering the command:
keytool –list –v –keystore ($HOME)\psvks -storepass 12345678
-storetype ARJKS
5. If the keys are in a pfx file perform the followings steps:
a. Get the alias of the private key that is in the pfx file by entering the command:
keytool -list –v -keystore ($HOME)\pfxfile.pfx
-storetype pkcs12
b. Import the private key and certificate in the pfx by entering the command:
keytool -importkeystore -srckeystore ($HOME)\pfxfile.pfx
-srcstoretype pkcs12 -srcstorepass 12345678 -srcalias "alias"
-destkeystore ($HOME)\psvks -deststoretype ARJKS
-deststorepass 12345678 -destalias psvalias
Configure Oracle WebLogic Server
1. Start Oracle WebLogic Server by performing one of the following:
a. Go to Start -> All Programs -> Oracle WebLogic -> WebLogic server -> tools -> WebLogic
scripting tools . A cmd window will open, enter the following commands:
- nmConnect('WebLogic', 'weblogic1', 'localhost', '5556',
'base_domain',
'C:/Oracle/Middleware/user_projects/domains/base_domain',
'plain') - nmStart('AdminServer')
b. Go to Start -> All Programs -> Oracle Enterprise Pack for Eclipse -> User Projects ->
your_doamin -> Start Admin Server for WebLogic Server Domain
In case this path doesn’t exist go to:
$WEBLOGIC \Middleware\user_projects\domains\your_domain and start the domain.
2. Open the Administration console by opening the browser and go to the address
(http://localhost:7001/console).
3. Connect to the server host with the credentials you have entered in the Creating the WebLogic
domain section.
4. Select Domain Structure > Environment > Servers and then click AdminServer.
5. In the General tab do the following:
a. Mark the checkbox SSL Listen Port enabled.
b. In SSL Listen Port, type 443, and then click Save button in the bottom of the page.
6. Select the Keystores tab and do the following:
a. Click the button change in the keystore option and select Custom Identity and Custom Trust
from the drop down menu.
ARX | 855 Folsom St. Suite 939, San Francisco, CA 94107 | Tel. (415) 839-8161 | www.arx.com | [email protected]
b. In Custom Identity Keystore, type the full path to your keystore.
c. In Custom Identity Keystore Type, type ARJKS.
d. In Custom Identity Keystore Passphrase, type 12345678 and confirm it.
e. In Custom Trust Keystore, type the full path to your keystore.
f. In Custom Trust Keystore Type, type ARJKS.
g. In Custom Trust Keystore Passphrase, type 12345678 and confirm it.
h. Click Save.
7. Select the SSL tab and do the following:
a. In the Private Key Alias, type the alias of the private key that you gave it during the creation in
previous step (psvalias).
b. In Private Key Passphrase, type 12345678 and confirm it.
c. Click Save.
8. Log out from the Administration console.
9. Restart the WebLogic Server.
10. Open the Administration console using https://localhost/console.
11. Check if the alias of the private key was changed by entering the command:
keytool -list –v -keystore ($HOME)\psvks
In case it has changed connect again to the server host like you connected in step 1 and perform
the following steps.
12. Connect again to the server host with the credentials you have entered in the Creating the
WebLogic domain section.
13. Select the SSL tab and change the Private Key alias to the new alias.
14. Restart the WebLogic Server.
15. Open the Administration console using https://localhost/console.