Skip Headers

Oracle® Security Developer Tools Reference 10g Release 3 (10.1.3) B25372-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 4 Oracle Security Engine

This chapter provides information about using the Oracle Security Engine Software Development Kit (SDK) certificate package. Oracle Security Engine 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.

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" in Chapter 2.

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

This chapter contains the following topics:

- Oracle Security Engine Features and Benefits

- Setting Up Your Oracle Security Engine Environment

- Core Classes and Interfaces

- Oracle Security Engine Java API Reference

## 4.1 Oracle Security Engine Features and Benefits

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

### 4.1.1 Oracle Security Engine Packages

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.

## 4.2 Setting Up Your Oracle Security Engine Environment

The Oracle Security Developer Tools are installed with Oracle Application Server in `ORACLE_HOME`. This section provides information for setting up your environment for Oracle Security Engine. It contains the following topics:

- System Requirements for Oracle Security Engine

- Setting the CLASSPATH Environment Variable

### 4.2.1 System Requirements for Oracle Security Engine

In order to use Oracle Security Engine, your system must have the Java Development Kit (JDK) version 1.2.2.

### 4.2.2 Setting the CLASSPATH Environment Variable

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`

#### 4.2.2.1 Setting the CLASSPATH on Windows

To set your `CLASSPATH` on Windows:

1. In your Windows Control Panel, select System.

2. In the System Properties dialog, select the Advanced tab.

3. Click Environment Variables.

4. In the User Variables section, click New to add a `CLASSPATH` environment variable for your user profile. If a `CLASSPATH` environment variable already exists, select it and click Edit.

5. Add the full path and file names for all of the required jar and class files to the `CLASSPATH`.

   For example, your `CLASSPATH` might look like this:

       %CLASSPATH%;C:\ORACLE_HOME\jlib\osdt_core.jar;
       C:\ORACLE_HOME\jlib\osdt_cert.jar;

6. Click OK.

#### 4.2.2.2 Setting the CLASSPATH on UNIX

To set your CLASSPATH on UNIX, set your `CLASSPATH` environment variable to include the full path and file name of all of the required jar and class files. For example:

    setenv CLASSPATH $CLASSPATH:$ORACLE_HOME/jlib/osdt_core.jar:\
    $ORACLE_HOME/jlib/osdt_cert.jar:

## 4.3 Core Classes and Interfaces

This section provides information and code samples for using the certificate facility classes of Oracle Security Engine. Oracle Security Engine also includes all of the classes provided with Oracle Crypto. See Chapter 2, "Oracle Crypto" for an overview of the core Oracle Crypto classes.

The core certificate facility classes are:

- The oracle.security.crypto.cert.X500RDN Class

- The oracle.security.crypto.cert.X500Name Class

- The oracle.security.crypto.cert.CertificateRequest Class

- The oracle.security.crypto.cert.X509 Class

### 4.3.1 The oracle.security.crypto.cert.X500RDN Class

This 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.

Example 4-1 Code Example for Creating and Retrieving an `X500RDN` Object

    // 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();

### 4.3.2 The oracle.security.crypto.cert.X500Name Class

This 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:

Example 4-2 Code Example for Creating an X500Name Object

    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@oracle.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();

### 4.3.3 The oracle.security.crypto.cert.CertificateRequest Class

This 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.

Example 4-3 Code Example for Creating a Certificate Request

    //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

### 4.3.4 The oracle.security.crypto.cert.X509 Class

This class represents an X.509 certificate. Oracle Security Engine supports the generation of new certificates as well as the parsing of existing certificates.<May want to add some examples here from the GenCACert, GenCert.java and/or GenSPKACCert.java programs>

## 4.4 Oracle Security Engine Java API Reference

The Oracle Security Engine Java API reference (Javadoc) is available at:

Oracle Security Developer Tools Security Engine Java API Reference