13 Integrating Hardware with Oracle Web Services Manager

This chapter describes hardware setup information. Hardware, such as SafeNet Luna SA, can be integrated with OWSM to provide a secure way to store keys and off-load cryptographic processing. Integrating OWSM with Oracle SPARC T5 and SPARC T4 Cryptographic Acceleration allows you to use the T5 and T4 processor based cryptographic capabilities. This delivers high-performance security for scenarios that rely on compute-intensive cryptographic operations, such as those imposed by transport-layer and message-layer protection policies.

This chapter includes the following sections:

13.1 Using Hardware Security Modules With OWSM

Hardware security modules (HSM) are certified to operate with Oracle Advanced Security. These modules provide a secure way to store keys and off-load cryptographic processing.

OWSM supports the SafeNet Luna SA HSM, which can be installed and configured as described in the following sections:

13.1.1 Understanding SafeNet Luna SA With OWSM for Key Storage

SafeNet Luna SA is a network-attached HSM featuring cryptographic processing and hardware key management for applications. Luna SA is designed to protect critical cryptographic keys across a wide range of security applications.

Some key advantages of using Luna SA with OWSM are:

  • Network shareability

  • Most secure with keys always in hardware

  • FIPS validated


You must contact your SafeNet representative to obtain certified hardware and software to use with Oracle Advanced Security.

By default, OWSM uses the Keystore Service (KSS) for key storage. Keys and certificates required by OWSM for cryptographic operations are fetched from a keystore file. When Luna SA is available in-network, it can be leveraged by OWSM for key storage purposes and cryptographic operations.

13.1.2 About Installing and Configuring the Luna SA HSM Client

The Luna SA HSM client needs to be installed on the host that has a running instance of OWSM. Then the Luna SA HSM client will communicate with an available Luna SA HSM network. However, this section does not cover Luna SA client installation, nor does it cover the Luna SA network installation and setup, which are out of scope for this document. Instead, you should refer to the Luna SA documentation for those instructions, at http://www.safenet-inc.com/Products/Detail.aspx?id=2147483853&terms=search.

Before installing the Luna SA HSM client, verify the following checklist:

  • You already have Luna SA installed and available in you network.

  • You are logged in as root or as a user that has installation permission.

  • You have a Luna SA client installation CD or software image.

  • You have all required passwords for Luna SA, including an administrator password and a partition password.


You must contact your SafeNet representative to obtain the hardware security module, and to acquire the necessary library.

These tasks must be performed before you can use a Luna SA hardware security module with OWSM.

13.1.3 Configuring the JRE Used By OWSM

After installing the Luna SA client, you need to configure the JRE that will be used by the OWSM setup. You must perform the following steps:

  1. Copy the following JAR files from the /usr/lunasa/jsp/lib directory to the $JAVA_HOME/jre/lib/ext directory:

    • LunaJCASP.jar

    • LunaJCESP.jar

  2. Copy the libLunaAPI.so file to the java.library.path.

  3. Edit the $JAVA_HOME/jre/lib/security/java.security file to include two Luna providers.

    To do so, add these two Luna providers at the end of the security.providers list:



    n specifies the preference order that determines the order in which providers are searched for requested algorithms when no specific provider is requested. The order is 1-based; 1 is the most preferred, followed by 2, and so on.

13.1.4 Logging On to Luna SA

Before you can use Luna SA with OWSM, you must log on to the Luna SA server. This is a one-time process that creates a Luna log-in session on the client machine. This session remains active until the client or server machine is rebooted, or when someone explicitly logs out of the Luna session.

You must use the salogin utility to log in. The salogin utility establishes a connection between the client and the HSM partition for a particular application. It takes an application ID as an argument. This application id consists of two parts: a high and a low ID.

Before invoking the salogin utility, you need to add an entry to the Chrystoki.conf file, which registers the application ID. The Chrystoki.conf file is usually found in the /etc/ directory. This is also a one-time process.

  1. Edit the /etc/Chrystoki.conf file by adding the application ID to the end of file. For example:

    Misc = { AppIdMajor=<major id>; AppIdMinor=<minor id>;  }
  2. Log into the Luna SA server, by entering:

    /salogin -o -s <partition number> -i <AppIdMajor>:<AppIdMinor> -v -p <partition_password>

    This opens a session for the application ID you provided. The salogin is in the /usr/lunasa/bin directory.

  3. To log out of the Luna SA server, enter:

    salogin -c -s <slot number> -i <AppIdMajor>:<AppIdMinor>

13.1.5 Copying Keys and Certificates to Luna SA

If keys and certificates are currently in a KSS or JKS keystore, then you need to move all keys and certificates to Luna SA. You can use the cmu script provided by LunaSA for importing keys and certificates.

  • The cmu importKey command imports an RSA|DSA private key from a file onto an HSM. (Supports PKCS12(RSA), PKCS8(RSA/DSA), or PKCS1(RSA)).

  • The cmu import command imports an X.509 certificate from a file onto an HSM.


The cmu script imports from a file. Therefore, before you can import the keys and certificates into Luna SA, you must first export them to a file from a KSS or JKS keystore.

13.1.6 Configuring OWSM to Use Luna SA

As part of configuring OWSM to use Luna SA, you need to configure the OWSM domain to use the Luna HSM instead of the default KSS keystore. For more information, see the following topics:

13.2 Configuring OWSM for Oracle SPARC T5 and SPARC T4 Cryptographic Acceleration

OWSM supports the use of Oracle SPARC T5 and SPARC T4 processor-based servers, which eliminate the need for third-party security hardware by integrating computing, security, and I/O on a single chip. Deploying OWSM on Oracle SPARC T5 and SPARC T4 based servers transparently leverages the SPARC T5 and T4 processor based cryptographic capabilities. This delivers high-performance security for scenarios that rely on compute-intensive cryptographic operations, such as those imposed by transport-layer and message-layer protection policies.

This section describes how to configure OWSM to take advantage of cryptographic acceleration capabilities of Oracle SPARC T5 and SPARC T4 processor-based servers.

This section applies only to users who are running Oracle SPARC T5 and T4 processor-based servers running Oracle Solaris 10 8/11 or later.

The following topics are described:

13.2.1 Terms You Need to Understand

This section uses the following terms that you need to understand. Refer to the white paper described in Section 13.2.5, "Additional Reading" for a complete discussion of these terms.

  • PKCS#11 token — A token that generically refers to all the hardware and software tokens that implement the PKCS#11 API. The PKCS#11 API is an RSA standard for integrating hardware cryptographic accelerators, cryptographic tokens (for example, SCA-6000), and smart cards.

    A software based PKCS#11 token is a PKCS#11 token implemented entirely in software (for example, Solaris PKCS11 Softtoken.)

  • Solaris Cryptographic Framework — The Solaris Cryptographic Framework (SCF) library plays a vital role in providing application access to hardware-assisted cryptographic acceleration provided by Oracle T-series processors and Hardware Security Modules (HSM), including the Oracle Sun Crypto Accelerator 6000 PCIe Card (SCA-6000) and third-party HSMs. SCF is based on PKCS#11 standard interfaces and provides a set of cryptographic services for kernel-level and user-level consumers to perform cryptographic operations.

13.2.2 Overview of Oracle SPARC T5 and SPARC T4 Hardware Assisted Cryptographic Acceleration

The Oracle SPARC T5 and SPARC T4 processors are part of Oracle's SPARC T-series processors family, which combines multiprocessing at the processor core level and hardware multithreading inside of each core with an efficient instruction pipeline to enable Chip Level Multi-Threading (CMT). These processors present a unique "System-on-a-Chip" design principle that incorporates specialized features such as on-chip/on-core cryptographic acceleration, 10 Gigabit Ethernet networking, and hardware-enabled virtualization capabilities. Each core of the Oracle SPARC T5 and SPARC T4 processors contains a Stream Processing Unit (SPU) to perform processing of cryptographic operations at the same clock speed as the core. The SPU is designed to achieve wire-speed encryption and decryption on the processor's 10 GbE ports.

Configuring and deploying OWSM on Oracle SPARC T5 and SPARC T4 based servers delivers high performance by leveraging the on-core cryptographic instructions to perform computationally intensive cryptographic operations as part of web service security transactions using SSL and WS-Security mechanisms. For example, all message protection policies are computationally intensive.

OWSM makes use of SPARC T5 and SPARC T4 processor based cryptographic acceleration in the following scenarios:

  • Transport-level security, as described in Section 13.2.3, "Configuring Transport-Level Security for Cryptographic Acceleration."

    The SPARC T5 and SPARC T4 processor on-core cryptographic acceleration capabilities can be accessed in a variety of ways by the OWSM deployment, depending on the applied security scenarios and its requirements. The availability of Oracle Ucrypto provider features and the Sun PKCS#11 interfaces in the Java Cryptography Extension (JCE) framework enable OWSM and WebLogic Server to take advantage of hardware-assisted cryptographic acceleration of SSLv3/TLSv1 and WS-Security-based cryptographic workloads.

    With the release of JDK7 update 4, Oracle introduced Oracle Ucrypto provider, which provides a specialized interface that bypasses PKCS#11 and automatically leverages hardware-assisted cryptographic acceleration capabilities of Oracle's SPARC T4 and SPARC T5 (or newer) processors. In a typical JDK7 installation (JDK7u4 or later) on Oracle Solaris 11 (SPARC), the Java Runtime Environment is preconfigured to make use of the Oracle Ucrypto provider by default. This enables the Java and Oracle WebLogic Server-hosted applications and XML web services to automatically delegate their cryptographic-intensive operations processed via Oracle Solaris Cryptographic Framework using Oracle SPARC T5- and SPARC T4-based on-core cryptographic instructions.

    In JDK6, the Java PKCS#11 interfaces help to off-load and accelerate the compute-intensive cryptographic workloads of SSL/TLS protocols by leveraging the on-core cryptographic instructions of SPARC T5 and SPARC T4 processors.

  • Message-level security, as described in Section 13.2.4, "Configuring Message-level Security for Cryptographic Acceleration."

    Message-level security builds on cryptographic operations that support Web Services security standards such as WS-Security, WS-SecurityPolicy, and WS-Trust.

    In particular, web services security makes use of public-key encryption, digital signature (for example, RSA, DSA and ECC), bulk encryption (for example, AES, 3DES, and DES) and message digest (for example, SHA-1, SHA-2, and MD5) functions intended for supporting XML encryption, XML digital signature and related cryptographic operations.

    OWSM implements a dedicated PKCS#11 interface to delegate cryptographic operations (via SCF) to on-core cryptographic instructions of SPARC T4 processor.

13.2.3 Configuring Transport-Level Security for Cryptographic Acceleration

You need to perform the following tasks to configure cryptographic acceleration for transport-level security:

  1. Configure the WebLogic Server keystore, as described in "Configure keystores" in the Oracle WebLogic Server Administration Console Online Help.

    Choose "Custom Identity and Java Standard Trust" and Java KeyStore (JKS).

  2. Enable JSSE SSL for WebLogic Server.

    Using JSSE based SSL automatically leverages the SunPKCS11 provider implementation pre-configured with the Java runtime environment on Solaris SPARC.

    See "Using the JSSE-Based SSL Implementation" in Administering Security for Oracle WebLogic Server for the steps to follow.

  3. In a typical WebLogic Server installation on SPARC Solaris, the Java runtime environment is pre-configured to make use of the Oracle Ucrypto Provider (JDK7) or SunPKCS11 provider.

    To leverage the Oracle Ucrypto provider, you must use JDK7 update 4 (or later) as the Java Runtime Environment on Oracle Solaris 11. Make sure that the Oracle Ucrypto provider is identified as the default provider in the Java security properties file java.security located in the $JAVA_HOME/jre/lib/security/ directory.

  4. If using JDK6, confirm the use of the SunPKCS11 provider.

    The SunPKCS11 provider is a Java based PKCS#11 implementation that integrates with underlying PKCS#11 implementations provided by the SCF and its exposed cryptographic providers.

    In a typical WebLogic server installation on Solaris, the Java runtime environment is pre-configured to make use of the SunPKCS11 provider.

    Therefore, make sure that the SunPKCS11 provider is listed as the first provider in the $JAVA_HOME/jre/lib/security/java.security properties file:

    security.provider.1=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/sunpkcs11-solaris.cfg

    The relevant portion of the default Solaris $JAVA_HOME/jre/lib/security/java.security file is shown in the following example of a partial java.security file.

    # List of providers and their preference orders (see above):
    security.provider.1=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/sunpkcs11-solaris.cfg
  5. Restart WebLogic Server.

  6. Verify that the SSL configuration is working.

13.2.4 Configuring Message-level Security for Cryptographic Acceleration

You need to perform the following tasks to configure cryptographic acceleration for message-level security:

  1. From the Solaris command line, create a PKCS11 keystore.

    To create and initialize a PKCS11 keystore, use the pktool setpin command.

    When you specify keystore=pkcs11, the keystore defaults to "Sun Software PKCS#11 softtoken."

    If the softoken keystore has not yet been initialized, use "changeme" as the original passphrase.

    # pktool setpin keystore=pkcs11
    Enter token passphrase:
    Create new passphrase:
    Re-enter new passphrase:
    Passphrase changed.
  2. Generate private keys for the keystore.

    # pktool genkeypair keystore=pkcs11 keytype=rsa keylen=1024 hash=sha1
  3. Alternatively, you can choose to import the key from a Java keystore to the Solaris Softtoken keystore by using the following command.

    # keytool –importkeystore
    -srckeystore /opt/Oracle/Middleware/default-keystore.jks
    -destkeystore NONE -srcstoretype JKS
    -deststoretype PKCS11
            -srcstorepass changeme -deststorepass your-scfpassword
  4. From the Solaris command line, verify that the keys are present in the Solaris Softtoken keystore.

    keytool -list -storetype pkcs11 -keystore NONE
  5. Make sure that the algorithm suites of the policies you use are not in the disabledMechanisms list in the $JAVA_HOME/jre/lib/security/sunpkcs11-solaris.cfgsunpkcs11-solaris.cfg configuration file.

    For example, if the specified algorithm suite for a policy is Basic256Rsa15 as shown in Figure 13-1, it uses Aes256 encryption and KwAes256/kwRsA15 for key wrap. In this case, make sure that CKM_AES is not in the disabledMechanisms list in the configuration file.

    Figure 13-1 Sample Algorithm Suite

    Description of Figure 13-1 follows
    Description of ''Figure 13-1 Sample Algorithm Suite''

    See Appendix A Sun PKCS#11 Provider's Supported Algorithms in the Java PKCS#11 Reference Guide for the list of supported algorithms.

  6. Configure the OWSM keystore to use the PKCS11 keystore as described in the following sections:

  7. Verify the configuration.

    To ensure the hardware-assisted cryptographic acceleration is correctly configured and working, use the following Solaris DTrace script.

    #!/usr/sbin/dtrace -s 
      @[probefunc] = count(); 

    Save this script as a file named cryptoverify.d. Run this script with the WebLogic Server's Java process ID as a command line argument, as follows:

    # dtrace -s cryptoverify.d  <WeblogicServer Process ID>

    For example, in an encryption scenario using the AES algorithm, a positive and growing value of AES jobs indicates that cryptographic acceleration is operational on the target AES bulk encryption payloads.

13.2.5 Additional Reading

The whitepaper is the definitive source for cryptographic acceleration information for using Oracle SPARC T-series processor based servers.

The whitepaper covers many additional pertinent topics such as Solaris Cryptographic Framework components, using Solaris Kernel SSL (KSSL), Apache Web Server, Oracle Database Transparent Data Encryption and performance characteristics.

You can refer to the following whitepapers for more information: