Migrating to the JCE Framework

A Migrating to the JCE Framework

The Oracle Security Developer Tools framework introduced changes to low-level libraries starting in 11g Release 1 to comply with the Java Cryptography Extension (JCE) framework. The changes affected both client programs and higher-level libraries of the Oracle Security Developer Tools. You can migrate your legacy programs to leverage the JCE functions.

This chapter describes how the changes affected the toolkit architecture, and explain how you can migrate your legacy programs to leverage the JCE functions. It contains these topics:

A.1 About The JCE Framework

Prior to Oracle Fusion Middleware 11g, Oracle Security Developer Tools used a cryptographic engine that was developed prior to the adoption of JCE in the market. To enable applications (including Oracle WebLogic Server) to continue their move to adopt JCE, the Oracle Security Developer Tools have standardized on low-level libraries that are compliant with the Java Cryptography Extension (JCE) framework with Oracle Fusion Middleware 11g.

Benefits of the JCE framework include:

standards-based implementations of cryptographic and certificate management engines
a pluggable JCE provider architecture that enables you to leverage third-party JCE provider implementations
the ability to use third-party providers as the cryptographic engine

Additional Reading

This chapter’s primary focus is on the changes to the Oracle Security Developer Tools for the JCE framework, and how to migrate your existing security artifacts to JCE objects.

A.2 Understanding JCE Keys

As of Release 11gR1, the higher level toolkits (Oracle XML Security, Oracle Web Services Security, Oracle CMS, Oracle S/MIME, Oracle XKMS) have changed so that instead of taking Oracle cryptographic keys and certificates, they take standard JCE keys and certificates.

Thus, APIs that were taking:

oracle.security.crypto.core.PublicKey

now take a:

java.security.PublicKey

Note:

This discussion highlights changes in the Oracle Security Developer Tools in support of JCE. For fuller details of all the available cryptographic functions, see the API documentation.

oracle.security.crypto.core.PublicKey changed to java.security.PublicKey
oracle.security.crypto.core.PrivateKey changed to java.security.PrivateKey
oracle.security.crypto.core.SymmetricKey changed to javax.crypto.SecretKey

A.3 Converting Between OSDT Key Objects and JCE Key Objects

You can convert keys from Oracle Security Developer Tools (OSDT) objects to JCE objects and vice versa.

If you are using a java.security.KeyStore to store your keys, you will directly get a java.security.PrivateKey object from it, so you do not need to do any conversion.

However if you are using a oracle.security.crypto.cert.PKCS12 object to store your keys, you will get an oracle.security.crypto.core.PrivateKey from it, and then you need to convert to a java.security.PrivateKey object.

A.3.1 Converting a Private Key from OSDT to JCE Object

You can convert keys in Oracle Security Developer Tools (OSDT) format to JCE objects.

Here is an example:

//***** Conversion of PrivateKeys from OSDT -> JCE *******
{
// Example code to convert an RSAPrivateKey (non CRT) to JCE
oracle.security.crypto.core.RSAPrivateKey osdtKey = null;
RSAPrivateKeySpec keySpec = new RSAPrivateKeySpec(
osdtKey.getModulus(), osdtKey.getExponent());
KeyFactory kf = KeyFactory.getInstance("RSA");
RSAPrivateKey jceKey = (RSAPrivateKey)kf.generatePrivate(keySpec);
}
 
{
// Example code to convert an RSAPrivateKey (CRT) to JCE
oracle.security.crypto.core.RSAPrivateKey osdtKey = null;
RSAPrivateKeySpec keySpec = new RSAPrivateCrtKeySpec(
osdtKey.getModulus(),
osdtKey.getPublicExponent(),
osdtKey.getExponent(),
osdtKey.getPrimeP(),
osdtKey.getPrimeQ(),
osdtKey.getPrimeExponentP(),
osdtKey.getPrimeExponentQ(),
osdtKey.getCrtCoefficient());
KeyFactory kf = KeyFactory.getInstance("RSA");
RSAPrivateCrtKey jceKey = (RSAPrivateCrtKey)kf.generatePrivate(keySpec);
 
}
 
{
// Example code to convert a DSAPrivateKey to JCE
oracle.security.crypto.core.DSAPrivateKey osdtKey = null;
DSAPrivateKeySpec keySpec = new DSAPrivateKeySpec(
osdtKey.getX(),
osdtKey.getParams().getP(),
osdtKey.getParams().getQ(),
osdtKey.getParams().getG());
 
KeyFactory kf = KeyFactory.getInstance("DSA");
DSAPrivateKey jceKey = (DSAPrivateKey)kf.generatePrivate(keySpec);
 
}
 
{
// Example code to convert a DHPrivateKey to JCE
oracle.security.crypto.core.DHPrivateKey osdtKey = null;
 
// Note q is assumed to be (p-1)/2
DHPrivateKeySpec keySpec = new DHPrivateKeySpec(
osdtKey.getX(),
osdtKey.getParams().getP(),
osdtKey.getParams().getG());
 
KeyFactory kf = KeyFactory.getInstance("DiffieHelman");
DHPrivateKey jceKey = (DHPrivateKey)kf.generatePrivate(keySpec);
 
}

A.3.2 Converting a Private Key from JCE Object to OSDT Object

You can convert private key objects from JCE to OSDT format.

Here is an example:

//***** Conversion or Private Keys from JCE -> OSDT *******
{
// Example code to convert an RSAPrivateKey (non CRT) to OSDT
RSAPrivateKey jceKey = null;
oracle.security.crypto.core.RSAPrivateKey osdtKey =
new oracle.security.crypto.core.RSAPrivateKey(
jceKey.getModulus(),
jceKey.getPrivateExponent());
}
 
{
// Example code to convert an RSAPrivateKey (CRT) to OSDT
RSAPrivateCrtKey jceKey = null;
oracle.security.crypto.core.RSAPrivateKey osdtKey =
new oracle.security.crypto.core.RSAPrivateKey(
jceKey.getModulus(),
jceKey.getPrivateExponent(),
jceKey.getPublicExponent(),
jceKey.getPrimeP(),
jceKey.getPrimeQ(),
jceKey.getPrimeExponentP(),
jceKey.getPrimeExponentQ(),
jceKey.getCrtCoefficient());
}
 
{
// Example code to convert an DSAPrivateKey to OSDT
DSAPrivateKey jceKey = null;
oracle.security.crypto.core.DSAPrivateKey osdtKey =
new oracle.security.crypto.core.DSAPrivateKey(
jceKey.getX(),
new oracle.security.crypto.core.DSAParams(
jceKey.getParams().getP(),
jceKey.getParams().getQ(),
jceKey.getParams().getG()));
}
 
{
// Example code to convert an DHPrivateKey to OSDT
DHPrivateKey jceKey = null;
 
// Note calculate q = (p-1)/2
oracle.security.crypto.core.DHPrivateKey osdtKey =
new oracle.security.crypto.core.DHPrivateKey(
jceKey.getX(),
new oracle.security.crypto.core.DHParams(
jceKey.getParams().getP(),
jceKey.getParams().getG(),
jceKey.getParams().getP().subtract(new BigInteger("1")).divide(new BigInteger("2"))));
}

A.4 Working with JCE Certificates

As of Release 11gR1, oracle.security.crypto.cert.X509 is changed to java.security.cert.X509Certificate. Several utility methods are available for creating and working with JCE certificates. An X509Certificate object can be created from an input stream using java.security.cert.CertificateFactory.

The input stream can be one of the following:

a FileInputSream, if the certificate is stored in a file, or
a ByteArrayInputStream, if we got the encoded bytes from an old X509 object, or
any other sources.

For example, the following code converts an Oracle Security Developer Tools certificate to a JCE certificate:

CertificateFactory cf = CertificateFactory.getInstance("X.509");
  
X509Certificate cert = (X509Certificate)cf.generateCertificate(
    new FileInputStream(certFileName);

where certFileName is the name of the certificate file.

A.5 Working with JCE Certificate Revocation Lists (CRLs)

In Release 11gR1, oracle.security.crypto.cert.CRL is replaced by java.security.cert.CRL. You can create the java.security.cert.CRL object from an input stream by using java.security.cert.CertificateFactory.

The input stream can be one of the following:

FileInputSream, if the CRL is stored in a file
ByteArrayInputStream, if the encoded bytes were obtained from an old oracle.security.crypto.cert.CRL object
any other source

Here is an example of a CRL object creation:

CertificateFactory cf = CertificateFactory.getInstance("X.509");
 
509Certificate cert = (X509Certificate)cf.generateCRL(
   new FileInputStream(crlFileName));

where the crlFileName is the name of the CRL file.

A.6 Using JCE Keystores

Oracle Security Developer Tools provide four types of keystore: JKS keystore, Oracle wallet, PKCS12 wallet, and PKCS8 wallet.

These are:

the JKS keystore, which is Oracle's implementation of the java.security.KeyStore interface
the Oracle wallet, which is Oracle's implementation of the java.security.KeyStore interface
the PKCS12 wallet, which is a proprietary Oracle interface/implementation of PKCS12
the PKCS8 wallet, which is a proprietary Oracle interface/implementation of PKCS8

A.6.1 Working with standard KeyStore-type Wallets

You can instantiate a Keystore object using an Oracle provider, load a Keystore file, and retrieve a certificate.

Creating a PKCS12 Wallet

This example instantiates a PKCS12 wallet for the Oracle provider:

java.security.KeyStore keystore = KeyStore.getInstance("PKCS12", "OraclePKI");

Loading a Keystore File

You perform this task with the keystore.load method:

keystore.load(new FileInputStream(walletFile), pass);

Retrieving a Certificate

To retrieve a certificate and private key using an alias:

Key key = keystore.getKey(alias);

Certificate cert = keystore.getCert(alias);

If the alias is not known in advance, you can list all aliases by calling:

keystore.aliases();

A.6.2 Working with PKCS12 and PKCS8 Wallets

If you maintain keystores in the PKCS12 or PKCS8 oracle wallet format, you can retrieve keys, certificates or CRLs from those stores in Oracle Security Developer Tools format.

A.6.2.1 Retrieving a PKCS Object

In Oracle wallets, the key is found in oracle.security.crypto.core.PrivateKey.

After retrieval, you can convert the keys into the JCE key format, using the utility class PhaosJCEKeyTranslator.

For more information, see Converting Between OSDT Key Objects and JCE Key Objects.

A.6.2.2 Retrieving a Certificate

In Oracle wallets, the certificate is found in oracle.security.crypto.cert.X509.

After retrieval, you can:

get the encoded value of the X509 certificate, for example X509.getEncoded();
use the CertificateFactory to create a X509Certificate instance, based on the encoded bytes value.

For more information, see Working with JCE Certificates.

A.6.2.3 Retrieving CRLs

In Oracle wallets, the CRL is found in oracle.security.crypto.cert.CRL.

After retrieval, you can:

get the encoded value of the CRL, for example CRL.getEncoded();
use the CertificateFactory to create a java.security.cert.CRL instance, based on the encoded bytes value.

For more information, see Working with JCE Certificate Revocation Lists (CRLs).

A.7 The Oracle JCE Java API Reference

The Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools guide explains the classes and methods available in the Oracle JCE framework.

You can access the guide at:

Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools