7 Managing Keystores, Wallets, and Certificates

This chapter explains how to use Oracle Fusion Middleware security features to administer keystores, keys, and certificates. These artifacts are used to configure SSL and related tasks for Oracle Fusion Middleware components.

This chapter contains these sections:

7.1 Key and Certificate Storage in Oracle Fusion Middleware

Keys and certificates are used to digitally sign and verify data and achieve authentication, integrity, and privacy in network communications.

Private keys, digital certificates, and trusted CA certificates are stored in keystores. This section describes the keystores available in Oracle Fusion Middleware and contains these topics:

7.1.1 Types of Keystores

Oracle Fusion Middleware provides various types of keystores for keys and certificates as shown in Table 7-1:

Table 7-1 Keystore Types in Oracle Fusion Middleware

Keystore Type Description Protection Mechanism

Oracle Wallet

Oracle Wallet

Password or auto-login

JKS

Java Keystore

Password

KSS

OPSS Keystore Service

Password or policy

7.1.1.1 About Oracle Wallet

An Oracle wallet is a container that stores your credentials, such as certificates, trusted certificates, certificate requests, and private keys. You can store Oracle wallets on the file system or in LDAP directories such as Oracle Internet Directory. Oracle wallets can be auto-login or password-protected wallets.

When creating a wallet, you can:

  • Pre-populate it with a self-signed certificate. Such a wallet is called a test wallet and is typically used in development and testing phases.

  • Create a certificate request, so that you can request a signed certificate back from a Certificate Authority (CA). Once the CA sends the certificate back, it is imported into the wallet. Such a wallet is called a third-party wallet.

Either the test wallet or the third-party wallet may be password-protected, or may be configured to not require a password, in which case it is called an auto-login wallet.

Oracle Wallets are used for Oracle HTTP Server. As of Oracle Fusion Middleware 12c (12.1.3), you can take advantage of the central storage and unified management available with the Keystore Service to manage wallets and their contents through the export, import, and synchronization features of that service.

See Also:

7.1.1.2 About the JKS Keystore

A JKS keystore is the default JDK implementation of Java keystores. Java EE applications can use the JKS-based keystore and truststore.

7.1.1.3 About the Keystore Service (KSS) Keystore

The OPSS Keystore Service enables you to manage keys and certificates for SSL, message security, encryption, and related tasks.

The Keystore Service offers several advantages including policy-based protection and centralized management of keystores and truststores, expiring certificates, and other key material.

In Oracle Fusion Middleware 12c (12.1.3), Oracle WebLogic Server:

  • uses the Keystore Service out-of-the-box

  • uses JKS by default in upgraded environments.

7.1.2 Keystore Management Tools

Oracle Fusion Middleware provides these options for keystore operations:

  • WLST, a command-line interface for JKS keystores and Oracle wallets

  • orapki, a command-line tool for wallets

  • Fusion Middleware Control, a graphical user interface

About Importing DER-encoded Certificates

You cannot use Fusion Middleware Control or the WLST command-line tool to import DER-encoded certificates or trusted certificates into an Oracle wallet. Use orapki command-line tool instead.

Using a Keystore Not Created with WLST or Fusion Middleware Control

If an Oracle wallet was created with tools such as orapki, it must be imported prior to use. Specifically for Oracle HTTP Server, if a wallet was created using orapki, in order to view or manage it in Fusion Middleware Control you must first import it with either Fusion Middleware Control or the WLST importWallet command. For details, see Section 7.4.4.5.1 and Section 7.4.4.5.2.

Copying Keystores to File System Not Supported

Creating, renaming, or copying keystores directly to any directory on the file system is not supported. Any pre- existing keystore or wallet that you wish to use must be imported using either Fusion Middleware Control or the WLST utility.

Managing Wallets in a Stand-alone Environment

In a stand-alone environment, such as a stand-alone OHS installation, the keystore management features are provided by the database.

For details, see Administering Oracle HTTP Server:

JDK7 Requirement for Self-Signed Certificates

JDK7 requires the keyUsage extension for self-signed CA certificates used for SSL configuration. For details, see Section H.3.3.

Additional Information

Details about the tools are provided in these sections:

7.2 Command-Line Interface for Keystores and Wallets

Oracle Fusion Middleware provides a set of WLST scripts to create and manage keystores and Oracle wallets, and to manipulate their stored objects.

7.2.1 How to Launch the Command-Line Interface

When running SSL WLST commands, you must invoke the WLST script from the Oracle Common home. (See Section 7.2.1 for more information.)

This brings up the WLST shell. Connect to a running Oracle WebLogic Server instance by specifying the user name, password, and connect URL. After connecting, you are now ready to run SSL-related WLST commands as explained in the subsequent sections.

Note:

All SSL-related WLST commands require you to launch the script from the above-mentioned location only.

Here is the basic execution sequence:

./wlst.sh
connect('weblogic','weblogic1') --- To connect to WebLogic Admin Server
editCustom()
startEdit()
wlstCommand('param1', 'param2', 'param3', 'param4')
save()
activate()

where wlstCommand is the actual WLST command. For example, to create an OHS wallet:

connect('weblogic','weblogic1') --- For connecting to WLS Admin Server
editCustom()
startEdit()
createWallet('ohs1', 'ohs1', 'ohs', 'testwallet')
save()
activate()

In this command the first two parameters both refer to the component instance name (in contrast with earlier releases where they referred to an Oracle instance and a component instance respectively, in this release both refer to the latter), the third parameter is the component, and the fourth parameter is the wallet name.

Here is a sample output for createWallet:

wls:/base_domain/serverConfig> editCustom()
Location changed to edit custom tree. This is a writable tree with No root.
For more help, use help('editCustom')
 
wls:/base_domain/editCustom> startEdit()
Starting an edit session ...
Started edit session, please be sure to save and activate your
changes once you are done.
wls:/base_domain/editCustom> createWallet('ohs1','ohs1','ohs','testwallet','Welcome1')
Wallet created
wls:/base_domain/editCustom> save()
Saving all your changes ...
Saved all your changes successfully.
wls:/base_domain/editCustom> activate()
Activating all your changes, this may take a while ...
The edit lock associated with this edit session is released
once the activation is completed.
Activation completed

7.3 Keystore Management

For details about Keystore Service (KSS) keystore management, see "Keystore Management with the Keystore Service" in Securing Applications with Oracle Platform Security Services.

7.4 Wallet Management

This section contains the following topics:

This discussion assumes that components are installed within a WebLogic domain. For wallet configuration in a stand-alone context, for example a stand-alone Oracle HTTP Server, see Appendix G.

7.4.1 About Wallets and Certificates

This section contains the following topics:

7.4.1.1 About Password-Protected and Autologin Wallets

You can create two types of wallets:

  • Auto-login wallet

    This is an obfuscated form of a PKCS#12 wallet that provides PKI-based access to services and applications without requiring a password at runtime. You can also add to, modify, or delete the wallet without needing a password. File system permissions provide the necessary security for auto-login wallets.

    Note:

    In previous releases, you could create a wallet with a password and then enable auto-login to create an obfuscated wallet. With 12c (12.1.3), auto-login wallets are created without a password. When using such a wallet, you do not need to specify a password.

    If using an auto-login wallet without a password, specify a null password ("") in the ldapbind command.

    Older type of wallets (such as Release 10g wallets) will continue to work as they did earlier.

  • Password-protected wallet

    As the name suggests, this type of wallet is protected by a password. Any addition, modification, or deletion to the wallet content requires a password.

    Every time a password-protected wallet is created, an auto-login wallet is automatically generated. However, this auto-login wallet is different from the user-created auto-login wallet described in the previous bullet. While the user-created wallet can be updated at configuration time without a password, an automatically generated auto-login wallet is a read-only wallet that does not allow direct updates. The wallet must be modified through the password protected file (by providing a password), at which time the auto-login wallet is regenerated.

    The purpose of this system-generated auto-login wallet is to provide PKI-based access to services and applications without requiring a password at runtime, while still requiring a password at configuration time.

7.4.1.2 About Self-Signed and Third-Party Wallets

Self-signed wallets contain certificates for which the issuer is the same as the subject. These wallets are typically created for use within an intranet environment where trust is not a high priority. Each self-signed wallet has its own unique issuer; hence, in an environment with multiple components and wallets, the trust management tasks increase n-fold.

When created through Fusion Middleware Control, a self-signed wallet is valid for five years.

Third-party wallets contain certificates that are issued by well known Certificate Authorities (CA's). The functionality and security remain the same as for self-signed wallets, but the use of third-party certificates provides added trust because the issuers are well known, so they are already trusted by most clients.

Difference Between Self-Signed and Third-Party Wallets

From a functional and security perspective, a self-signed certificate is comparable to one issued by a third party. The only difference is that a self-signed certificate is not trusted.

7.4.1.3 Sharing Wallets Across Instances

Oracle recommends that you do not share wallets between component instances, since each wallet represents a unique identity.

The exception to this is an environment with a cluster of component instances, in which case wallet sharing would be an acceptable practice.

Note that no management tools or interfaces are available to facilitate wallet sharing. However, you can export a wallet from one instance and import it into another instance. See Section 7.4.4 for details of wallet export and import.

7.4.1.4 Wallet Naming Conventions

Follow these naming conventions for your Oracle wallets:

  • Do not use a name longer than 256 characters.

  • Do not use any of the following characters in a wallet name:

    | ; , ! @ # $ ( ) < > / \ " ' ` ~ { } [ ] = + & ^ space tab

    Note:

    Observe this rule even your operating system supports the character.

  • Do not use non-ASCII characters in a wallet name.

  • Additionally, follow the operating system-specific rules for directory and file names

Due to the way data is handled in an LDAP directory, wallet names are not case-sensitive.

Thus, it is recommended that you use case-insensitive wallet names (preferably, using all lower case letters). For example, if you have created a wallet named UPPER, do not create another wallet named upper; doing so could cause confusion during wallet management operations.

7.4.1.5 Wallet Requirements in JDK7

JDK7 requires the keyUsage extension for self-signed CA certificates used for SSL configuration. For details, see Section H.3.3.

7.4.2 Accessing the Wallet Management Page in Fusion Middleware Control

An Oracle wallet is associated with the component where it is utilized. To locate a component instance:

  1. Log into Fusion Middleware Control using administrator credentials.

  2. Select the domain of interest.

    Note:

    You can use Setup to discover a specific Oracle WebLogic Server domain to work with.

  3. From the navigation pane, locate the instance (for example, an OHS instance) that will use the wallet. Click on the instance.

    The component type now appears on the upper left of the page adjacent to the Farm drop-down.

  4. Select the component type drop-down (for example, Oracle HTTP Server).

    If the component is not started, start it by right-clicking to open the component menu, press Control, then Start Up.

  5. Navigate to Security, then Wallets.

  6. The Wallets page appears.

On the Wallets page, you can:

  • Create a wallet.

  • Delete a wallet.

  • Import a wallet.

  • Export a wallet.

7.4.3 Managing the Wallet Life Cycle

Typical life cycle events for an Oracle wallet are as follows:

  • The wallet is created. Wallets can be created directly, or by importing a wallet file from the file system.

  • The list of available wallets are viewed and specific wallets selected for update.

  • Wallets are updated or deleted. Update operations for password-protected wallets require that the wallet password be entered.

  • The wallet password can be changed for password-protected wallets.

  • The wallet can be deleted.

  • Wallets can be exported and imported.

    Note:

    As of Oracle Fusion Middleware 12c (12.1.3), you can take advantage of the central storage and unified console available with the Keystore Service to manage wallets and their contents through the export, import, and synchronization features of that service. See Infrastructure Security WLST Command Reference for details about the importKeyStore, exportKeyStore, and syncKeyStore commands.

7.4.4 Common Wallet Operations

This section describes the steps required to perform a range of wallet management functions, including:

7.4.4.1 Creating a Wallet

This section explains how to create an Oracle wallet:

7.4.4.1.1 Creating a Wallet Using Fusion Middleware Control

Take these steps to create a wallet:

  1. Navigate to the Wallets page for your component instance. See Section 7.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."

  2. Click Create.

  3. The Create Wallet page appears.

  4. Enter a wallet name.

  5. Check or uncheck the Autologin box, depending on whether your wallet will be an auto-login wallet. The default is an auto-login wallet.

    See Section 7.4.1.1, "About Password-Protected and Autologin Wallets" for details.

    Note:

    Wallets configured for Oracle Internet Directory must have auto-login enabled.

    Description of wal3.gif follows
    Description of the illustration wal3.gif

  6. Click Submit.

  7. At this point, you must choose whether to add a certificate request (CR) at this time. If you choose not to do so, you can always add the CR later; see Section 7.4.7.1.1, "Adding a Certificate Request Using Fusion Middleware Control."

    In this example, we choose to add a CR:

    Description of wal5.gif follows
    Description of the illustration wal5.gif

    Note:

    The common name entered here should match the host name of the Oracle HTTP Server to which clients will connect; this helps to prevent problems of the type mentioned in Section 7.4.8.2.

  8. Click Finish.

  9. There are two options for the CR:

    • Copy and paste the Base64-encoded certificate request from the text box to a file.

    • Export it directly to a file with the Export Certificate Request button.

  10. A message appears confirming the wallet creation.

7.4.4.1.2 Creating a Wallet Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to create a wallet:

createWallet('ohs1', 'ohs1', 'ohs', 'ohs2', 'password')

where ohs2 is the wallet name and password is the password for this wallet. If an auto-login wallet needs to be created, the password should be specified as '' (that is, no text between the quotes).

See Also:

"createWallet" in the Infrastructure Security WLST Command Reference.

7.4.4.2 Creating a Self-Signed Wallet

This section explains how to create a self-signed wallet:

7.4.4.2.1 Creating a Self-Signed Wallet Using Fusion Middleware Control

Take these steps to create a self-signed wallet:

See Also:

Section 7.4.1.2, "About Self-Signed and Third-Party Wallets"

  1. Navigate to the Wallets page for your component instance. See Section 7.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."

  2. Click Create Self-Signed Wallet.

  3. On the Self-Signed Wallet page, enter data to create the wallet. This includes:

  4. Click Submit.

  5. A confirmation message is displayed and the new wallet appears in the list of wallets.

    Description of wal9.gif follows
    Description of the illustration wal9.gif

Note:

Wallets configured for Oracle Internet Directory must have auto-login enabled.

7.4.4.2.2 Creating a Self-Signed Wallet Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use these commands to create a self-signed wallet:

createWallet('ohs1', 'ohs1', 'ohs', 'ohs2', 'password')
addSelfSignedCertificate('ohs1', 'ohs1', 'ohs', 'ohs2', 'password', 'subject_dn', 'key_size')

where ohs2 is the wallet name, subject_dn is the distinguished name of the self-signed certificate, key_size is the key size in bits and password is the password for this wallet. If an auto-login wallet needs to be created, the password should be specified as '' (that is, with no text between the quotes).

See Also:

Note:

Wallets configured for Oracle Internet Directory must have auto-login enabled.

7.4.4.3 Changing a Self-Signed Wallet to a Third-Party Wallet

For steps to convert a self-signed wallet into a third-party wallet, see Section 7.4.8.3, "Changing a Self-Signed Wallet to a Third-Party Wallet."

7.4.4.4 Exporting a Wallet

This section explains how to export a wallet:

7.4.4.4.1 Exporting a Wallet Using Fusion Middleware Control

Take these steps to export a wallet:

  1. Navigate to the Wallets page for your component instance. See Section 7.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."

  2. Select the row corresponding to the wallet of interest.

    Note:

    Do not click on the wallet name itself; this opens the wallet for certificate management operations.

  3. Click Export.

  4. The Export Wallet page appears.

  5. Enter the filename and the location where the wallet is to be exported.

  6. Click OK.

    Description of wal20.gif follows
    Description of the illustration wal20.gif

7.4.4.4.2 Exporting a Wallet Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to export a wallet:

exportWallet('ohs1', 'ohs1', 'ohs', 'selfsigned', 'password', '/tmp')

where password is the password for this wallet (specify '' as password for auto-login wallet).

If it is an auto-login wallet, this command will export the wallet into a file named cwallet.sso under the directory /tmp. If it is a password-protected wallet, there will be two files created under /tmp, namely ewallet.p12 and cwallet.sso.

See Also:

"exportWallet" in the Infrastructure Security WLST Command Reference.

7.4.4.5 Importing a Wallet

This section explains how to import a wallet:

7.4.4.5.1 Importing a Wallet Using Fusion Middleware Control

Take these steps to import a wallet:

  1. Navigate to the Wallets page for your component instance. See Section 7.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control".

  2. Click Import.

  3. The Import Wallet page appears.

  4. If this is an auto-login wallet, check the box and enter the wallet name. No password is required.

    Description of wal10.gif follows
    Description of the illustration wal10.gif

  5. If this is not an auto-login wallet, uncheck the auto-login box. Specify both the wallet name and password.

    Description of wal11.gif follows
    Description of the illustration wal11.gif

  6. Click OK. The wallet is imported into the repository.

7.4.4.5.2 Importing a Wallet Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to import a wallet:

importWallet('ohs1', 'ohs1', 'ohs', 'ohs5', 'password', '/tmp/ewallet.p12')

where ohs5 is the wallet name, password is the password of the wallet being imported and /tmp/ewallet.p12 contains the wallet file (if there are two files ewallet.p12 and cwallet.sso, point to ewallet.p12). Point to cwallet.sso only if it is an auto-login wallet - in this case, the password should be specified as ''.

See Also:

"importWallet" in the Infrastructure Security WLST Command Reference.

7.4.4.6 Deleting a Wallet

This section explains how to delete a wallet:

7.4.4.6.1 Deleting a Wallet Using Fusion Middleware Control

Take these steps to delete a wallet:

  1. Navigate to the Wallets page for your component instance. See Section 7.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."

  2. Select the row corresponding to the wallet of interest.

  3. Click Delete.

    Description of ks19.gif follows
    Description of the illustration ks19.gif

  4. The wallet is deleted and no longer appears on the list of wallets.

7.4.4.6.2 Deleting a Wallet Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to delete a wallet:

deleteWallet('ohs1', 'ohs1', 'ohs', 'selfsigned')

See Also:

"deleteWallet" in the Infrastructure Security WLST Command Reference.

7.4.5 Managing the Certificate Life Cycle

The complete certificate life cycle, starting from wallet creation, includes these actions:

  1. Create an empty wallet (that is, a wallet that does not contain a certificate request).

  2. Add a certificate request to the wallet.

  3. Export the certificate request.

  4. Use the certificate request to obtain the corresponding certificate.

  5. Import trusted certificates.

  6. Import the certificate.

These steps are needed to generate a wallet with a third-party trusted certificate. For details about this task, see Section 7.4.7.5.1, "Converting a Self-Signed Certificate into a Third-Party Certificate Using Fusion Middleware Control."

See Also:

Section 7.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control"

7.4.6 Accessing the Certificate Management Page for Wallets in Fusion Middleware Control

An Oracle wallet is associated with the component where it is utilized.

To locate a component instance:

  1. Log into Fusion Middleware Control using administrator credentials.

  2. Select the domain of interest.

    Note:

    You can use Setup to discover a specific Oracle WebLogic Server domain to utilize.

  3. Use the navigation pane to locate the instance (for example, an Oracle HTTP Server instance) that will use the wallet. Note: Oracle HTTP Server must be running so that subsequent steps will work.

After locating your component instance, there are two ways you can access a wallet's certificate management page in Fusion Middleware Control:

  • Go to the Wallets page, select the line for the wallet of interest and click Manage.

  • Go to the Wallets page, locate the wallet of interest, and click on the wallet name.

On the Certificate Management page, you can:

  • Add a certificate request.

  • Export a certificate request, a certificate, or a trusted certificate.

  • Import a certificate or a trusted certificate.

  • Delete a certificate request, a certificate, or a trusted certificate.

7.4.7 Common Certificate Operations

This section describes the following common certificate operations:

7.4.7.1 Adding a Certificate Request

This section explains how to add a certificate request to a wallet:

7.4.7.1.1 Adding a Certificate Request Using Fusion Middleware Control

It is possible to add a certificate request at the time you create the wallet, but if it was not done at that time, you can do so using the following steps:

  1. Navigate to the Certificate Management page. See Section 7.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."

  2. Click Add Certificate Request.

  3. A dialog box appears where you enter the CRs DN values:

    Description of cer2.gif follows
    Description of the illustration cer2.gif

    Fields marked with an asterisk (*) are required. Note: The common name must be the host name that clients will use to access the component.

  4. Click OK.

  5. The new CR is generated and a dialog box appears with the CR in the text box. You can either:

    • Copy and paste the Base64-encoded certificate request to a file.

    • Export it directly to a file with the Export Certificate Request button.

    Description of cer3.gif follows
    Description of the illustration cer3.gif

7.4.7.1.2 Adding a Certificate Request Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to add a certificate request for a wallet:

addCertificateRequest('ohs1', 'ohs1', 'ohs', 'selfsigned', 'password', 'subject_dn', 'key_size')

where password is the password for this wallet, subject_dn is the distinguished name by which the certificate request is generated and key_size is the key size in bits.

See Also:

"addCertificateRequest" in the Infrastructure Security WLST Command Reference.

7.4.7.2 Exporting a Certificate, Certificate Request, or a Trusted Certificate

This section explains how to export a Certificate, Certificate Request, or a Trusted Certificate:

7.4.7.2.1 Exporting a Certificate, Certificate Request, or a Trusted Certificate Using Fusion Middleware Control

Take these steps to export a certificate, a certificate request (CR), or a trusted certificate:

  1. Navigate to the Certificate Management page. See Section 7.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."

  2. Select the certificate, CR, or trusted certificate and click Export.

  3. A dialog box appears with the certificate, CR, or trusted certificate in the text box. You can either:

    • Copy and paste the Base64-encoded certificate to a file.

    • Export it directly to a file with the Export Certificate or Export Trusted Certificate button.

7.4.7.2.2 Exporting a Certificate, Certificate Request, or a Trusted Certificate Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to export a certificate request:

exportWalletObject('ohs1', 'ohs1', 'ohs', 'selfsigned', 'password', 'CertificateRequest', '/tmp', 'subject_dn')

where password is the password for this wallet, /tmp is the path under which the certificate request is exported in BASE64 format in the file base64.txt, and subject_dn is the distinguished name of the certificate request that is exported.

To export a certificate or trusted certificate, replace CertificateRequest in the above command with Certificate or TrustedCertificate.

See Also:

"exportWalletObject" in the Infrastructure Security WLST Command Reference.

7.4.7.3 Importing a Certificate or a Trusted Certificate

This section explains how to import a Certificate or a Trusted Certificate:

7.4.7.3.1 Importing a Certificate or a Trusted Certificate Using Fusion Middleware Control

Note:

You cannot use Fusion Middleware Control to import DER-encoded certificates or trusted certificates into an Oracle wallet. Use orapki command-line tool instead.

Take these steps to import a certificate or a trusted certificate:

  1. Navigate to the Certificate Management page. See Section 7.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."

  2. Click Import.

  3. In the Import Certificate dialog, you can select either a certificate or a trusted certificate.

  4. There are two ways to do the import:

    • Paste the Base64-encoded certificate or trusted certificate in the text box.

    • Use the file selector to browse your file system to locate a file containing the Base64-encoded certificate or trusted certificate.

    Description of cer4.gif follows
    Description of the illustration cer4.gif

  5. Click OK.

7.4.7.3.2 Importing a Certificate or a Trusted Certificate Using WLST

Note:

You cannot use the WLST command-line tool to import DER-encoded certificates or trusted certificates into an Oracle wallet. Use orapki command-line tool instead.

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to import a certificate into a wallet:

importWalletObject('ohs1', 'ohs1', 'ohs', 'selfsigned', 'password', 'Certificate', '/tmp/cert.txt')

where password is the password for this wallet and /tmp/cert.txt is the file that contains BASE64 encoded certificate.

To import a trusted certificate, replace Certificate in the above command with TrustedCertificate.

See Also:

"importWalletObject" in the Infrastructure Security WLST Command Reference.

7.4.7.4 Deleting a Certificate Request, a Certificate, or a Trusted Certificate

This section explains how to delete a Certificate Request, a Certificate, or a Trusted Certificate:

7.4.7.4.1 Deleting a Certificate Request, a Certificate, or a Trusted Certificate Using Fusion Middleware Control

Take these steps to delete a CR, a certificate, or a trusted certificate:

  1. Navigate to the Certificate Management page. See Section 7.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."

  2. Select the row containing the certificate request, certificate or trusted certificate.

  3. Click Delete.

  4. A dialog box appears, requesting confirmation.

    Description of cer5.gif follows
    Description of the illustration cer5.gif

  5. Click Yes.

  6. The object no longer appears in the Manage Certificates list.

7.4.7.4.2 Deleting a Certificate Request, a Certificate, or a Trusted Certificate Using WLST

Execute these WLST commands using the protocol described in Section 7.2.1.

Assuming the component instance is ohs1, use this command to delete a certificate:

removeWalletObject('ohs1', 'ohs1', 'ohs', 'selfsigned', 'password', 'Certificate', 'subject_dn')

where password is the password for this wallet and subject_dn is the distinguished name of the certificate being deleted.

To delete a certificate request or trusted certificate, replace Certificate in the above command with CertificateRequest or TrustedCertificate.

See Also:

"removeWalletObject" in the Infrastructure Security WLST Command Reference.

7.4.7.5 Converting a Self-Signed Certificate into a Third-Party Certificate

This section explains how to convert a Self-Signed Certificate into a Third-Party Certificate:

7.4.7.5.1 Converting a Self-Signed Certificate into a Third-Party Certificate Using Fusion Middleware Control

A self-signed certificate residing in a wallet can be converted into a third-party certificate signed by a certificate authority (CA). Take these steps to perform the task:

Note:

The steps are illustrated for use with Oracle Internet Directory, and similar steps are applicable for generating wallets to use with Oracle HTTP Server.

  1. From the navigation pane, locate your component instance.

  2. Navigate to component_name, then Security, then Wallets.

  3. From the list of wallets, select the wallet that contains the self-signed certificate.

  4. The Manage Certificates page appears. It contains the list of certificates in the wallet.

  5. A new certificate request must be generated for the self-signed certificate that is to be converted. Select the self-signed certificate and click Add Certificate Request. A dialog box appears:

    Description of cer2.gif follows
    Description of the illustration cer2.gif

    Note:

    The common name entered here should match the host name of the server to which clients will connect; this helps to prevent problems of the type mentioned in Section 7.4.8.2.

  6. Enter the certificate request (CR) details and click OK.

    The CR is generated. You can either:

    • Copy and paste the Base64-encoded certificate request to a file.

    • Export it directly to a file with the Export Certificate Request button.

  7. Submit the certificate request file to a certificate authority to generate a certificate. This is an offline procedure that you can execute in accordance with your local policy for obtaining certificates.

  8. The CA signs the certificate request and generates a certificate. The CA will return you one of the following:

    • A single file containing both the newly generated certificate and its own CA certificate in pkcs7 format

    • Multiple files, one of which will be the newly generated certificate and the other(s) its own CA certificate (or certificates, if there is a chain)

  9. Use Import to import these files into your wallet:

    • If you received a single file from the CA, import it as a trusted certificate, using an alias that matches the alias of the self-signed certificate you are replacing (from Step 3).

    • If you received two or more files:

      • Import the file(s) containing the CA certificate or certificate chain as trusted certificate(s) (use an alias that is unique in the wallet).

      • Import the certificate file as a certificate (using an alias that matches the alias of the self-signed certificate you are replacing).

      Note:

      The order is important: you must import the trusted certificate first, followed by the certificate.

      For more information on how to identify the correct Trusted CA Certificate or the correct chain of Trusted CA certificates, see Doc ID 1368940.1 in My Oracle Support Knowledge Base https://support.oracle.com/epmos/faces/DocumentDisplay?id=1368940.1

    The CA returned a single file, which is imported as a trusted certificate:

    Description of cer4.gif follows
    Description of the illustration cer4.gif

  10. After import, the certificate issued by the CA replaces the self-signed certificate.

7.4.7.5.2 Converting a Self-Signed Certificate into a Third-Party Certificate Using WLST

See Also:

Section 6.9

Execute these WLST commands using the protocol described in Section 7.2.1.

Follow these steps to convert a self signed certificate to a third-party certificate using WLST:

  1. Add a certificate request, for example:

    addCertificateRequest('inst1', 'ohs1', 'ohs', 'selfsigned', 'password', 'subject_dn', 'key_size')

  2. Export the certificate request:

    exportWalletObject('inst1', 'ohs1', 'ohs', 'selfsigned', 'password', 'CertificateRequest', '/tmp', 'subject_dn')

  3. Submit the certificate request /tmp/base64.txt to a certificate authority. The CA will return a newly generated certificate and its own certificate, either as one file in PKCS#7 format or as multiple files, one of which will be the newly generated certificate and the other(s) its own CA certificate (or certificates, if there is a chain).

  4. If you receive a single file from the CA, run the following command:

    importWalletObject('inst1', 'ohs1', 'ohs', 'selfsigned', 'password', 'TrustedChain', '/tmp/cert.txt')

    where password is the password for this wallet and /tmp/cert.txt is the file that the CA returned and contains BASE64 encoded PKCS#7.

    If you receive two or more files from the CA, import the file(s) containing the CA certificate or certificate chain as trusted certificate(s) first, followed by the newly generated certificate. For example when two files are returned:

    importWalletObject('inst1', 'ohs1', 'ohs', 'selfsigned', 'password', 'TrustedCertificate', '/tmp/cacert.txt')
 
importWalletObject('inst1', 'ohs1', 'ohs', 'selfsigned', 'password', 'Certificate', '/tmp/cert.txt')

    where password is the password for this wallet, /tmp/cert.txt is the file that the CA returned and contains BASE64 encoded certificate and /tmp/cacert.txt is the file containing the BASE64 encoded CA certificate.

    For more information on how to identify the correct Trusted CA Certificate or the correct chain of Trusted CA certificates, see Doc ID 1368940.1 in My Oracle Support Knowledge Base https://support.oracle.com/epmos/faces/DocumentDisplay?id=1368940.1

See Also:

The following references in the Infrastructure Security WLST Command Reference:

7.4.8 Wallet and Certificate Maintenance

This section contains the following administration topics:

7.4.8.1 Location of Wallets

This section describes the location of wallets and provides maintenance details.

Root Directory for an Oracle HTTP Server Wallet

The root directory for Oracle HTTP Server wallets is:

$DOMAIN_HOME/config/fmwconfig/components/OHS/ohs_instance_name/keystores

This root directory contains subdirectories with wallet names, and these subdirectories contain the actual wallet files.

For example, assuming ohs_instance1 contains two wallets named ohs1 and ohs2, respectively. ohs1 is a password-protected wallet, and ohs2 is an auto-login-only wallet. A sample structure could look like this:

$DOMAIN_HOME/config/fmwconfig/components/OHS/ohs_instance1
/keystores/ohs1/cwallet.sso

$DOMAIN_HOME/config/fmwconfig/components/OHS/ohs_instance1
/keystores/ohs1/ewallet.p12

$DOMAIN_HOME/config/fmwconfig/components/OHS/ohs_instance1
/keystores/ohs2/cwallet.sso

7.4.8.2 Effect of Host Name Change on a Wallet

Typically, the wallet DN is based on the host name of the server where the wallet is used.

For example, if a wallet is being created for the Oracle HTTP Server my.example.com, then the DN of the certificate in this Oracle HTTP Server wallet will be something like "CN=my.example.com,O=organization name".

This synchronization is required because most clients do host name verification during the SSL handshake.

Clients that perform host name verification include Web browsers and Oracle HTTPClient, among others. If the host name of the server does not match that of the certificate DN, then:

  • A clear warning will be displayed (in the case of browser clients).

  • There may be SSL handshake failure (in the case of other clients).

Thus, when you have a wallet on a server that is accepting requests from clients, you must ensure that whenever the host name of this server changes, you also update the certificate in the wallet.

You can do this by requesting a new certificate with a new DN (based on the new host name).

7.4.8.2.1 Requesting a New Certificate for a Production Wallet

The steps are:

  • Generate a new request with the new DN (based on new host name).

  • Send this request to a certificate authority (CA).

  • Get back a new certificate from the CA.

  • Delete the older certificate and certificate request from the wallet.

  • Import the new certificate.

See Section 7.4.4 for details about these operations.

7.4.8.2.2 Requesting a New Certificate for a Self-signed Wallet

The steps are:

  • Delete the existing wallet.

  • Create a new wallet with a self-signed certificate using the new DN (based on the new host name).

See Section 7.4.4 for details about these operations.

For both production and self-signed wallets, once the new certificate is available in the wallet, you need to ensure that it is imported into all the component wallets where it needs to be trusted. For example, if Oracle WebLogic Server is SSL-enabled and the certificate for Oracle WebLogic Server changed due to a host name change, then you need to import its new certificate into the Oracle HTTP Server wallet so that it can trust its new peer.

7.4.8.3 Changing a Self-Signed Wallet to a Third-Party Wallet

You can convert a self-signed wallet into a third-party wallet, one that contains certificates signed by a trusted Certificate Authority (CA).

Assuming a self-signed wallet named MYWallet, containing a certificate with DN as "CN=my.example.com,O=example", take these steps to convert it into a third-party wallet:

  1. Remove the user certificate "CN=my.example.com,O=example" from the wallet.

  2. Remove the trusted certificate "CN=my.example.com,O=example" from the wallet (this has the same DN as the user certificate, but is a separate entity nonetheless).

  3. Export the certificate request "CN=my.example.com,O=example" from the wallet and save it to a file.

  4. Give this certificate request file to a third-party certificate authority (CA) such as Verisign.

  5. The CA will return one of the following:

    • A user certificate file and its own certificate file

    • A single file with a certificate chain consisting of a user certificate and its own certificate

  6. Import the above file(s) into the wallet.

See Section 7.4.4 for details about these operations.

7.4.8.4 Replacing an Expiring Certificate in a Wallet

An expiring certificate should be replaced before it actually expires to avoid or reduce application downtime.

The steps for replacing an expiring certificate are as follows:

  1. Export the certificate request from the wallet (this is the same request for which the current expiring certificate was issued).

  2. Provide this certificate request to the third-party Certificate Authority (CA) for certificate issuance. The validity date of the new certificate should be earlier than the expiration date of the current certificate. This overlap is recommended to reduce downtime.

    Note:

    Steps 1 and 2 are not required when the third-party CA already maintains the certificate request in a repository. In that case, simply request the CA to issue a new certificate for that certificate request.

  3. Remove the existing certificate (the one that is about to expire) from the wallet.

  4. Import the newly issued certificate into the wallet.

    To reduce downtime, remove the previous certificate and import the new certificate in the overlap period when the new certificate has become valid and the older one has not yet expired.

  5. If the new certificate was issued by a CA other than the one that issued the original certificate, you may also need to import the new CA's trusted certificate before importing the newly issued certificate.

See Section 7.4.4 for details about these operations.