7 Managing Keystores, Wallets, and Certificates

Oracle Fusion Middleware supports security features and tools to administer keystores, keys, and certificates. These artifacts are used to configure SSL and related tasks for Oracle Fusion Middleware components.

• 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.
• 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.
• Keystore Management
  The keystore service allows you to manage and administer keys and certificates for Secure Sockets Layer (SSL), message security, encryption, and other tasks that require special certificates.
• Wallet Management
  Oracle wallets provide a full range of management features to enable you to create, maintain, and delete certificates for various applications.

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:

• Types of Keystores
  Oracle Fusion Middleware provides various types of keystores for keys and certificates.
• Keystore Management Tools
  Oracle Fusion Middleware provides WLST, orapki and Fusion Middleware Control as options for keystore operations.

Types of Keystores

Oracle Fusion Middleware provides various types of keystores for keys and certificates.

The various types of keystores 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

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

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.2.1.2), 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:

• About the Keystore Service (KSS) Keystore for more information on the Keystore Service.

• “Infrastructure Security Custom WLST Commands” in WLST Command Reference for Infrastructure Security for details about the importKeyStore, exportKeyStore, and syncKeyStore commands.

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.

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.2.1.2), Oracle WebLogic Server:

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

• uses JKS by default in upgraded environments.

Keystore Management Tools

Oracle Fusion Middleware provides WLST, orapki and Fusion Middleware Control as options for keystore operations.

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

Note:

This is only applicable in a collocated environment.

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 importKeyStore command. For details, see “Importing a Keystore” in Securing Applications with Oracle Platform Security Services.

Copying Keystores to File System Not Supported

Note:

This is only applicable in a collocated environment.

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 standalone environment, such as a standalone OHS installation, orapki commands are used for wallet management. For details, see “Configuring SSL in a Standalone Mode” in Administering Oracle HTTP Server.

JDK8 Requirement for Self-Signed Certificates

JDK8 requires the keyUsage extension for self-signed CA certificates used for SSL configuration. For details, see keyUsage Extension Required for Certificates in JDK8.

Additional Information

Details about the tools are provided in these sections:

• Command-Line Interface for Keystores and Wallets

• Wallet Management

• orapki

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.

For more information on how to launch the command line interface, see How to Launch the Command-Line Interface.

• How to Launch the Command-Line Interface
  When running SSL WLST commands, you must invoke the WLST script from the Oracle Common home.

How to Launch the Command-Line Interface

When running SSL WLST commands, you must invoke the WLST script from the Oracle Common home.

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','<password>') --- 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','<password>') --- 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','password')
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

Keystore Management

The keystore service allows you to manage and administer keys and certificates for Secure Sockets Layer (SSL), message security, encryption, and other tasks that require special certificates.

Since 12c (12.2.1), Fusion Middleware recommends Keystore Service (KSS) for wallet and certificate management in a collocated scenario. For details about KSS keystore management, see "Managing Keys and Certificates" in Securing Applications with Oracle Platform Security Services.

Wallet Management

Oracle wallets provide a full range of management features to enable you to create, maintain, and delete certificates for various applications.

Note:

Since 12c (12.2.1), the "Wallet" option is no longer available in the Fusion Middleware Control Security menu. Fusion Middleware recommends the Keystore Service (KSS) instead for wallet management in a collocated scenario. However, in a standalone environment, you can manage a wallet only by using the orapki utility. There is no KSS support in standalone scenario.

For wallet configuration in a stand-alone context, for example a stand-alone Oracle HTTP Server, see orapki.

This discussion assumes that components are installed within a WebLogic domain.

• About Wallets and Certificates
  Review these topics for various types of wallets and their recommendation, conventions and requirements.
• Managing the Wallet Life Cycle
  Review this topic for the typical life cycle events for an Oracle wallet.
• Common Wallet Operations
  Follow these procedures for the steps required to perform a range of wallet management functions.
• Managing the Certificate Life Cycle
  Review this topic for the typical life cycle event of a certificate, starting from wallet creation.
• Common Certificate Operations
  Follow these procedures for the steps required to perform a range of certificate management functions.
• Wallet and Certificate Maintenance
  Review these topics for more information on maintaining wallet and certificates.

About Wallets and Certificates

Review these topics for various types of wallets and their recommendation, conventions and requirements.

This section contains the following topics:

• About Password-Protected and Autologin Wallets
  
• 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.
• Sharing Wallets Across Instances
  Oracle recommends that you do not share wallets between component instances, since each wallet represents a unique identity.
• Wallet Naming Conventions
  
• Wallet Requirements in JDK8
  JDK8 requires the keyUsage extension for self-signed CA certificates used for SSL configuration.

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.2.1.1), 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.

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.

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 Common Wallet Operations for details of wallet export and import.

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.

Wallet Requirements in JDK8

JDK8 requires the keyUsage extension for self-signed CA certificates used for SSL configuration.

For details, see keyUsage Extension Required for Certificates in JDK8.

Managing the Wallet Life Cycle

Review this topic for the typical life cycle events for an Oracle wallet.

• 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.2.1.2), 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 Custom WLST Commands” in WLST Command Reference for Infrastructure Security for details about the importKeyStore, exportKeyStore, and syncKeyStore commands.

Common Wallet Operations

Follow these procedures for the steps required to perform a range of wallet management functions.

• Creating a Wallet Using orapki
  
• Adding a Self-Signed Certificate to a Wallet Using orapki
  

Creating a Wallet Using orapki

To create a Password Protected Wallet (ewallet.p12 and cwallet.sso):

orapki wallet create -wallet wallet_location -auto_login

To create an Auto-Login Wallet (cwallet.sso only):

orapki wallet create -wallet wallet_location -auto_login_only

For more information on using the orapki utility for creating a wallet, see Creating and Viewing Oracle Wallets with orapki.

Adding a Self-Signed Certificate to a Wallet Using orapki

To create a wallet containing a self-signed certificate using orapki:

orapki wallet add –wallet wallet_location –dn user_dn -keysize 512|1024|2048|4096|8192|16384 -self_signed [-pwd][-auto_login_only]

Note:

If alias value is not specified for a wallet, a default alias will be set. Example: orakey,orakey1,orakey2.

To create a wallet containing self-signed certificate with ECC keys:

orapki wallet add -wallet wallet_location -dn user_dn -sign_alg signing_alg -asym_alg ECC -eccurve curve_type

For more information on adding an ECC certificate request to an Oracle Wallet, see Adding an ECC Certificate Request to an Oracle Wallet.

Managing the Certificate Life Cycle

Review this topic for the typical life cycle event of a certificate, starting from wallet creation.

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 “Replacing Demonstration CA Signed Certificates” in Securing Applications with Oracle Platform Security Services.

Common Certificate Operations

Follow these procedures for the steps required to perform a range of certificate management functions.

• Adding a Certificate Request Using orapki
  
• Exporting a Certificate from an Oracle Wallet using orapki
  
• Exporting a Certificate Request Using orapki
  
• Importing a Trusted Certificate Using orapki
  
• Importing a User Certificate Using orapki
  
• Creating a Signed Certificate from Certificate Requests Using orapki
  

Adding a Certificate Request Using orapki

To add a certificate signing request to an Oracle Wallet:

orapki wallet add -wallet wallet_location -dn user_dn -keysize certificate_key_size -addext_ski -addext_ku extension_key_usage -addext_basic_cons CA -pathLen number -addext_san DNS [-pwd] [-auto_login_only]

Note:

In all commands where user_dn is referenced, use single quotes for UNIX and double quotes for Windows.

For more information on using the orapki utility for adding certificate request to an Oracle wallet, see Adding Certificates and Certificate Requests to Oracle Wallets with orapki.

Exporting a Certificate from an Oracle Wallet using orapki

To export a certificate from an Oracle Wallet:

orapki wallet export -wallet wallet_location -dn
certificate_dn -cert certificate_filename -issuer_dn dn_of_issuer –serial_num serial_number_of_certificate

For more information on using the orapki utility for exporting a certificate from an Oracle Wallet, see Exporting Certificates and Certificate Requests from Oracle Wallets with orapki.

Exporting a Certificate Request Using orapki

To export a certificate request from an Oracle wallet:

orapki wallet export -wallet wallet_location -dn certificate_request_dn -request certificate_request_filename [-pwd]

For more information on using the orapki utility for exporting certificate requests from an Oracle Wallet, see Exporting Certificates and Certificate Requests from Oracle Wallets with orapki.

Note:

For detailed information about Trusted Certificates and how to identify the correct Trusted Root Certificate Authority Certificate(s) for a User Certificate, refer to support Document 1368940.1 on My Oracle Support. You can access My Oracle Support at: https://support.oracle.com/.

Importing a Trusted Certificate Using orapki

To import a trusted certificate into the Wallet:

orapki wallet add -wallet wallet_location -trusted_cert -cert certificate_location [-pwd] [-auto_login_only]

For more information on using the orapki utility to import a trusted certificate to an Oracle wallet, see Adding Certificates and Certificate Requests to Oracle Wallets with orapki.

Importing a User Certificate Using orapki

To add a user certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -user_cert -cert certificate_location [-pwd] [auto_login_only]

For more information on using the orapki utility to import a trusted certificate to an Oracle wallet, see Adding Certificates and Certificate Requests to Oracle Wallets with orapki.

Creating a Signed Certificate from Certificate Requests Using orapki

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]

For more information on using the orapki utility for creating a signed certificate, see Creating Signed Certificates for Testing Purposes.

Wallet and Certificate Maintenance

Review these topics for more information on maintaining wallet and certificates.

• Location of Wallets
  
• Effect of Host Name Change on a Wallet
  
• 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).
• Replacing an Expiring Certificate in a Wallet
  An expiring certificate in a wallet is replaced before it actually expires to avoid or reduce application downtime.

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

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

• Requesting a New Certificate for a Production Wallet
  
• Requesting a New Certificate for a Self-signed Wallet
  

Requesting a New Certificate for a Production Wallet

You can request a new certificate to import into a production wallet.

The steps are:

1. Generate a new request with the new DN (based on new host name).
2. Send this request to a certificate authority (CA).
3. Get back a new certificate from the CA.
4. Delete the older certificate and certificate request from the wallet.
5. Import the new certificate.

See Common Wallet Operations for details about these operations.

Requesting a New Certificate for a Self-signed Wallet

To add a new certificate to a self-signed wallet, you need to create a new wallet for the certificate.

The steps are:

1. Delete the existing wallet.
2. Create a new wallet with a self-signed certificate using the new DN (based on the new host name).

See Common Wallet Operations 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.

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 Common Wallet Operations for details about these operations.

Replacing an Expiring Certificate in a Wallet

An expiring certificate in a wallet is 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 Common Wallet Operations for details about these operations.