privateserver™ hsm - docusign of privateserver with... · 3. in the oracle weblogic welcome...

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


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.


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


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


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.


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.


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.


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.


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.


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.


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.

http://www.oracle.com/technetwork/middleware/weblogic/downloads/wls-main-097127.html


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.


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.

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#jce_policy-6-oth-JPR

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#jce_policy-6-oth-JPR


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


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.


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



If you already obtained a set of keys and certificates using Microsoft CAPI enrollment procedure, perform

the following:


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




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.

http://localhost:7001/console


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.

https://localhost/console

https://localhost/console

privateserver™ hsm - docusign of privateserver with... · 3. in the oracle weblogic welcome...

Documents