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:
- 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. - 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. - 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. - Working with JCE Certificates
As of Release 11gR1,oracle.security.crypto.cert.X509
is changed tojava.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. - Working with JCE Certificate Revocation Lists (CRLs)
In Release 11gR1,oracle.security.crypto.cert.CRL
is replaced byjava.security.cert.CRL
. You can create thejava.security.cert.CRL
object from an input stream by usingjava.security.cert.CertificateFactory
. - Using JCE Keystores
Oracle Security Developer Tools provide four types of keystore: JKS keystore, Oracle wallet, PKCS12 wallet, and PKCS8 wallet. - 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.
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.
Parent topic: Migrating to the JCE Framework
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 tojava.security.PublicKey
-
oracle.security.crypto.core.PrivateKey
changed tojava.security.PrivateKey
-
oracle.security.crypto.core.SymmetricKey
changed tojavax.crypto.SecretKey
Parent topic: Migrating to the JCE Framework
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.
- Converting a Private Key from OSDT to JCE Object
You can convert keys in Oracle Security Developer Tools (OSDT) format to JCE objects. - Converting a Private Key from JCE Object to OSDT Object
You can convert private key objects from JCE to OSDT format.
Parent topic: Migrating to the JCE Framework
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); }
Parent topic: Converting Between OSDT Key Objects and JCE Key Objects
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")))); }
Parent topic: Converting Between OSDT Key Objects and JCE Key Objects
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.
Parent topic: Migrating to the JCE Framework
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 oldoracle.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.
Parent topic: Migrating to the JCE Framework
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
- Working with standard KeyStore-type Wallets
You can instantiate a Keystore object using an Oracle provider, load a Keystore file, and retrieve a certificate. - 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.
Parent topic: Migrating to the JCE Framework
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();
Parent topic: Using JCE Keystores
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.
Parent topic: Working with PKCS12 and PKCS8 Wallets
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.
Parent topic: Working with PKCS12 and PKCS8 Wallets
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).
Parent topic: Working with PKCS12 and PKCS8 Wallets
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
Parent topic: Migrating to the JCE Framework