Skip Headers

Oracle® Application Server Administrator's Guide 10g Release 3 (10.1.3) B25209-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 11 Managing Wallets and Certificates

This chapter explains how to obtain and manage security credentials for Oracle Application Server resources. Security administrators can use Oracle Wallet Manager and its command-line utility, `orapki`, to manage public key infrastructure (PKI) credentials on Oracle clients and servers. These tools create credentials that can be read by Oracle Database, Oracle Application Server, and the Oracle Identity Management infrastructure.

Note: In this chapter, references to any of the following Oracle Application Server products are applicable for Release 2 (10.1.2) or earlier software only: Oracle Identity Management For more information about which specific versions are compatible with 10g Release 3 (10.1.3), see the Oracle Application Server Upgrade and Compatibility Guide.

This chapter contains the following topics:

- Using Oracle Wallet Manager

- Performing Certificate Validation and CRL Management with the orapki Utility

- Interoperability with X.509 Certificates

  Note: If you already have certificates provisioned, the following sections may provide all of the information you need: Section 11.1.2, "Starting Oracle Wallet Manager" Section 11.3, "Interoperability with X.509 Certificates"

## 11.1 Using Oracle Wallet Manager

This section describes Oracle Wallet Manager, a graphical user interface tool used to manage PKI certificates. It contains the following topics:

- Oracle Wallet Manager Overview

- Starting Oracle Wallet Manager

- How To Create a Complete Wallet: Process Overview

- Managing Wallets

- Managing Certificates

### 11.1.1 Oracle Wallet Manager Overview

Oracle Wallet Manager is an application used to manage and edit security credentials in Oracle wallets. A wallet is a password-protected container that stores authentication and signing credentials, including private keys, certificates, and trusted certificates, all of which are used by SSL for strong authentication. You can use Oracle Wallet Manager to perform the following tasks:

- Create wallets

- Generate certificate requests

- Open wallets to access PKI-based services

- Save credentials to hardware security modules by using APIs which comply to Public-Key Cryptography Standard #11 specification (see PKCS #11)

- Upload wallets to and download them from an LDAP directory

- Import third-party PKCS #12-format wallets to use in an Oracle environment

- Export Oracle wallets to third-party environments

The following topics describe Oracle Wallet Manager features:

- Wallet Password Management

- Strong Wallet Encryption

- Microsoft Windows Registry Wallet Storage

- Backward Compatibility

- Third-Party Wallet Support

- LDAP Directory Support

#### 11.1.1.1 Wallet Password Management

Oracle wallets are password protected. Oracle Wallet Manager includes an enhanced wallet password management module that enforces the following password management policy guidelines:

- Minimum password length (8 characters)

- Maximum password length unlimited

- Alphanumeric character mix required

#### 11.1.1.2 Strong Wallet Encryption

Oracle Wallet Manager stores private keys associated with X.509 certificates and uses Triple-DES encryption.

#### 11.1.1.3 Microsoft Windows Registry Wallet Storage

As an option, Oracle Wallet Manager enables you to store multiple Oracle wallets in the user profile area of the Microsoft Windows system registry or in a Windows file management system. Storing your wallets in the registry provides the following benefits:

- Better Access Control. Wallets stored in the user profile area of the registry are only accessible by the associated user. User access controls for the system thus become, by extension, access controls for the wallets. In addition, when a user logs out of a system, access to that user's wallets is effectively precluded.

- Easier Administration. Since wallets are associated with specific user profiles, no file permissions need to be managed, and the wallets stored in the profile are automatically deleted when the user profile is deleted. Oracle Wallet Manager can be used to create and manage the wallets in the registry.

##### 11.1.1.3.1 Options Supported:

- Open wallet from the registry

- Save wallet to the registry

- Save As to a different registry location

- Delete wallet from the registry

- Open wallet from the file system and save it to the registry

- Open wallet from the registry and save it to the file system

#### 11.1.1.4 Backward Compatibility

Oracle Wallet Manager is backward-compatible to Release 8.1.7 of the database.

#### 11.1.1.5 Third-Party Wallet Support

Oracle Wallet Manager can use PKI credentials from the following third-party applications:

- Microsoft Internet Explorer 5.0 and later

- Netscape Communicator 4.7.2 and later

- OpenSSL

Browser PKI credential stores (those from Microsoft Internet Explorer and Netscape) hold user certificates, which contain the subject's public key and identifying information, and their associated trusted certificates. To use these credentials, you must export them from the third-party environment and save them in PKCS #12 format. Then you can use Oracle Wallet Manager to open them for use with SSL.

See Also: "Section 11.1.5.1.3, "Importing Certificates Created with a Third-Party Tool"

#### 11.1.1.6 LDAP Directory Support

Oracle Wallet Manager can upload wallets to and retrieve them from an LDAP-compliant directory. Storing wallets in a centralized LDAP-compliant directory lets users access them from multiple locations or devices, ensuring consistent and reliable user authentication while providing centralized wallet management throughout the wallet life cycle. To prevent accidental over-write of functional wallets, only wallets containing an installed certificate can be uploaded.

Directory user entries must be defined and configured in the LDAP directory before Oracle Wallet Manager can be used to upload or download wallets for a user. If a directory contains Oracle8i (or prior) users, they are automatically upgraded to use the wallet upload and download feature on first use.

Oracle Wallet Manager downloads a user wallet by using a simple password-based connection to the LDAP directory. However, for uploads it uses an SSL connection if the open wallet contains a certificate with SSL Oracle PKI certificate usage. If an SSL certificate is not present in the wallet, password-based authentication is used.

Note: The directory password and the wallet password are independent, and can be different. Oracle Corporation recommends that these passwords be maintained to be consistently different, where neither one can logically be derived from the other.

See Also: Section 11.1.4.7, "Uploading a Wallet to an LDAP Directory" Section 11.1.4.8, "Downloading a Wallet from an LDAP Directory" Section 11.3.2, "Multiple Certificate Support"

### 11.1.2 Starting Oracle Wallet Manager

To start Oracle Wallet Manager:

- (Windows) Select Start > Programs > Oracle - Oracle_Home_Name > Integrated Management Tools > Wallet Manager

- (UNIX) At the command line, enter `owm`.

### 11.1.3 How To Create a Complete Wallet: Process Overview

A wallet is a necessary repository in which to securely store user certificates and the trust points needed to validate the certificates of peers.

The following steps provide an overview of the complete wallet creation process:

1. Use Oracle Wallet Manager to create a new wallet:

   - See Section 11.1.4.1, "Required Guidelines for Creating Wallet Passwords" for information about creating a wallet password.

   - See Section 11.1.4.2, "Creating a New Wallet" for information about creating standard wallets (store credentials on your file system) and hardware security module wallets.

2. Generate a certificate request. Note that when you create a new wallet with Oracle Wallet Manager, the tool automatically prompts you to create a certificate request. See Section 11.1.5.1.1, "Adding a Certificate Request" for information about creating a certificate request.

3. Send the certificate request to the CA you want to use. You can copy and paste the certificate request text into an e-mail message, or you can export the certificate request to a file. See Section 11.1.5.1.7, "Exporting a User Certificate Request". Note that the certificate request becomes part of the wallet and must remain there until you remove its associated certificate.

4. When the CA sends your signed user certificate and its associated trusted certificate, then you can import these certificates in the following order. (Note that user certificates and trusted certificates in the PKCS #7 format can be imported at the same time.)

   - First import the CA's trusted certificate into the wallet. See Section 11.1.5.2.1, "Importing a Trusted Certificate". Note that this step may be optional if the new user certificate has been issued by one of the CAs whose trusted certificate is already present in Oracle Wallet Manager by default.

   - After you have successfully imported the trusted certificate, then import the user certificate that the CA sent to you into your wallet. See Section 11.1.5.1.2, "Importing the User Certificate into the Wallet".

     Note: The BASE64 encoded PKCS#7 format used by most certificate authorities typically uses the following header and footer lines:
         -----BEGIN PKCS7-----
         -----END PKCS7-----
     Regular certificates contain the following header & footer lines:
         -----BEGIN CERTIFICATE-----
         -----END CERTIFICATE-----
     However, some certificate authorities use BEGIN CERTIFICATE and END CERTIFICATE header and footer lines in PKCS #7 format certificates as well. When certificates of PKCS #7 format are imported, the certificate authority certificates are imported as trusted certificates. If you import the user certificate without its certificate authority certificate, Oracle Wallet Manager prompts you for the certificate authority certificate that issued the user certificate.

5. (Optional) Set the auto login feature for the wallet. See Section 11.1.4.14, "Using Auto Login".

   Typically, this feature, which enables PKI-based access to services without a password, is required for most wallets. It is required for database server and client wallets. It is only optional for products that take the wallet password at the time of startup.

After completing the preceding process, you have a wallet that contains a user certificate and its associated trust points.

### 11.1.4 Managing Wallets

This section describes how to create a new wallet and perform associated wallet management tasks in the following topics:

- Required Guidelines for Creating Wallet Passwords

- Creating a New Wallet

- Opening an Existing Wallet

- Closing a Wallet

- Exporting Oracle Wallets to Third-Party Environments

- Exporting Oracle Wallets to Tools That Do Not Support PKCS #12

- Uploading a Wallet to an LDAP Directory

- "Downloading a Wallet from an LDAP Directory"

- Saving Changes

- Saving the Open Wallet to a New Location

- Saving in System Default

- Deleting the Wallet

- Changing the Password

- Using Auto Login

#### 11.1.4.1 Required Guidelines for Creating Wallet Passwords

Because an Oracle wallet contains user credentials that can be used to authenticate the user to multiple databases, it is especially important to choose a strong wallet password. A malicious user who guesses the wallet password can access all the databases to which the wallet owner has access.

Passwords must contain at least eight characters that consist of alphabetic characters combined with numbers or special characters.

Caution: It is strongly recommended that users avoid choosing easily guessed passwords based on user names, phone numbers, or government identification numbers, such as "admin0," "oracle1," or "2135551212A." This prevents a potential attacker from using personal information to deduce the users' passwords. It is also a prudent security practice for users to change their passwords periodically, such as once in each month or once in each quarter. When you change passwords, you must regenerate auto login wallets.

See Also: Section 11.1.1.1, "Wallet Password Management" Section 11.1.4.14, "Using Auto Login"

#### 11.1.4.2 Creating a New Wallet

You can use Oracle Wallet Manager to create PKCS #12 wallets (the standard default wallet type) that store credentials in a directory on your file system. It can also be used to create PKCS #11 wallets that store credentials on a hardware security module for servers, or private keys on tokens for clients. The following sections explain how to create both types of wallets by using Oracle Wallet Manager.

##### 11.1.4.2.1 Creating a Standard Wallet

Unless you have a hardware security module (a PKCS #11 device), then you should use a standard wallet that stores credentials in a directory on your file system.

To create a standard wallet, perform the following tasks:

1. Choose Wallet > New from the menu bar. The New Wallet dialog box appears.

2. Follow the "Required Guidelines for Creating Wallet Passwords" on page 1-9 and enter a password in the Wallet Password field. This password protects unauthorized use of your credentials.

3. Re-enter that password in the Confirm Password field.

4. Choose Standard from the Wallet Type list.

5. Click OK to continue. If the entered password does not conform to the required guidelines, then the following message appears:

       Password must have a minimum length of eight characters,
       and contain alphabetic characters combined with numbers
       or special characters.
        Do you want to try again?

6. An alert is displayed that informs you that a new empty wallet has been created. It prompts you to decide whether you want to add a certificate request. See Section 11.1.5.1.1, "Adding a Certificate Request".

   If you choose No, you are returned to the Oracle Wallet Manager main window. The new wallet you just created appears in the left window pane. The certificate has a status of [Empty], and the wallet displays its default trusted certificates.

7. Select Wallet > Save In System Default to save the new wallet.

   If you do not have permission to save the wallet in the system default, you can save it to another location. This location must be used in the SSL configuration for clients and servers.

   A message at the bottom of the window confirms that the wallet was successfully saved.

##### 11.1.4.2.2 Creating a Wallet to Store Hardware Security Module Credentials

To create a wallet to store credentials on a hardware security module that complies with PKCS #11, perform the following tasks:

1. Choose Wallet > New from the menu bar; the New Wallet dialog box appears.

2. Follow Section 11.1.4.1, "Required Guidelines for Creating Wallet Passwords" and enter a password in the Wallet Password field.

3. Re-enter that password in the Confirm Password field.

4. Choose PKCS11 from the Wallet Type list, and click OK to continue. The New PKCS11 Wallet window appears.

5. Choose a vendor name from the Select Hardware Vendor list.

   Note: In the current release of Oracle Wallet Manager, only nCipher hardware has been certified to interoperate with Oracle wallets.

6. In the PKCS11 library filename field, enter the path to the directory in which the PKCS11 library is stored, or click Browse to find it by searching the file system.

7. Enter the SmartCard password, and choose OK.

   The smart card password, which is different from the wallet password, is stored in the wallet.

8. An alert is displayed, and informs you that a new empty wallet has been created. It prompts you to decide whether you want to add a certificate request. See Section 11.1.5.1.1, "Adding a Certificate Request".

   If you choose No, you are returned to the Oracle Wallet Manager main window. The new wallet you just created appears in the left window pane. The certificate has a status of [Empty], and the wallet displays its default trusted certificates.

9. Select Wallet > Save In System Default to save the new wallet.

   If you do not have permission to save the wallet in the system default, you can save it to another location.

   A message at the bottom of the window confirms that the wallet was successfully saved.

   Note: If you change the SmartCard password or move the PKCS #11 library, an error message displays when you try to open the wallet. Then you are prompted to enter the new SmartCard password or the new path to the library.

#### 11.1.4.3 Opening an Existing Wallet

Open a wallet that already exists in the file system directory as follows:

1. Choose Wallet > Open from the menu bar. The Select Directory dialog box appears.

2. Navigate to the directory location in which the wallet is located, and select the directory.

3. Choose OK. The Open Wallet dialog box appears.

4. Enter the wallet password in the Wallet Password field.

5. Choose OK.

   You are returned to the main window and a message appears at the bottom of the window indicating the wallet was opened successfully. The wallet's certificate and its trusted certificates are displayed in the left window pane.

#### 11.1.4.4 Closing a Wallet

To close an open wallet in the currently selected directory:

Choose Wallet > Close.

A message appears at the bottom of the window to confirm that the wallet is closed.

#### 11.1.4.5 Exporting Oracle Wallets to Third-Party Environments

Oracle Wallet Manager can export its own wallets to third party environments.

To export a wallet to third-party environments:

1. Use Oracle Wallet Manager to save the wallet file.

2. Follow the procedure specific to your third-party product to import an operating system PKCS #12 wallet file created by Oracle Wallet Manager (called `ewallet.p12` on UNIX and Windows platforms).

   Note: Oracle Wallet Manager supports multiple certificates for each wallet, yet current browsers typically support import of single-certificate wallets only. For these browsers, you must export an Oracle wallet containing a single key-pair. Oracle Wallet Manager supports wallet export to only Netscape Communicator 4.7.2 and later, OpenSSL, and Microsoft Internet Explorer 5.0 and later.

#### 11.1.4.6 Exporting Oracle Wallets to Tools That Do Not Support PKCS #12

You can export a wallet to a text-based PKI format if you want to put a wallet into a tool that does not support PKCS #12. Individual components are formatted according to the standards listed in Table 11-1. Within the wallet, only those certificates with SSL key usage are exported with the wallet.

To export a wallet to text-based PKI format:

1. Choose Operations > Export Wallet.... The Export Wallet dialog box appears.

2. Enter the destination file system directory for the wallet, or navigate to the directory structure under Folders.

3. Enter the destination file name for the wallet.

4. Choose OK to return to the main window.

Table 11-1 PKI Wallet Encoding Standards

Component | Encoding Standard
--- | ---
Certificate chains | X509v3
Trusted certificates | X509v3
Private keys | PKCS #8

#### 11.1.4.7 Uploading a Wallet to an LDAP Directory

To upload a wallet to an LDAP directory, Oracle Wallet Manager uses SSL if the specified wallet contains an SSL certificate. Otherwise, it lets you enter the directory password.

To prevent accidental destruction of your wallet, Oracle Wallet Manager will not permit you to execute the upload option unless the target wallet is currently open and contains at least one user certificate.

To upload a wallet:

1. Choose Wallet > Upload Into The Directory Service.... If the currently open wallet has not been saved, a dialog box appears with the following message:

   Wallet needs to be saved before uploading.

   Choose Yes to proceed.

2. Wallet certificates are checked for `SSL` key usage. Depending on whether a certificate with `SSL` key usage is found in the wallet, one of the following results occur:

   - If at least one certificate has SSL key usage: When prompted, enter the LDAP directory server hostname and port information, then click OK. Oracle Wallet Manager attempts connection to the LDAP directory server using SSL. A message appears indicating whether the wallet was uploaded successfully or it failed.

   - If no certificates have SSL key usage: When prompted, enter the user's distinguished name (DN), the LDAP server hostname and port information, and click OK. Oracle Wallet Manager attempts connection to the LDAP directory server using simple password authentication mode, assuming that the wallet password is the same as the directory password.

     If the connection fails, a dialog box prompts for the directory password of the specified DN. Oracle Wallet Manager attempts connection to the LDAP directory server using this password and displays a warning message if the attempt fails. Otherwise, Oracle Wallet Manager displays a status message at the bottom of the window indicating that the upload was successful.

#### 11.1.4.8 Downloading a Wallet from an LDAP Directory

When a wallet is downloaded from an LDAP directory, it is resident in working memory. It is not saved to the file system unless you expressly save it using any of the Save options described in the following sections.

See Also: Section 11.1.4.9, "Saving Changes" Section 11.1.4.10, "Saving the Open Wallet to a New Location" Section 11.1.4.11, "Saving in System Default"

To download a wallet from an LDAP directory:

1. Choose Wallet > Download From The Directory Service....

2. A dialog box prompts for the user's distinguished name (DN), and the LDAP directory password, hostname, and port information. Oracle Wallet Manager uses simple password authentication to connect to the LDAP directory.

   Depending on whether the downloading operation succeeds or not, one of the following results occurs:

   - If the download operation fails: Check to make sure that you have correctly entered the user's DN, and the LDAP server hostname and port information.

   - If the download is successful: Choose OK to open the downloaded wallet. Oracle Wallet Manager attempts to open that wallet using the directory password. If the operation fails after using the directory password, then a dialog box prompts for the wallet password.

     If Oracle Wallet Manager cannot open the target wallet using the wallet password, then check to make sure you entered the correct password. Otherwise a message displays at the bottom of the window, indicating that the wallet was downloaded successfully.

#### 11.1.4.9 Saving Changes

To save your changes to the current open wallet:

Choose Wallet > Save.

A message at the bottom of the window confirms that the wallet changes were successfully saved to the wallet in the selected directory location.

#### 11.1.4.10 Saving the Open Wallet to a New Location

To save open wallets to a new location, use the Save As... menu option:

1. Choose Wallet > Save As.... The Select Directory dialog box appears.

2. Select a directory location in which to save the wallet.

3. Choose OK.

   The following message appears if a wallet already exists in the selected location:

       A wallet already exists in the selected path. Do you want to overwrite it?

   Choose Yes to overwrite the existing wallet, or No to save the wallet to another location.

   A message at the bottom of the window confirms that the wallet was successfully saved to the selected directory location.

#### 11.1.4.11 Saving in System Default

To save wallets in the default directory location, use the Save In System Default menu option:

Choose Wallet > Save In System Default.

A message at the bottom of the window confirms that the wallet was successfully saved in the system default wallet location as follows for UNIX and Windows platforms:

- (UNIX) `/etc/ORACLE/WALLETS/$USER/`

- (Windows) `%USERPROFILE%\ORACLE\WALLETS\`

  Note: SSL uses the wallet that is saved in the system default directory location. Some Oracle applications are not able to use the wallet if it is not in the system default location. Check the Oracle documentation for your specific application to determine whether wallets must be placed in the default wallet directory location.

#### 11.1.4.12 Deleting the Wallet

To delete the current open wallet:

1. Choose Wallet > Delete. The Delete Wallet dialog box appears.

2. Review the displayed wallet location to verify you are deleting the correct wallet.

3. Enter the wallet password.

4. Choose OK. A dialog panel appears to inform you that the wallet was successfully deleted.

   Note: Any open wallet in application memory will remain in memory until the application exits. Therefore, deleting a wallet that is currently in use does not immediately affect system operation.

#### 11.1.4.13 Changing the Password

A password change is effective immediately. The wallet is saved to the currently selected directory, with the new encrypted password.

Note: If you are using a wallet with auto login enabled, you must regenerate the auto login wallet after changing the password. See Section 11.1.4.14, "Using Auto Login"

To change the password for the current open wallet:

1. Choose Wallet > Change Password. The Change Wallet Password dialog box appears.

2. Enter the existing wallet password.

3. Enter the new password.

4. Re-enter the new password.

5. Choose OK.

A message at the bottom of the window confirms that the password was successfully changed.

See Also: Section 11.1.4.1, "Required Guidelines for Creating Wallet Passwords" Section 11.1.1.1, "Wallet Password Management"

#### 11.1.4.14 Using Auto Login

The Oracle Wallet Manager auto login feature creates an obfuscated copy of the wallet and enables PKI-based access to services without a password until the auto login feature is disabled for the wallet. File system permissions provide the necessary security for auto-login wallets.

You must enable auto login if you want single sign-on access to multiple Oracle databases, which is disabled by default. Sometimes these are called "SSO wallets" because they provide single sign-on capability.

##### 11.1.4.14.1 Enabling Auto Login

To enable auto login:

1. Choose Wallet from the menu bar.

2. Check Auto L ogin. A message at the bottom of the window indicates that auto login is enabled.

##### 11.1.4.14.2 Disabling Auto Login

To disable auto login:

1. Choose Wallet from the menu bar.

2. Uncheck Auto Login. A message at the bottom of the window indicates that auto login is disabled.

### 11.1.5 Managing Certificates

Oracle Wallet Manager uses two kinds of certificates: user certificates and trusted certificates. All certificates are signed data structures that bind a network identity with a corresponding public key. User certificates are used by end entities, including server applications, to validate an end entity's identity in a public key/private key exchange. In comparison, trusted certificates are any certificates that you trust, such as those provided by CAs to validate the user certificates that they issue.

This section describes how to manage both certificate types, in the following subtopics:

- Managing User Certificates

- Managing Trusted Certificates

  Note: Before a user certificate can be installed, the wallet must contain the trusted certificate representing the certificate authority who issued that user certificate. However, whenever you create a new wallet, several publicly trusted certificates are automatically installed, since they are so widely used. If the necessary certificate authority is not represented, you must install its certificate first. Also, you can import using the PKCS#7 certificate chain format, which gives you the user certificate and the CA certificate at the same time.

#### 11.1.5.1 Managing User Certificates

User certificates can be used by end users, smart cards, or applications, such as Web servers. Server certificates are a type of user certificate. For example, if a CA issues a certificate for a Web server, placing its distinguished name (DN) in the Subject field, then the Web server is the certificate owner, thus the "user" for this user certificate.

Managing user certificates involves the following tasks:

- Adding a Certificate Request

- Importing the User Certificate into the Wallet

- Importing Certificates Created with a Third-Party Tool

- Removing a User Certificate from a Wallet

- Removing a Certificate Request

- Exporting a User Certificate

- Exporting a User Certificate Request

##### 11.1.5.1.1 Adding a Certificate Request

You can add multiple certificate requests with Oracle Wallet Manager. When adding multiple requests, Oracle Wallet Manager automatically populates each subsequent request dialog box with the content of the initial request that you can then edit.

The actual certificate request becomes part of the wallet. You can reuse any certificate request to obtain a new certificate. However, you cannot edit an existing certificate request. Store only a correctly filled out certificate request in a wallet.

To create a PKCS #10 certificate request:

1. Choose Operations > Add Certificate Request. The Add Certificate Request dialog box appears.

2. Enter the information specified in Table 11-2.

3. Choose OK. A message informs you that a certificate request was successfully created. You can either copy the certificate request text from the body of this dialog panel and paste it into an e-mail message to send to a certificate authority, or you can export the certificate request to a file.

4. Choose OK to return to the Oracle Wallet Manager main window. The status of the certificate changes to [Requested].

   See Also: "Section 11.1.5.1.7, "Exporting a User Certificate Request"

Table 11-2 Certificate Request: Fields and Descriptions

Field Name | Description
--- | ---
Common Name | Mandatory. Enter the name of the user's or service's identity. Enter a user's name in first name /last name format. Example: Eileen.Sanger
Organizational Unit | Optional. Enter the name of the identity's organizational unit. Example: Finance.
Organization | Optional. Enter the name of the identity's organization. Example: XYZ Corp.
Locality/City | Optional. Enter the name of the locality or city in which the identity resides.
State/Province | Optional. Enter the full name of the state or province in which the identity resides. Enter the full state name, because some certificate authorities do not accept two–letter abbreviations.
Country | Mandatory. Choose to view a list of country abbreviations. Select the country in which the organization is located.
Key Size | Mandatory. Choose to view a list of key sizes to use when creating the public/private key pair. See Table 11-3 to evaluate key size.
Advanced | Optional. Choose Advanced to view the Advanced Certificate Request dialog panel. Use this field to edit or customize the identity's distinguished name (DN). For example, you can edit the full state name and locality.

Table 11-3 lists the available key sizes and the relative security each size provides. Typically, CAs use key sizes of 1024 or 2048. When certificate owners wish to keep their keys for a longer duration, they choose 3072 or 4096 bit keys.

Table 11-3 Available Key Sizes

Key Size | Relative Security Level
--- | ---
512 or 768 | Not regarded as secure.
1024 or 2048 | Secure.
3072 or 4096 | Very secure.

##### 11.1.5.1.2 Importing the User Certificate into the Wallet

When the Certificate Authority grants you a certificate, it may send you an e-mail that has your certificate in text (BASE64) form or attached as a binary file.

Note: Certificate authorities may send your certificate in a PKCS #7 certificate chain or as an individual X.509 certificate. Oracle Wallet Manager can import both types. PKCS #7 certificate chains are a collection of certificates, including the user's certificate and all of the supporting trusted CA and subCA certificates. In contrast, an X.509 certificate file contains an individual certificate without the supporting certificate chain. However, before you can import any such individual certificate, the signer's certificate must be a Trusted Certificate in the wallet.

To import the user certificate from the text of the Certificate Authority's e-mail, copy the certificate, represented as text (BASE64), from the certificate authority's e-mail message. Include the lines `Begin Certificate` and `End Certificate.`

1. Choose Operations > Import User Certificate.... The Import Certificate dialog box appears.

2. Choose Paste the certificate, and then click OK. Another Import Certificate dialog box appears with the following message:

       Please provide a base64 format certificate and paste it below.

3. Paste the certificate into the dialog box, and choose OK.

   1. If the certificate received is in PKCS#7 format, it is installed, and all the other certificates included with the PKCS#7 data are placed in the Trusted Certificate list.

   2. If the certificate received is not in PKCS#7 format, and the certificate of its CA is not already in the Trusted Certificates list, then more must be done. Oracle Wallet Manager will ask you to import the certificate of the CA that issued your certificate. This CA certificate will be placed in the Trusted Certificates list. (If the CA certificate was already in the Trusted Certificates list, your certificate is imported without additional steps.)

   After either (a) or (b) succeeds, a message at the bottom of the window confirms that the certificate was successfully installed. The Oracle Wallet Manager main window reappears, and the status of the corresponding entry in the left panel subtree changes to [Ready].

   - Note: The standard X.509 certificate includes the following start and end text:
         -----BEGIN CERTIFICATE-----
         -----END CERTIFICATE-----
   - A typical PKCS#7 certificate includes more, as described earlier, and includes the following start and end text:
         -----BEGIN PKCS7-----
         -----END PKCS7-----
   You can use the standard Ctrl+c to copy, including all dashes, and Ctrl+v to paste.

To import the certificate from a file:

  The user certificate in the file can be in either text (BASE64) or binary (`der`) format.

1. Choose Operations > Import User Certificate.... The Import Certificate dialog box appears.

2. Choose Select a file that contains the certificate, and click OK. Another Import Certificate dialog box appears.

3. Enter the path or folder name of the certificate file location.

4. Select the name of the certificate file (for example, `cert.txt`, `cert.der`).

5. Choose OK.

   1. If the certificate received is in PKCS#7 format, it is installed, and all the other certificates included with the PKCS#7 data are placed in the Trusted Certificate list.

   2. If the certificate received is not in PKCS#7 format, and the certificate of its CA is not already in the Trusted Certificates list, then more must be done. Oracle Wallet Manager will ask you to import the certificate of the CA that issued your certificate. This CA certificate will be placed in the Trusted Certificates list. (If the CA certificate was already in the Trusted Certificates list, your certificate is imported without additional steps.)

   After either (a) or (b) succeeds, a message at the bottom of the window confirms that the certificate was successfully installed. You are returned to the Oracle Wallet Manager main panel, and the status of the corresponding entry in the left panel subtree changes to [Ready.]

##### 11.1.5.1.3 Importing Certificates Created with a Third-Party Tool

Third-party certificates are those created from certificate requests that were not generated using Oracle Wallet Manager. These third-party certificates are actually wallets, in the Oracle sense, because they contain more than just the user certificate; they also contain the private key for that certificate. Furthermore, they include the chain of trusted certificates validating that the certificate was created by a trustworthy entity.

Oracle Wallet Manager makes these wallets available in a single step by importing them in PKCS#12 format, which includes all three elements described earlier: the user certificate, the private key, and the trusted certificates. It supports the following PKCS #12-format certificates:

- Netscape Communicator 4.x

- Microsoft Internet Explorer 5.x and later

Oracle Wallet Manager adheres to the PKCS#12 standard, so certificates exported by any PKCS#12-compliant tool should be usable with Oracle Wallet Manager.

Such third-party certificates cannot be stored into existing Oracle wallets because they would lack the private key and chain of trusted authorities. Therefore, each such certificate is exported and retrieved instead as an independent PKCS#12 file, that is, as its own wallet.

To import a certificate created with a third-party tool, you must first export it from the application you are using, and then save it as a wallet file that can be read by Oracle Wallet Manager.

To import a certificate created with a third-party tool, perform the following steps:

1. Follow the procedures for your particular product to export the certificate. Take the actions indicated in the exporting product to include the private key in the export, and specify the new password to protect the exported certificate. Also include all associated trust points. (Under PKCS #12, browsers do not necessarily export trusted certificate s, other than the signer's own certificate. You may need to add additional certificates to authenticate to your peers. You can use Oracle Wallet Manager to import trusted certificates.)

   The resulting file, contenting the certificate, the private key, and the trust points, is the new wallet that enables the third-party certificate to be used.

2. Save the exported certificate to a file name appropriate for your operating system in a directory expected by Oracle Wallet Manager.

   For UNIX and Windows, the appropriate file name is `ewallet.p12`.

   For other operating systems, see the Oracle documentation for the applicable operating system.

3. Use Oracle Wallet Manager to navigate to the directory in which you saved the `ewallet.p12` file and open it to use the PKI credentials it contains.

   Note: The password will be required whenever the associated application starts up or otherwise needs the certificate. To make such access automatic, see Section 11.1.4.14, "Using Auto Login". However, if the private key for the desired certificate is held in a separate hardware security module, you will not be able to import that certificate.

   If you exported the trusted certificate separately, then you must import the trusted certificate first before you open the `ewallet.p12` file that contains the imported third-party user certificate.

See Also: "Section 11.1.5.2.1, "Importing a Trusted Certificate"

##### 11.1.5.1.4 Removing a User Certificate from a Wallet

To remove a user certificate from a wallet:

1. In the left panel subtree, select the certificate that you want to remove.

2. Choose Operations > Remove User Certificate.... A dialog panel appears and prompts you to verify that you want to remove the user certificate from the wallet.

3. Choose Yes to return to the Oracle Wallet Manager main panel. The certificate displays a status of [Requested].

##### 11.1.5.1.5 Removing a Certificate Request

You must remove a certificate before removing its associated request.

To remove a certificate request:

1. In the left panel subtree, select the certificate request that you want to remove.

2. Choose Operations > Remove Certificate Request....

3. Click Yes. The certificate displays a status of [Empty].

##### 11.1.5.1.6 Exporting a User Certificate

To save the certificate in a file system directory, export the certificate by using the following steps:

1. In the left panel subtree, select the certificate that you want to export.

2. Choose Operations > Export User Certificate... from the menu bar. The Export Certificate dialog box appears.

3. Enter the file system directory location in which you want to save your certificate, or navigate to the directory structure under Folders.

4. Enter a file name for your certificate in the Enter File Name field.

5. Choose OK. A message at the bottom of the window confirms that the certificate was successfully exported to the file. You are returned to the Oracle Wallet Manager main window.

See Also: "Section 11.1.4.5, "Exporting Oracle Wallets to Third-Party Environments" for information about exporting wallets. Note that Oracle Wallet Manager supports storing multiple certificates in a single wallet, yet current browsers typically support only single-certificate wallets. For these browsers, you must export an Oracle wallet that contains a single key-pair.

##### 11.1.5.1.7 Exporting a User Certificate Request

To save the certificate request in a file system directory, export the certificate request by using the following steps:

1. In the left panel subtree, select the certificate request that you want to export.

2. Choose Operations > Export Certificate Request.... The Export Certificate Request dialog box appears.

3. Enter the file system directory location in which you want to save your certificate request, or navigate to the directory structure under Folders.

4. Enter a file name for your certificate request, in the Enter File Name field.

5. Choose OK. A message at the bottom of the window confirms that the certificate request was successfully exported to the file. You are returned to the Oracle Wallet Manager main window.

#### 11.1.5.2 Managing Trusted Certificates

Managing trusted certificates includes the following tasks:

- Importing a Trusted Certificate

- Removing a Trusted Certificate

- Exporting a Trusted Certificate

- Exporting All Trusted Certificates

##### 11.1.5.2.1 Importing a Trusted Certificate

You can import a trusted certificate into a wallet in either of two ways: paste the trusted certificate from an e-mail that you receive from the certificate authority, or import the trusted certificate from a file.

Oracle Wallet Manager automatically installs trusted certificates from VeriSign, RSA, Entrust, and GTE CyberTrust when you create a new wallet.

To copy and paste the text only (BASE64) trusted certificate:

Copy the trusted certificate from the body of the e-mail message you received that contained the user certificate. Include the lines `Begin Certificate` and `End Certificate.`

1. Choose Operations > Import Trusted Certificate... from the menu bar. The Import Trusted Certificate dialog panel appears.

2. Choose Paste the Certificate, and click OK. Another Import Trusted Certificate dialog panel appears with the following message:

       Please provide a base64 format certificate and paste it below.

3. Paste the certificate into the window, and click OK. A message at the bottom of the window informs you that the trusted certificate was successfully installed.

4. Choose OK. You are returned to the Oracle Wallet Manager main panel, and the trusted certificate appears at the bottom of the Trusted Certificates tree.

   Keyboard shortcuts for copying and pasting certificates: Use Ctrl+c to copy, and use Ctrl+v to paste.

To import a file that contains the trusted certificate:

  The file containing the trusted certificate should have been saved in either text (BASE64) or binary (`der`) format.

1. Choose Operations > Import Trusted Certificate.... The Import Trusted Certificate dialog panel appears.

2. Enter the path or folder name of the trusted certificate location.

3. Select the name of the trusted certificate file (for example, `cert.txt``)`.

4. Choose OK. A message at the bottom of the window informs you that the trusted certificate was successfully imported into the wallet.

5. Choose OK to exit the dialog panel. You are returned to the Oracle Wallet Manager main panel, and the trusted certificate appears at the bottom of the Trusted Certificates tree.

##### 11.1.5.2.2 R emoving a Trusted Certificate

You cannot remove a trusted certificate if it has been used to sign a user certificate still present in the wallet. To remove such trusted certificates, you must first remove the certificates it has signed. Also, you cannot verify a certificate after its trusted certificate has been removed from your wallet.

To remove a trusted certificate from a wallet:

1. Select the trusted certificate listed in the Trusted Certificates tree.

2. Choose Operations > Remove Trusted Certificate... from the menu bar.

   A dialog panel warns you that your user certificate will no longer be verifiable by its recipients if you remove the trusted certificate that was used to sign it.

3. Choose Yes. The selected trusted certificate is removed from the Trusted Certificates tree.

##### 11.1.5.2.3 Exporting a Trusted Certificate

To export a trusted certificate to another file system location:

1. In the left panel subtree, select the trusted certificate that you want to export.

2. Select Operations > Export Trusted Certificate.... The Export Trusted Certificate dialog box appears.

3. Enter a file system directory in which you want to save your trusted certificate, or navigate to the directory structure under Folders.

4. Enter a file name to save your trusted certificate.

5. Choose OK. You are returned to the Oracle Wallet Manager main window.

##### 11.1.5.2.4 Exporting All Trusted Certificates

To export all of your trusted certificates to another file system location:

1. Choose Operations > Export All Trusted Certificates.... The Export Trusted Certificate dialog box appears.

2. Enter a file system directory location in which you want to save your trusted certificates, or navigate to the directory structure under Folders.

3. Enter a file name to save your trusted certificates.

4. Choose OK. You are returned to the Oracle Wallet Manager main window.

## 11.2 Performing Certificate Validation and CRL Management with the orapki Utility

The `orapki` utility is a command-line tool that you can use to manage certificate revocation lists (CRLs), create and manage Oracle wallets, and to create signed certificates for testing purposes.

The following topics describe this tool and how to use it:

- orapki Overview

- Displaying orapki Help

- Creating Signed Certificates for Testing Purposes

- Managing Oracle Wallets with the orapki Utility

- Managing Certificate Revocation Lists (CRLs) with orapki Utility

- orapki Utility Commands Summary

### 11.2.1 orapki Overview

The `orapki` utility is provided to manage public key infrastructure (PKI) elements, such as wallets and certificate revocation lists, on the command line so the tasks it performs can be incorporated into scripts. This enables you to automate many of the routine tasks of maintaining a PKI.

This command-line utility can be used to perform the following tasks:

- Creating signed certificates for testing purposes

- Manage Oracle wallets:

  - Create and display Oracle wallets

  - Add and remove certificate requests

  - Add and remove certificates

  - Add and remove trusted certificates

- Manage certificate revocation lists (CRLs):

  - Renaming CRLs with a hash value for certificate validation

  - Uploading, listing, viewing, and deleting CRLs in Oracle Internet Directory

#### 11.2.1.1 orapki Utility Syntax

The basic syntax of the `orapki` command-line utility is as follows:

    orapki module command -parameter value

In the preceding command, `module` can be `wallet` (Oracle wallet), `crl` (certificate revocation list), or `cert` (PKI digital certificate). The available commands depend on the `module` you are using. For example, if you are working with a `wallet`, then you can add a certificate or a key to the wallet with the `add` command. The following example adds the user certificate located at `/private/lhale/cert.txt` to the wallet located at `ORACLE_HOME/wallet/ewallet.p12`:

    orapki wallet add -wallet ORACLE_HOME/wallet/ewallet.p12
    -user_cert -cert /private/lhale/cert.txt

### 11.2.2 Displaying orapki Help

You can display all the `orapki` commands that are available for a specific mode by entering the following at the command line:

    orapki mode help

For example, to display all available commands for managing certificate revocation lists (CRLs), enter the following at the command line:

    orapki CRL help

Note: Using the `-summary`, `-complete`, or `-wallet` command options is always optional. A command will still run if these command options are not specified.

### 11.2.3 Creating Signed Certificates for Testing Purposes

This command-line utility provides a convenient, lightweight way to create signed certificates for testing purposes. The following syntax can be used to create signed certificates and to view certificates:

To create a signed certificate for testing purposes:

    orapki cert create [-wallet wallet_location] -request
     certificate_request_location
    -cert certificate_location -validity number_of_days [-summary]

This command creates a signed certificate from the certificate request. The `-wallet` parameter specifies the wallet containing the user certificate and private key that will be used to sign the certificate request. The `-validity` parameter specifies the number of days, starting from the current date, that this certificate will be valid. Specifying a certificate and certificate request is mandatory for this command.

To view a certificate:

    orapki cert display -cert certificate_location [-summary | -complete]

This command enables you to view a test certificate that you have created with `orapki`. You can choose either `-summary` or `-complete`, which determines how much detail the command will display. If you choose `-summary`, the command will display the certificate and its expiration date. If you choose `-complete`, it will display additional certificate information, including the serial number and public key.

### 11.2.4 Managing Oracle Wallets with the orapki Utility

The following sections describe the syntax used to create and manage Oracle wallets with the `orapki` command-line utility. You can use these `orapki` utility `wallet` module commands in scripts to automate the wallet creation process.

- Creating and Viewing Oracle Wallets with orapki

- Adding Certificates and Certificate Requests to Oracle Wallets with orapki

- Exporting Certificates and Certificate Requests from Oracle Wallets with orapki

  Note: The `-wallet` parameter is mandatory for all `wallet` module commands.

#### 11.2.4.1 Creating and Viewing Oracle Wallets with orapki

To create an Oracle wallet:

    orapki wallet create -wallet wallet_location

This command will prompt you to enter and re-enter a wallet password. It creates a wallet in the location specified for `-wallet`.

To create an Oracle wallet with auto login enabled:

    orapki wallet create -wallet wallet_location -auto_login

This command creates a wallet with auto login enabled, or it can also be used to enable auto login on an existing wallet. If the `wallet_location` already contains a wallet, then auto login will be enabled for it. To turn the auto login feature off, use Oracle Wallet Manager. See Section 11.1.4.14, "Using Auto Login" for details.

Note: For wallets with the auto login feature enabled, you are prompted for a password only for operations that modify the wallet, such as `add`.

To view an Oracle wallet:

    orapki wallet display -wallet wallet_location

Displays the certificate requests, user certificates, and trusted certificates contained in the wallet.

#### 11.2.4.2 Adding Certificates and Certificate Requests to Oracle Wallets with orapki

To add a certificate request to an Oracle wallet:

    orapki wallet add -wallet wallet_location -dn user_dn -keySize 512|1024|2048

This command adds a certificate request to a wallet for the user with the specified distinguished name (`user_dn`). The request also specifies the requested certificate's key size (512, 1024, or 2048 bits). To sign the request, export it with the export option. See Section 11.2.4.3, "Exporting Certificates and Certificate Requests from Oracle Wallets with orapki".

To add a trusted certificate to an Oracle wallet:

    orapki wallet add -wallet wallet_location -trusted_cert -cert
    certificate_location

This command adds a trusted certificate, at the specified location (`-cert` `certificate_location`), to a wallet. You must add all trusted certificates in the certificate chain of a user certificate before adding a user certificate, or the command to add the user certificate will fail.

To add a root certificate to an Oracle wallet

    orapki wallet add -wallet wallet_location -dn
    certificate_dn -keySize 512|1024|2048 -self_signed -validity number_of_days

This command creates a new self-signed (root) certificate and adds it to the wallet. The `-validity` parameter (mandatory) specifies the number of days, starting from the current date, that this certificate will be valid. You can specify a key size for this root certificate (`-keySize`) of 512, 1024, or 2048 bits.

To add a user certificate to an Oracle wallet:

    orapki wallet add -wallet wallet_location -user_cert -cert certificate_location

This command adds the user certificate at the location specified with the `-cert` parameter to the Oracle wallet at the `wallet_location`. Before you add a user certificate to a wallet, you must add all the trusted certificates that make up the certificate chain. If all trusted certificates are not installed in the wallet before you add the user certificate, then adding the user certificate will fail.

#### 11.2.4.3 Exporting Certificates and Certificate Requests from Oracle Wallets with orapki

To export a certificate from an Oracle wallet:

    orapki wallet export -wallet wallet_location -dn
    certificate_dn -cert certificate_filename

This command exports a certificate with the subject's distinguished name (`-dn`) from a wallet to a file that is specified by `-cert`.

To export a certificate request from an Oracle wallet:

    orapki wallet export -wallet wallet_location -dn
    certificate_request_dn -request certificate_request_filename

This command exports a certificate request with the subject's distinguished name (`-dn`) from a wallet to a file that is specified by `-request`.

### 11.2.5 Managing Certificate Revocation Lists (CRLs) with orapki Utility

CRLs must be managed with `orapki`. This utility creates a hashed value of the CRL issuer's name to identify the CRLs location in your system. If you do not use `orapki`, your Oracle server cannot locate CRLs to validate PKI digital certificates. The following sections describe CRLS, how you use them, and how to use orapki to manage them:

- Section 11.2.5.1, "About Certificate Validation with Certificate Revocation Lists"

- Section 11.2.5.2, "Certificate Revocation List Management"

#### 11.2.5.1 About Certificate Validation with Certificate Revocation Lists

The process of determining whether a given certificate can be used in a given context is referred to as certificate validation. Certificate validation includes determining that

- A trusted certificate authority (CA) has digitally signed the certificate

- The certificate's digital signature corresponds to the independently-calculated hash value of the certificate itself and the certificate signer's (CA's) public key

- The certificate has not expired

- The certificate has not been revoked

The SSL network layer automatically performs the first three validation checks, but you must configure certificate revocation list (CRL) checking to ensure that certificates have not been revoked. CRLs are signed data structures that contain a list of revoked certificates. They are usually issued and signed by the same entity who issued the original certificate.

##### 11.2.5.1.1 What CRLs Should You Use?

You should have CRLs for all of the trust points that you honor. The trust points are the trusted certificates from a third party identity that is qualified with a level of trust. Typically, the certificate authorities you trust are called trust points.

##### 11.2.5.1.2 How CRL Checking Works

Certificate revocation status is checked against CRLs which are located in file system directories, Oracle Internet Directory, or downloaded from the location specified in the CRL Distribution Point (CRL DP) extension on the certificate. If you store your CRLs on the local file system or in the directory, then you must update them regularly. If you use CRL DPs then CRLs are downloaded each time a certificate is used so there is no need to regularly refresh the CRLs.

The server searches for CRLs in the following locations in the order listed. When the system finds a CRL that matches the certificate CA's DN, it stops searching.

1. Local file system

   The system checks the `sqlnet.ora` file for the `SSL_CRL_FILE` parameter first, followed by the `SSL_CRL_PATH` parameter. If these two parameters are not specified, then the system checks the wallet location for any CRLs.

   Note: if you store CRLs on your local file system, then you must use the `orapki` utility to periodically update them. See "Renaming CRLs with a Hash Value for Certificate Validation" on page 1-28

2. Oracle Internet Directory

   If the server cannot locate the CRL on the local file system and directory connection information has been configured in the `ORACLE_HOME/ldap/admin/ldap.ora` file, then the server searches in the directory. It searches the CRL subtree by using the CA's distinguished name (DN) and the DN of the CRL subtree.

   The server must have a properly configured `ldap.ora` file to search for CRLs in the directory. It cannot use the Domain Name System (DNS) discovery feature of Oracle Internet Directory. Also note that if you store CRLs in the directory, then you must use the `orapki` utility to periodically update them. See "Uploading CRLs to Oracle Internet Directory" on page 1-28

3. CRL DP

   If the CA specifies a location in the CRL DP X.509, version 3, certificate extension when the certificate is issued, then the appropriate CRL that contains revocation information for that certificate is downloaded. Currently, Oracle Advanced Security supports downloading CRLs over HTTP and LDAP.

   Notes: For performance reasons, only user certificates are checked. Oracle recommends that you store CRLs in the directory rather than the local file system.

#### 11.2.5.2 Certificate Revocation List Management

Before you can enable certificate revocation status checking, you must ensure that the CRLs you receive from the CAs you use are in a form (renamed with a hash value) or in a location (uploaded to the directory) in which your system can use them. Oracle Advanced Security provides a command-line utility, `orapki`, that you can use to perform the following tasks:

- Renaming CRLs with a Hash Value for Certificate Validation

- UploadingCRLs to Oracle Internet Directory

- Listing CRLs Stored in Oracle Internet Directory

- Viewing CRLs in Oracle Internet Directory

- Deleting CRLs from Oracle Internet Directory

  Note: CRLs must be updated at regular intervals (before they expire) for successful validation. You can automate this task by using `orapki` commands in a script.

You can also use LDAP command-line tools to manage CRLs in Oracle Internet Directory.

See Also: Appendix A, "Syntax for Command-Line Tools" in Oracle Identity Management Application Developer's Guide for information about LDAP command-line tools and their syntax.

##### 11.2.5.2.1 Renaming CRLs with a Hash Value for Certificate Validation

When the system validates a certificate, it must locate the CRL issued by the CA who created the certificate. The system locates the appropriate CRL by matching the issuer name in the certificate with the issuer name in the CRL.

When you specify a CRL storage location for the Certificate Revocation Lists Path field in Oracle Net Manager (sets the `SSL_CRL_PATH` parameter in the `sqlnet.ora` file), use the `orapki` utility to rename CRLs with a hash value that represents the issuer's name. Creating the hash value enables the server to load the CRLs.

On UNIX operating systems, `orapki` creates a symbolic link to the CRL. On Windows operating systems, it creates a copy of the CRL file. In either case, the symbolic link or the copy created by `orapki` are named with a hash value of the issuer's name. Then when the system validates a certificate, the same hash function is used to calculate the link (or copy) name so the appropriate CRL can be loaded.

Depending on your operating system, enter one of the following commands to rename CRLs stored in the file system.

To rename CRLs stored in UNIX file systems:

    orapki crl hash -crl crl_filename [-wallet wallet_location]
    -symlink crl_directory [-summary]

To rename CRLs stored in Windows file systems:

    orapki crl hash -crl crl_filename
    [-wallet wallet_location] -copy crl_directory [-summary]

In the preceding commands, `crl_filename` is the name of the CRL file, `wallet_location` is the location of a wallet that contains the certificate of the CA that issued the CRL, and `crl_directory` is the directory in which the CRL is located.

Using `-wallet` and `-summary` are optional. Specifying `-wallet` causes the tool to verify the validity of the CRL against the CA's certificate prior to renaming the CRL. Specifying the `-summary` option causes the tool to display the CRL issuer's name.

##### 11.2.5.2.2 Uploading CRLs to Oracle Internet Directory

Publishing CRLs in the directory enables CRL validation throughout your enterprise, eliminating the need for individual applications to configure their own CRLs. All applications can use the CRLs stored in the directory in which they can be centrally managed, greatly reducing the administrative overhead of CRL management and use.

The user who uploads CRLs to the directory by using `orapki` must be a member of the directory group `CRLAdmins` (`cn=CRLAdmins,cn=groups,%s_OracleContextDN%`). This is a privileged operation because these CRLs are accessible to the entire enterprise. Contact your directory administrator to be added to this administrative directory group.

To upload CRLs to the directory, enter the following at the command line:

    orapki crl upload -crl crl_location
    -ldap hostname:ssl_port -user username [-wallet wallet_location] [-summary]

In the preceding command, `crl_location` is the file name or URL in which the CRL is located, `hostname` and `ssl_port` (SSL port with no authentication) are for the system on which your directory is installed, `username` is the directory user who has permission to add CRLs to the CRL subtree, and `wallet_location` is the location of a wallet that contains the certificate of the CA that issued the CRL.

Using `-wallet` and `-summary` are optional. Specifying `-wallet` causes the tool to verify the validity of the CRL against the CA's certificate prior to uploading it to the directory. Specifying the `-summary` option causes the tool to print the CRL issuer's name and the LDAP entry in which the CRL is stored in the directory.

Note: The `orapki` utility will prompt you for the directory password when you perform this operation. Ensure that you specify the directory SSL port on which the Diffie-Hellman-based SSL server is running. This is the SSL port that does not perform authentication. Neither the server authentication nor the mutual authentication SSL ports are supported by the `orapki` utility.

##### 11.2.5.2.3 Listing CRLs Stored in Oracle Internet Directory

You can display a list of all CRLs stored in the directory with `orapki`, which is useful for browsing to locate a particular CRL to view or download to your local system. This command displays the CA who issued the CRL (Issuer) and its location (DN) in the CRL subtree of your directory.

To list CRLs in Oracle Internet Directory, enter the following at the command line:

    orapki crl list -ldap hostname:ssl_port

In the preceding command, the `hostname` and `ssl_port` are for the system on which your directory is installed. Note that this is the directory SSL port with no authentication as described in the preceding section.

##### 11.2.5.2.4 Viewing CRLs in Oracle Internet Directory

You can view specific CRLs that are stored in Oracle Internet Directory in a summarized format or you can request a complete listing of revoked certificates for the specified CRL. A summary listing provides the CRL issuer's name and its validity period. A complete listing provides a list of all revoked certificates contained in the CRL.

To view a summary listing of a CRL in Oracle Internet Directory, enter the following at the command line:

    orapki crl display -crl crl_location [-wallet wallet_location] -summary

In the preceding command, `crl_location` is the location of the CRL in the directory. It is convenient to paste the CRL location from the list that displays when you use the `orapki crl list` command. See: "Listing CRLs Stored in Oracle Internet Directory" on page 1-29.

To view a list of all revoked certificates contained in a specified CRL, which is stored in Oracle Internet Directory, enter the following at the command line:

    orapki crl display -crl crl_location [-wallet wallet_location] -complete

For example, the following `orapki` command:

    orapki crl display -crl $T_WORK/pki/wlt_crl/nzcrl.txt -wallet $T_WORK/pki/wlt_crl -complete

produces the following output, which lists the CRL issuer's DN, its publication date, date of its next update, and the revoked certificates it contains:

    issuer = CN=root,C=us, thisUpdate = Sun Nov 16 10:56:58 PST 2003,
    nextUpdate = Mon Sep 30 11:56:58 PDT 2013, revokedCertificates =
    {(serialNo = 153328337133459399575438325845117876415,
    revocationDate - Sun Nov 16 10:56:58 PST 2003)}
    CRL is valid

Using the `-wallet` option causes the `orapki crl display` command to validate the CRL against the CA's certificate.

Depending on the size of your CRL, choosing the `-complete` option may take a long time to display.

You can also use Oracle Directory Manager, a graphical user interface tool that is provided with Oracle Internet Directory, to view CRLs in the directory. CRLs are stored in the following directory location:

    cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext

##### 11.2.5.2.5 Deleting CRLs from Oracle Internet Directory

The user who deletes CRLs from the directory by using `orapki` must be a member of the directory group `CRLAdmins`. See Section 11.2.5.2.2, "UploadingCRLs to Oracle Internet Directory" for information about this directory administrative group.

To delete CRLs from the directory, enter the following at the command line:

    orapki crl delete -issuer issuer_name -ldap hostname:ssl_port
    -user username [-summary]

In the preceding command, `issuer_name` is the name of the CA who issued the CRL, the `hostname` and `ssl_port` are for the system on which your directory is installed, and `username` is the directory user who has permission to delete CRLs from the CRL subtree. Note that this must be a directory SSL port with no authentication. See Section 11.2.5.2.2, "UploadingCRLs to Oracle Internet Directory" for more information about this port.

Using the `-summary` option causes the tool to print the CRL LDAP entry that was deleted.

For example, the following `orapki` command:

    orapki crl delete -issuer "CN=root,C=us"
    -ldap machine1:3500 -user cn=orcladmin -summary

produces the following output, which lists the location of the deleted CRL in the directory:

    Deleted CRL at cn=root
    cd45860c.rN,cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext

### 11.2.6 orapki Utility Commands Summary

This section lists and describes the following `orapki` commands:

- orapki cert create

- orapki cert display

- orapki crl delete

- orapki crl display

- orapki crl hash

- orapki crl list

- orapki crl upload

- orapki wallet add

- orapki wallet create

- orapki wallet display

- orapki wallet export

#### 11.2.6.1 orapki cert create

The following sections describe this command.

##### 11.2.6.1.1 Purpose

Use this command to create a signed certificate for testing purposes.

##### 11.2.6.1.2 Syntax

    orapki cert create [-wallet wallet_location]
    -request certificate_request_location
    -cert certificate_location -validity number_of_days [-summary]

- The `-wallet` parameter specifies the wallet containing the user certificate and private key that will be used to sign the certificate request.

- The `-request` parameter (mandatory) specifies the location of the certificate request for the certificate you are creating.

- The `-cert` parameter (mandatory) specifies the directory location in which the tool places the new signed certificate.

- The `-validity` parameter (mandatory) specifies the number of days, starting from the current date, that this certificate will be valid.

#### 11.2.6.2 orapki cert display

The following sections describe this command.

##### 11.2.6.2.1 Purpose

Use this command to display details of a specific certificate.

##### 11.2.6.2.2 Syntax

    orapki cert display -cert certificate_location [-summary|-complete]

- The `-cert` parameter specifies the location of the certificate you want to display.

- You can use either the `-summary` or the `-complete` parameter to display the following information:

  - `-summary` displays the certificate and its expiration date

  - `-complete` displays additional certificate information, including the serial number and public key

#### 11.2.6.3 orapki crl delete

The following sections describe this command.

##### 11.2.6.3.1 Purpose

Use this command to delete CRLs from Oracle Internet Directory. Note that the user who deletes CRLs from the directory by using `orapki` must be a member of the `CRLAdmins` (`cn=CRLAdmins,cn=groups,%s_OracleContextDN%`) directory group.

##### 11.2.6.3.2 Prerequisites

None

##### 11.2.6.3.3 Syntax

    orapki crl delete -issuer issuer_name
    -ldap hostname:ssl_port -user username [-summary]

- The `-issuer` parameter specifies the name of the certificate authority (CA) who issued the CRL.

- The `-ldap` parameter specifies the hostname and SSL port for the directory in which the CRLs are to be deleted. Note that this must be a directory SSL port with no authentication. See "Uploading CRLs to Oracle Internet Directory" on page 7-29 for more information about this port.

- The `-user` parameter specifies the username of the directory user who has permission to delete CRLs from the CRL subtree in the directory.

- The `-summary` parameter is optional. Using it causes the tool to print the CRL LDAP entry that was deleted.

#### 11.2.6.4 orapki crl display

The following sections describe this command.

##### 11.2.6.4.1 Purpose

Use this command to display specific CRLs that are stored in Oracle Internet Directory.

##### 11.2.6.4.2 Syntax

    orapki crl display -crl crl_location
    [-wallet wallet_location] [-summary|-complete]

- The `-crl` parameter specifies the location of the CRL in the directory. It is convenient to paste the CRL location from the list that displays when you use the `orapki crl list` command. See "orapki crl list" on page 1-33

- The `-wallet` parameter (optional) specifies the location of the wallet that contains the certificate of the certificate authority (CA) who issued the CRL. Using it causes the tool to verify the validity of the CRL against the CA's certificate prior to displaying it.

- Choosing either the -summary or the -complete parameters displays the following information:

  - `-summary` provides a listing that contains the CRL issuer's name and the CRL's validity period

  - `-complete` provides a list of all revoked certificates that the CRL contains. Note that this option may take a long time to display, depending on the size of the CRL.

#### 11.2.6.5 orapki crl hash

The following sections describe this command.

##### 11.2.6.5.1 Purpose

Use this command to generate a hash value of the certificate revocation list (CRL) issuer to identify the location of the CRL in your file system for certificate validation.

##### 11.2.6.5.2 Syntax

    orapki crl hash -crl crl_filename|URL
    [-wallet wallet_location] [-symlink|-copy] crl_directory [-summary]

- The `-crl` parameter specifies the filename that contains the CRL or the URL in which it can be found.

- The `-wallet` parameter (optional) specifies the location of the wallet that contains the certificate of the certificate authority (CA) who issued the CRL. Using it causes the tool to verify the validity of the CRL against the CA's certificate prior to uploading it to the directory.

- Depending on your operating system, use either the `-symlink` or the `-copy` parameter:

  - (UNIX) use `-symlink` to create a symbolic link to the CRL at the `crl_directory` location

  - (Windows) use `-copy` to create a copy of the CRL at the `crl_directory` location

- The `-summary` parameter (optional) causes the tool to display the CRL issuer's name.

#### 11.2.6.6 orapki crl list

The following sections describe this command.

##### 11.2.6.6.1 Purpose

Use this command to display a list of CRLs stored in Oracle Internet Directory. This is useful for browsing to locate a particular CRL to view or download to your local file system.

##### 11.2.6.6.2 Syntax

    orapki crl list -ldap hostname:ssl_port

The `-ldap` parameter specifies the hostname and SSL port for the directory server from which you want to list CRLs. Note that this must be a directory SSL port with no authentication. See Section 11.2.5.2.2, "UploadingCRLs to Oracle Internet Directory" for more information about this port.

#### 11.2.6.7 orapki crl upload

The following sections describe this command.

##### 11.2.6.7.1 Purpose

Use this command to upload certificate revocation lists (CRLs) to the CRL subtree in Oracle Internet Directory. Note that you must be a member of the directory administrative group `CRLAdmins` (`cn=CRLAdmins,cn=groups,%s_OracleContextDN%`) to upload CRLs to the directory.

##### 11.2.6.7.2 Syntax

    orapki crl upload -crl crl_location
    -ldap hostname:ssl_port -user username
    [-wallet wallet_location] [-summary]

- The `-crl` parameter specifies the directory location or the URL of the CRL that you are uploading to the directory.

- The `-ldap` parameter specifies the hostname and SSL port for the directory to which you are uploading the CRLs. Note that this must be a directory SSL port with no authentication. See Section 11.2.5.2.2, "UploadingCRLs to Oracle Internet Directory" for more information about this port.

- The `-user` parameter specifies the username of the directory user who has permission to add CRLs to the CRL subtree in the directory.

- The `-wallet` parameter specifies the location of the wallet that contains the certificate of the certificate authority (CA) who issued the CRL. This is an optional parameter. Using it causes the tool to verify the validity of the CRL against the CA's certificate prior to uploading it to the directory.

- The `-summary` parameter is also optional. Using it causes the tool to display the CRL issuer's name and the LDAP entry in which the CRL is stored in the directory.

#### 11.2.6.8 orapki wallet add

The following sections describe this command.

##### 11.2.6.8.1 Purpose

Use this command to add certificate requests and certificates to an Oracle wallet.

##### 11.2.6.8.2 Syntax

To add certificate requests:

    orapki wallet add -wallet wallet_location -dn user_dn -keySize 512|1024|2048

- The `-wallet` parameter specifies the location of the wallet to which you want to add a certificate request.

- The `-dn` parameter specifies the distinguished name of the certificate owner.

- The `-keySize` parameter specifies the key size for the certificate.

- To sign the request, export it with the export option. See Section 11.2.6.11, "orapki wallet export".

To add trusted certificates:

    orapki wallet add -wallet wallet_location -trusted_cert -cert certificate_location

- The `-trusted_cert` parameter causes the tool to add the trusted certificate, at the location specified with `-cert`, to the wallet.

To add root certificates:

    orapki wallet add -wallet wallet_location -dn
    certificate_dn -keySize 512|1024|2048 -self_signed -validity number_of_days

- The `-self_signed` parameter causes the tool to create a root certificate.

- The `-validity` parameter is mandatory. Use it to specify the number of days, starting from the current date, that this root certificate will be valid.

To add user certificates:

    orapki wallet add -wallet wallet_location -user_cert -cert certificate_location

- The `-user_cert` parameter causes the tool to add the user certificate at the location specified with the `-cert` parameter to the wallet. Before you add a user certificate to a wallet, you must add all the trusted certificates that make up the certificate chain. If all trusted certificates are not installed in the wallet before you add the user certificate, then adding the user certificate will fail.

#### 11.2.6.9 orapki wallet create

The following sections describe this command.

##### 11.2.6.9.1 Purpose

Use this command to create an Oracle wallet or to set auto login on for an Oracle wallet.

##### 11.2.6.9.2 Syntax

    orapki wallet create -wallet wallet_location [-auto_login]

- The `-wallet` parameter specifies a location for the new wallet or the location of the wallet for which you want to turn on auto login.

- The `-auto_login` parameter creates an auto login wallet, or it turns on automatic login for the wallet specified with the `-wallet` option. See Section 11.1.4.14, "Using Auto Login" for details about auto login wallets.

#### 11.2.6.10 orapki wallet display

The following sections describe this command.

##### 11.2.6.10.1 Purpose

Use this command to view the certificate requests, user certificates, and trusted certificates in an Oracle wallet.

##### 11.2.6.10.2 Syntax

    orapki wallet display -wallet wallet_location

- The `-wallet` parameter specifies a location for the wallet you want to open if it is not located in the current working directory.

#### 11.2.6.11 orapki wallet export

The following sections describe this command.

##### 11.2.6.11.1 Purpose

Use this command to export certificate requests and certificates from an Oracle wallet.

##### 11.2.6.11.2 Syntax

To export a certificate from an Oracle wallet:

    orapki wallet export -wallet wallet_location -dn
    certificate_dn -cert certificate_filename

- The `-wallet` parameter specifies the location of the wallet from which you want to export the certificate.

- The `-dn` parameter specifies the distinguished name of the certificate.

- The `-cert` parameter specifies the name of the file that contains the exported certificate.

To export a certificate request from an Oracle wallet:

    orapki wallet export -wallet wallet_location -dn
    certificate_request_dn -request certificate_request_filename

- The `-request` parameter specifies the name of the file that contains the exported certificate request.

## 11.3 Interoperability with X.509 Certificates

Oracle Wallet Manager functionality supports users who already have certificates provisioned. If you do not use Oracle Wallet Manager to create certificates, you can use it to manage and store certificates created previously.

### 11.3.1 Public-Key Cryptography Standards (PKCS) Support

Oracle Wallet Manager stores X.509 certificates and private keys in Public-Key Cryptography Standards (PKCS) #12 format, and generates certificate requests according to the PKCS #10 specification developed by RSA Laboratories. This makes the Oracle wallet structure interoperable with supported third party PKI applications, and provides wallet portability across operating systems.

Oracle Wallet Manager wallets can be enabled to store credentials on hardware security modules using APIs that conform to the PKCS #11 specification. When `PKCS11` wallet type is chosen at the time of wallet creation, then all keys stored in that wallet are saved to a hardware security module or token, such as smart cards, PCMCIA cards, smart diskettes, or other types of portable hardware devices that store private keys, perform cryptographic operations, or both.

- See Also: Section 11.1.5.1.3, "Importing Certificates Created with a Third-Party Tool" Section 11.1.4.5, "Exporting Oracle Wallets to Third-Party Environments" Section 11.1.4.2.2, "Creating a Wallet to Store Hardware Security Module Credentials" To view PKCS standards documents, navigate to the following URL:
      http://www.rsasecurity.com/rsalabs/

### 11.3.2 Multiple Certificate Support

Oracle Wallet Manager enables you to store multiple certificates for each wallet, supporting the following Oracle PKI certificate usages:

- SSL

- S/MIME signature

- S/MIME encryption

- Code-Signing

- CA Certificate Signing

Oracle Wallet Manager supports multiple certificates for a single digital entity, where each certificate can be used for a set of Oracle PKI certificate usages, but the same certificate cannot be used for all such usages (See Table 11-4 and Table 11-5 for legal usage combinations). There must be a one-to-one mapping between certificate requests and certificates. The same certificate request can be used to obtain multiple certificates; however, more than one certificate for each certificate request cannot be installed in the same wallet at the same time.

Oracle Wallet Manager uses the X.509 Version 3 `KeyUsage` extension types to define Oracle PKI certificate usages. The key usage extension types are optional bits that can be set in certificates. Setting these bits defines what purpose the certificate's key can be used for. When certificates are issued, the certificate authority sets these bits according to the type of certificate that you have requested. Table 11-4 lists and describes these key usage types.

Table 11-4 X.509 Version 3 KeyUsage Extension Types, Values, and Descriptions

KeyUsage Extension Type | Value | Description
--- | --- | ---
digitalSignature | 0 | Used for entity authentication and to authenticate data origin integrity.
nonRepudiation | 1 | Used to protects against the signing entity falsely denying some action.
keyEncipherment | 2 | Used when the subject public key is used for key transport.
dataEncipherment | 3 | Used when the subject public key is used for enciphering data, other than cryptographic keys.
keyAgreement | 4 | Used when the subject public key is used for key agreement during SSL connection negotiation.
keyCertSign | 5 | Used when the subject public key is used for verifying a signature on certificates. May only be used in CA certificates.
cRLSign | 6 | Used when the subject public key is used for verifying a signature on certificate revocation lists.
encipherOnly | 7 | When the encipherOnly bit is asserted, the keyAgreement bit must also be set. When these two bits are set the subject public key may be used only for enciphering data while performing key agreement.
decipherOnly | 8 | As with the encipherOnly bit, the keyAgreement bit must also be set when decipherOnly is set. When these two bits (decipherOnly and keyAgreement) are set the subject public key may be used only for deciphering data while performing key agreement.

See Also: The Internet Engineering Task Force RFC #2459, Internet X.509 Public Key Infrastructure Certificate and CRL Profile, for a complete description of the `KeyUsage` extension types at the following URL:
    http://www.ietf.org/rfc/

When installing a certificate (user certificate or trusted certificate), Oracle Wallet Manager maps the `KeyUsage` extension values to Oracle PKI certificate usages as specified in Table 11-4 and Table 11-5.

Table 11-5 Oracle Wallet Manager Import of Trusted Certificates to an Oracle Wallet

KeyUsage Value | Critical?Foot 1 | Usage
--- | --- | ---
none | NA | Importable.
Any combination excluding 5 | Yes | Not importable.
Any combination excluding 5 | No | Importable.
5 alone, or any combination including 5 | an | Importable.

Footnote 1 If the `KeyUsage` extension is critical, the certificate cannot be used for other purposes.

You should obtain certificates from the certificate authority with the correct `KeyUsage` value for the required Oracle PKI certificate usage. A single wallet can contain multiple key pairs for the same usage. Each certificate can support multiple Oracle PKI certificate usages, as indicated by Table 11-4 and Table 11-5. Oracle PKI applications use the first certificate containing the required PKI certificate usage.

For example, for SSL usage, the first certificate containing the SSL Oracle PKI certificate usage is used.

If you do not have a certificate with SSL usage, then an `ORA-28885` error (`No certificate with required key usage found`) is returned.