1. Developing Applications with Oracle Security Developer Tools
  2. Oracle Security Engine

3 Oracle Security Engine

Oracle Security Engine Software Development Kit (SDK) is a superset of Oracle Crypto. It contains all of the libraries and tools provided with Oracle Crypto, plus additional packages and utilities for generating digital certificates.

Note:

The use of the Oracle Security Engine library is not recommended with Release 11gR1 and higher. Instead use the JDK's Certificate APIs.

For details, see the JDK documentation at:

http://www.oracle.com/technetwork/java/index.html

However, the following Public-Key Cryptography Standards (PKCS) have no JCE equivalents:

  • PKCS#7

  • PKCS#10

  • Signed Public Key And Challenge (SPKAC)

and you can continue using Oracle Security Engine for these features.

Oracle Crypto allows Java developers to develop applications that ensure data security and integrity. For more information about the Oracle Crypto functionality, see "Oracle Crypto".

For an overview of public key infrastructure, see "About Public Key Infrastructure (PKI)".

This chapter contains the following topics:

3.1 Oracle Security Engine Features and Benefits

Oracle Security Engine supports X.509, PKCS#10, and PKCS#12 certificates, along with RDN and CRLs. It contains packages to support handling of digital certificates, CRLs, and PKCS#12. The packages also handle Standard X.509 certificates and CRL extensions.

Oracle Security Engine provides the following features:

  • X.509 Version 3 Certificates, as defined in RFC 3280

  • Full PKCS#12 support

  • PKCS#10 support for certificate requests

  • certificate revocation list (CRL) functionality as defined in RFC 3280

  • Implementation of Signed Public Key And Challenge (SPKAC)

  • Support for X.500 Relative Distinguished Names

  • PKCS#7 support for wrapping X.509 certificates and CRLs

  • Implementation of standard X.509 certificates and CRL extensions

The Oracle Security Engine toolkit contains the following packages:

  • oracle.security.crypto.cert - Facilities for handling digital certificates, CRLs, and PKCS#12.

  • oracle.security.crypto.cert.ext - Standard X.509 certificates and CRL extensions.

3.2 Setting Up Your Oracle Security Engine Environment

The Oracle Security Developer Tools are installed with Oracle WebLogic Server in ORACLE_HOME. In order to use Oracle Security Engine, your system must have the Java Development Kit (JDK) version 1.6 or higher. Your CLASSPATH environment variable must contain the full path and file names to the required jar and class files.

Make sure the following items are included in your CLASSPATH:

  • osdt_core.jar

  • osdt_cert.jar

For example, your CLASSPATH might look like this: 

%CLASSPATH%;
%ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_core.jar;
%ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_cert.jar;

See Also:

Setting the CLASSPATH Environment Variable

3.3 Core Classes and Interfaces of Oracle Security Engine

Oracle Security Engine also includes all of the classes provided with Oracle Crypto. It also includes multiple core certificate facility classes.

Class Changes in Release 11gR1

In Release 11gR1, the oracle.security.crypto.cert.X509 class for certificate management was replaced with java.security.cert.X509Certificate

The Core Certificate Classes

The core certificate facility classes are:

3.3.1 Using the oracle.security.crypto.cert.X500RDN Class

The oracle.security.crypto.cert.X500RDN class represents an X.500 Relative Distinguished Name (RDN). This is the building block for X.500 names. A RDN consists of a set of attribute-value pairs. Typically, there is a single attribute-value pair in each RDN.

// Create the X500RDN object
X500RDN rdn = new X500RDN(PKIX.id_at_commonName, "Joe Smith");

// Retrieve the value
X500Name n = Instance of oracle.security.crypto.cert.X500Name;
String name = n.getAttribute(PKIX.id_at_commonName).getValue().getValue();

3.3.2 Using the oracle.security.crypto.cert.X500Name Class

The oracle.security.crypto.cert.X500Name class represents distinguished names as used in the X.500 series of specifications, defined in X.520. An X500Name object is made of X500RDN objects. An X500Name holds attributes defining an entity such as the common name, country, organization, and so on.

To create an X500Name object, use the standard constructor and then populate the object with attributes. Once created, the object can then be DER-encoded to make it available to other processes: 

X500Name name = new X500Name();
name.addComponent(PKIX.id_at_commonName, "Joe Smith");
name.addComponent(PKIX.id_at_countryName, "USA");
name.addComponent(PKIX.id_at_stateOrProvinceName, "NY");
name.addComponent(PKIX.id_at_localityName, "New York");
name.addComponent(PKIX.id_at_organizationName, "Oracle");
name.addComponent(PKIX.id_at_organizationalUnitName, "Engineering");
name.addComponent(PKIX.emailAddress, "joe.smith@example.com");

// Make object DER-encoded so its available to other processes 

byte[] encodedName = Utils.toBytes(name);
X500Name n = new X500Name(new ByteArrayInputStream(encodedName));
String name = n.getAttribute(PKIX.id_at_commonName).getValue().getValue();
String email = n.getAttribute(PKIX.emailAddress).getValue().getValue();

3.3.3 Using the oracle.security.crypto.cert.CertificateRequest Class

The oracle.security.crypto.cert.CertificateRequest class represents a PKCS#10 certificate request containing information about an entity and a signature of the content of the request. The certificate request is used to convey information and authentication data (the signature) that will be used by a Certificate Authority (CA) to generate a certificate for the corresponding entity.

Creating a new certificate request involves the following high-level steps:

  1. Create a new instance of CertificateRequest by using the empty constructor and setting the keys and the subject name, or by using the constructor taking an X500Name and a KeyPair object.
  2. Add X.509 extensions to the certificate request.
  3. Sign the certificate request and save it to a file.
  4. Send the certificate request you created to a Certificate Authority. 
//Create CertificateRequest by setting the keys and subject name
 CertificateRequest certReq = new CertificateRequest();
 certReq.setPrivateKey(privKey);
certReq.setPublicKey(pubKey);
 certReq.setSubject(subjectName);

//OR

// Create CertificateRequest by taking an X500Name and KeyPair object
CertificateRequest certReq = new CertificateRequest(subjectName, keyPair);

// Add X.509 certificate extensions in a extensionRequest attribute
X509ExtensionSet extSet = new X509ExtensionSet();

// Basic Constraints: non-CA, critical
extSet.addExtension(new BasicConstraintsExtension(false, true));

// Key Usage: signature, data encipherment, key agreement 
// & non-repudiation flags, critical
extSet.addExtension(new KeyUsageExtension(new int[] {
     KeyUsageExtension.DIGITAL_SIGNATURE,
     KeyUsageExtension.DATA_ENCIPHERMENT,
     KeyUsageExtension.KEY_AGREEMENT,
     KeyUsageExtension.NON_REPUDIATION},
        true));

// Subject Alternative Name: email address, non-critical
if (email.length() > 0)
    extSet.addExtension(new SubjectAltNameExtension(
        new GeneralName(GeneralName.Type.RFC822_NAME, email), false));

// Subject Key Identifier: key ID bytes, non-critical
extSet.addExtension(new SubjectKeyIDExtension
    (CryptoUtils.generateKeyID(kp.getPublic())));
req.addAttribute(PKIX.extensionRequest, extSet);

// Sign the certificate request and save to file
req.sign();
req.output(reqOS);
reqOS.close();
	}
// The certificate request can then be sent to a CA

3.3.4 Using the java.security.cert.X509Certificate Class

The java.security.cert.X509Certificate class supports the generation of new certificates as well as parsing of existing certificates.

Note:

This class replaces oracle.security.crypto.cert.X509 for X.509 certificate management in Oracle WebLogic Server 11g.

Complete documentation of the java.security.cert.X509Certificate class is available at http://www.oracle.com/technetwork/java/index.html.

Converting Your Code to Use java.security.cert.X509Certificate

You can create the X509Certificate object using the certificate factory java.security.cert.CertificateFactory.

The certificate is generated from an input stream, which can be:

  • a FileInputSream, if the certificate is stored in a file, or

  • a ByteArrayInputStream, if the encoded bytes are from an existing X509 object, or

  • any other source.

An example follows:

// Generating an X.509 certificate from a file-based certificate
                  
CertificateFactory cf = CertificateFactory.getInstance("X.509");
     
X509Certificate cert = (X509Certificate)cf.generateCertificate(
                       new FileInputStream(certFileName);

**

3.4 The Oracle Security Engine Java API Reference

Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools guide explains the classes and methods of Oracle Security Engine.

You can access the guide at:

Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools