Oracle® Fusion Middleware Administrator's Guide 11g Release 1 (11.1.1) Part Number E10105-09 |
|
|
View PDF |
This chapter explains how to use Oracle Fusion Middleware security features to administer keystores, wallets, and certificates. It contains these sections:
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:
Oracle Fusion Middleware provides two types of keystores for keys and certificates:
A JKS keystore is the default JDK implementation of Java keystores provided by Sun Microsystems. In 11g Release 1 (11.1.1), all Java components and Java EE applications use the JKS-based keystore and truststore.
You use a JKS-based keystore for the following:
Oracle Virtual Directory
Applications deployed on Oracle WebLogic Server, including:
Oracle SOA Suite
Oracle WebCenter
In Oracle Fusion Middleware, you can use graphical user interface or command-line tools to create, import, export, and delete a Java keystore and the certificates contained in the keystore. See Section 8.1.2, "Keystore Management Tools" for details.
While creating a keystore, you can pre-populate it with a keypair wrapped in a self-signed certificate; such a keystore is typically used in development and testing phases.
The other choice is to generate a certificate signing request for a keypair, 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 keystore; the keystore now contains a trusted certificate, since it comes from a trusted third-party. Such a keystore is typically used in production environments.
Keystores are always password-protected.
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.
You use an Oracle Wallet for the following components:
Oracle HTTP Server
Oracle Web Cache
Oracle Internet Directory
In Oracle Fusion Middleware, you can use graphical user interface or command-line tools to create, import, export and delete a wallet and the certificates contained in the wallet. See Section 8.1.2, "Keystore Management Tools" for details.
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.
The other choice is to 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 Fusion Middleware provides these options for keystore operations:
WLST, a command-line interface for JKS keystores and wallets
orapki, a command-line tool for wallets
Fusion Middleware Control, a graphical user interface
Oracle Wallet Manager, a stand-alone graphical user interface for wallets, recommended for managing PKCS#11 wallets
This table shows the type of keystore used by each component, and the tool(s) available to manage the keystore:
Component/Application | Type of Keystore | Tasks | Tool |
---|---|---|---|
Oracle HTTP Server
Oracle Web Cache Oracle Internet Directory |
Oracle Wallet | Create Wallet, Create Certificate Request, Delete Wallet, Import Certificate, Export Certificate, Enable SSL | Fusion Middleware Control, WLST
Oracle Wallet Manager and orapki for PKCS#11 or Hardware Security Modules (HSM)-based wallets. Also for environments where Fusion Middleware Control and WLST are not available (such as a stand-alone upgrade of these components without a domain). |
Oracle Virtual Directory | JKS-based Keystore | Create KeyStore, Create Certificate Request, Delete KeyStore, Import Certificate, Export Certificate, Enable SSL | Fusion Middleware Control, WLST |
Oracle SOA Suite | JKS-based Keystore | All Keystore operations | JDK Keytool |
Oracle WebCenter | JKS-based Keystore | All Keystore operations | JDK Keytool |
Oracle WebLogic Server | JKS-based Keystore | All Keystore operations | JDK Keytool |
Oracle WebLogic Server | JKS-based Keystore | Enable SSL | Oracle WebLogic Server Administration Console |
All Java EE applications (for example Oracle Directory Integration Platform, Oracle Directory Services Manager) | JKS-based Keystore | All Keystore operations | JDK Keytool |
See Also:
For details about using keytool, see Oracle Fusion Middleware Securing Oracle WebLogic Server.Note:
Pre-11g wallets (corresponding to 10g Release 10.1.2 and 10.1.3 formats) are supported in 11g Release 1 (11.1.1).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 or a JKS keystore. Use these tools instead:
To import DER-encoded certificates or trusted certificates into an Oracle wallet, use:
Oracle Wallet Manager or
orapki
command-line tool
To import DER-encoded certificates or trusted certificates into a JKS keystore, use the keytool
utility.
Using a Keystore Not Created with WLST or Fusion Middleware Control
If an Oracle wallet or JKS keystore was created with tools such as orapki
or keytool
, it must be imported prior to use. Specifically:
For Oracle HTTP Server, Oracle Web Cache, and Oracle Internet Directory, if a wallet was created using orapki
or Oracle Wallet Manager, 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 Oracle Virtual Directory, if a keystore was created using keytool
, 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.
Copying Keystores to File System Not Supported
Creating, renaming, or copying keystores directly to any directory on the file system is not supported. Any existing pre-11g keystore or wallet that you wish to use must be imported using either Fusion Middleware Control or the WLST utility.
Additional Information
Details about the tools are provided in these sections:
Oracle Fusion Middleware provides a set of wlst
scripts to create and manage JKS keystores and Oracle wallets, and to manipulate their stored objects.
How to Launch the WLST Command-Line Interface
When running SSL WLST
commands, you must invoke the WLST
script from the Oracle Common home. See Section 3.5.1.1 for more information.
Note:
All SSL-related WLST commands require you to launch the script from the above-mentioned location only.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.
This section describes the typical life cycle of keystores and certificates, and how to use Oracle Fusion Middleware tools to create and maintain keystores and certificates. It includes these topics:
Keys and certificates are used to digitally sign and verify data and achieve authentication, integrity, and privacy in network communications.
A Java keystore (JKS) is a protected database that holds keys and certificates for the organization. Oracle Fusion Middleware utilizes JKS keystores for Oracle Virtual Directory and for applications deployed in Oracle WebLogic Server.
Access to a keystore requires a password which is defined at the time the keystore is created, by the person who creates the keystore, and which can only be changed by providing the current password.
In addition, each private key in a keystore can be secured by its own password.
This section contains these topics:
Oracle recommends that you do not share keystores between component instances or Oracle instances, since each keystore represents a unique identity.
The exception to this is an environment with a cluster of component instances, in which case keystore sharing would be an acceptable practice.
Note that no management tools or interfaces are available to facilitate keystore sharing. However, you can export a keystore from one instance and import it into another instance.
Follow these naming conventions for your JKS keystores:
Do not use a name longer than 256 characters.
Do not use any of the following characters in a keystore name:
| ; , ! @ # $ ( ) < > / \ " ' ` ~ { } [ ] = + & ^ space tab
Note:
Observe this rule even if your operating system supports the character.Do not use non-ascii characters in a keystore name.
Additionally, follow the operating system-specific rules for directory and file names.
Typical life cycle events for a JKS keystore are as follows:
The keystore is created. Keystores can be created directly, or by importing a keystore file from the file system.
The list of available keystores are viewed and specific keystores selected for update.
Keystores are updated or deleted. Update operations require that the keystore password be entered.
The keystore password can be changed.
The keystore can be deleted.
Keystores can be exported and imported.
This section explains the following keystore operations:
Take these steps to create a keystore:
Log in to the domain of interest using Fusion Middleware Control.
From the navigation pane, locate your component instance.
Navigate to component_name, then Security, then Keystores. For example, navigate to Oracle Virtual Directory, then Security, then Keystores.
Note:
The component type is displayed at the top of the page, adjacent to the Topology icon.The Java Keystore page appears. On this page you can create, update, and delete keystores, and perform other keystore management tasks.
Click Create. The Create Keystore dialog appears.
Provide keystore details such as name and password.
You can also request a self-signed certificate in this dialog, and fill in the alias name and DN information.
Note:
If you want to use this keystore only to store trusted certificates, you can uncheck the Create Self-Signed Certificate checkbox. This will create a keystore with no keypair.Click Submit. The new keystore appears in the list of Java keystores.
Assuming the instance name is inst1
, use this command to create a keystore:
createKeyStore('inst1', 'ovd5', 'ovd', 'newKeyStore', 'password')
where password
is the password for this keystore.
See Also:
Section 6.9.6, "createKeyStore".If multiple Oracle Virtual Directory instances want to share the same keystore file, this can be achieved by exporting the keystore from one instance and importing it into the other instances.
Take these steps to export a keystore:
Navigate to the Java Keystores page for the component instance, as explained in Section 8.3.3.1, "Creating a Keystore Using Fusion Middleware Control."
Select the desired keystore from the list of stores.
Click Export.
A dialog box appears in which you must enter the keystore password to continue.
Specify a file system location, and click OK.
Assuming the instance name is inst1
, use this command to export a keystore:
exportKeyStore('inst1', 'ovd5', 'ovd', 'test', 'password', '/tmp')
where password
is the password for this keystore.
This command exports the keystore into a file named test
under the directory /tmp
.
See Also:
Section 6.9.10, "exportKeyStore".Take these steps to delete a keystore:
Navigate to the Java Keystores page for the component instance, as explained in Section 8.3.3.1, "Creating a Keystore Using Fusion Middleware Control."
Select the desired keystore from the list of stores.
Click Delete.
A dialog box appears to request confirmation of the delete request.
Click Delete.
Assuming the application server instance name is inst1
, use this command to delete a keystore:
deleteKeyStore('inst1', 'ovd5', 'ovd', 'demo')
where the component type is ovd
, the component instance is ovd5
, and the keystore is named demo
.
See Also:
Section 6.9.8, "deleteKeyStore".Navigate to the Java Keystores page for the component instance, as explained in Section 8.3.3.1, "Creating a Keystore Using Fusion Middleware Control."
Click Import.
The Import Keystore dialog box appears.
Browse the file system to locate the keystore file.
Provide a name for the keystore. Enter the keystore password.
Click OK.
The imported keystore appears in the list of Java keystores.
Assuming the instance name is inst1, use this command to import a keystore:
importKeyStore('inst1', 'ovd5', 'ovd', 'demojks', 'password', '/tmp/demojks.jks')
where password
is the password for this keystore.
See Also:
Section 6.9.18, "importKeyStore".Take these steps to change a keystore password:
Navigate to the Java Keystores page for the component instance, as explained in Section 8.3.3.1, "Creating a Keystore Using Fusion Middleware Control."
Select a keystore and click Change Password.
A dialog box appears on which you must enter the current password and enter a new password. The new password must be entered a second time to confirm.
Click OK to change the password. In future, any operations performed on this keystore or its certificates will require the use of the new password.
Assuming the instance name is inst1
, use this command to change the keystore password:
changeKeyStorePassword('inst1', 'ovd5', 'ovd', 'demojks', 'current_password', 'new_password')
where current_password
is the current password for this keystore, and new_password
is the new password.
See Also:
Section 6.9.3, "changeKeyStorePassword".Typical life cycle events for a certificate residing in a keystore are as follows:
A self-signed certificate is automatically created for the keypair.
A certificate signing request (CSR) is generated, and can then be exported to a file.
Certificates are imported into the keystore. A certificate can either be pasted into a text box or imported from the file system. You can import both user certificates and trusted certificates (also known as CA certificates) in this way.
Certificates or trusted certificates are exported from the keystore out to a file.
Certificates or trusted certificates are deleted from the keystore.
This section describes the following common certificate operations:
Generating a New Key for the Keystore Using Fusion Middleware Control
Generating a Certificate Signing Request Using Fusion Middleware Control
Importing a Certificate or Trusted Certificate into a Keystore Using Fusion Middleware Control
Importing a Certificate or Trusted Certificate into a Keystore Using WLST
Exporting a Certificate or Trusted Certificate from the Keystore Using Fusion Middleware Control
Exporting a Certificate or Trusted Certificate from the Keystore Using WLST
Deleting a Certificate or Trusted Certificate from the Keystore Using Fusion Middleware Control
Deleting a Certificate or Trusted Certificate from the Keystore Using WLST
Converting a Self-Signed Certificate to a Third-Party Certificate Using Fusion Middleware Control
Converting a Self-Signed Certificate to a Third-Party Certificate Using WLST
To generate a new key (that is, a new self-signed certificate) for a keystore:
Navigate to the Java Keystores page for the component instance, as explained in Section 8.3.3.1, "Creating a Keystore Using Fusion Middleware Control."
Select the keystore from the list of stores.
A dialog box appears in which you must enter the keystore password to continue.
The Manage Certificates page appears. Here, you can manage both types of keystore entries, that is, certificates and trusted certificates.
Click the Generate Keypair button.
In the Generate Keypair dialog, enter the details for the new key and click OK.
Example: Generating a Key Pair
When you complete these steps, a new public-private key pair is generated for the keystore, and the public key is wrapped in a self-signed certificate.
While these steps generate a new keypair for an existing keystore, you can also generate a new keypair when creating the keystore itself. For details, see Section 8.3.3.1, "Creating a Keystore Using Fusion Middleware Control."
Assuming the instance name is inst1
, use this command to generate a new key for a keystore:
generateKey('inst1', 'ovd5', 'ovd', 'newKeystore', 'password', 'subject_dn', 'key_size', 'alias')
where password
is the password for this keystore, subject_dn
is the distinguished name by which the key pair is generated, key_size
is the key size in bits, and alias
is the key alias.
Take these steps to create a Certificate Signing Request (CSR):
From the navigation pane, locate your component instance.
Navigate to component_name, then Security, then Keystores.
Select the desired keystore from the list of stores.
A dialog box appears in which you must enter the keystore password to continue.
The Manage Certificates page appears. Select the self-signed certificate for which you want to generate the CSR and click Generate CSR.
A dialog box appears, showing the generated signing request. You can either:
Copy the CSR from the dialog box and past it to a file.
Click the Export CSR button to directly save it to a file.
Assuming the instance name is inst1
, use this command to generate and export a CSR:
exportKeyStoreObject('inst1', 'ovd5', 'ovd', 'newKeystore', 'password', 'CertificateRequest', '/tmp', 'alias')
where password
is the password for this keystore, /tmp
is the path under which the certificate request is generated in BASE64 format in the file base64.txt
, and alias
is the alias of the key pair that is used to generate the certificate request.
Note:
You cannot use Fusion Middleware Control to import DER-encoded certificates or trusted certificates into a JKS keystore; use thekeytool
utility for this task.Take these steps to import a certificate, or a trusted certificate, into a keystore:
From the navigation pane, locate your component instance.
Navigate to component_name, then Security, then Keystores.
Select the desired keystore from the list of stores.
A dialog box appears in which you must enter the keystore password to continue.
The Manage Certificates page appears. Click the Import button.
A dialog box appears with which you can either:
Paste the Base-64 encoded contents of a certificate or trusted certificate into the keystore directly.
Select a certificate or trusted certificate file from the file system.
You need to specify an alias while importing a certificate.
When importing a certificate, the alias should match the alias of the corresponding keypair.
When importing a trusted certificate, the alias should be unique in the keystore.
Click OK. The Manage Certificates page appears, showing the newly imported certificate or trusted certificate.
Note:
You cannot use theWLST
command-line tool to import DER-encoded certificates or trusted certificates into a JKS keystore; use the keytool
utility for this purpose.Assuming the instance name is inst1
, use this command to import a certificate into a keystore:
importKeyStoreObject('inst1', 'ovd5', 'ovd', 'newKeystore', 'password', 'Certificate', '/tmp/cert.txt', 'alias')
where password
is the password for this keystore, /tmp/cert.txt
is the file that contains BASE64 encoded certificate, and alias
is the alias by which this certificate is imported. Note that this alias must be same as that of the key pair that was used to generate this certificate request.
Take these steps to export a certificate or trusted certificate from the keystore:
From the navigation pane, locate your component instance.
Navigate to component_name, then Security, then Keystores.
Select the desired keystore from the list of stores.
A dialog box appears in which you must enter the keystore password to continue.
The Manage Certificates page appears. Click Export.
A dialog box appears which shows the Base64 encoded certificate or trusted certificate. You can either copy the contents from the text box and paste it to a file, or select the Export button to save it directly to a file.
Assuming the instance name is inst1
, use this command to export a certificate:
exportKeyStoreObject('inst1', 'ovd5', 'ovd', 'newKeystore', 'password', 'Certificate', '/tmp', 'alias')
where password
is the password for this keystore, /tmp
is the path under which the certificate is generated in BASE64 format in the file base64.txt
, and alias
is the alias of the certificate being exported.
Take these steps to delete a certificate, or a trusted certificate, from a keystore:
From the navigation pane, locate your component instance.
Navigate to component_name, then Security, then Keystores.
Select the desired keystore from the list of stores.
A dialog box appears in which you must enter the keystore password to continue.
The Manage Certificates page appears. Select the certificate or trusted certificate to be deleted, and Click Delete.
A dialog box appears asking you to confirm the choice. Select OK to confirm.
Assuming the application server instance name is inst1
, use this command to delete a certificate:
removeKeyStoreObject('inst1', 'ovd5', 'ovd', 'newKeystore', 'password', 'Certificate', 'alias')
where password
is the password for this keystore and alias
is the alias of the certificate being deleted.
Take these steps to convert a self-signed certificate, residing in a keystore, into a third-party certificate:
From the navigation pane, locate your component instance.
Navigate to component_name, then Security, then Keystores.
Select the keystore that contains the self-signed certificate from the list of stores.
A dialog box appears in which you must enter the keystore password; click OK to continue.
The Manage Certificates page appears.
A new certificate request must be generated for the self-signed certificate that is to be converted. Select the certificate and click Generate CSR. In this example, the request is made for the self-signed certificate with alias demo
.
The certificate request is displayed.
You can either:
Copy and paste the Base64-encoded certificate request to a file.
Export it directly to a file with the Export CSR button.
Submit the certificate request file to a certificate authority (CA).
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
Two files, one containing the newly generated certificate and a second containing its own CA certificate
Use Import to import these files into your keystore:
If you received a single file from the CA, import it as a certificate, using an alias that matches the alias of the self-signed certificate you are replacing (from Step 6)
If you received two files:
Import the file containing the CA certificate as a trusted certificate (use an alias that is unique in the keystore)
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.The CA returned a single file, which is imported as a certificate:
After import, the certificate issued by the CA replaces the self-signed certificate.
Use these steps to convert a self-signed certificate to a third-party certificate:
Generate and export a CSR.
exportKeyStoreObject('inst1', 'ovd5', 'ovd', 'jks1', '<password>', 'CertificateRequest', '/tmp', 'mykey')
Submit the CSR /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 two separate files.
If you receive a single file from the CA, run the command:
importKeyStoreObject('inst1', 'ovd5', 'ovd', 'jks1', 'password', 'Certificate', '/tmp/cert.txt', 'alias')
where password
is the password for this keystore, /tmp/cert.txt
is the file that the CA returned and contains the BASE64 encoded PKCS#7, and alias
is the alias by which this certificate is imported. Note that this alias must match that of the key pair that was used to generate the certificate request.
If you receive two files from the CA, import the CA certificate first as a trusted certificate, followed by the newly generated certificate:
importKeyStoreObject('inst1', 'ovd5', 'ovd', 'jks1', 'password', 'TrustedCertificate', '/tmp/cacert.txt', 'unique_alias')
where unique_alias
is a unique alias by which the trusted certificate is imported.
importKeyStoreObject('inst1', 'ovd5', 'ovd', 'jks1', 'password', 'Certificate', '/tmp/cert.txt', 'alias')
where password
is the password for this keystore, /tmp/cert.txt
is the file that the CA returned and contains BASE64 encoded certificate, /tmp/cacert.txt
is the file containing the BASE64 encoded CA certificate, and alias
is the alias by which this certificate is imported. Note that this alias must match that of the key pair that was used to generate the certificate request.
This section contains the following administration topics:
The root directory for Oracle Virtual Directory keystores is located in $ORACLE_INSTANCE/config/OVD
/ovd_instance_name
/keystores
.
This root directory will contain all the JKS files.
A sample structure, assuming there are two keystores named keys.jks
and trust.jks
respectively, would look like this:
ORACLE_INSTANCE/config/OVD/ovd_instance_name/keystores/keys.jks ORACLE_INSTANCE/config/OVD/ovd_instance_name/keystores/trust.jks
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:
Generate a certificate request from the keystore (use the same key-pair for which the current expiring certificate was issued).
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 ask the CA to issue a new certificate for that certificate request.Import the newly issued certificate into the keystore using the same alias as that of the key-pair.
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.
Typically, the certificate DN is based on the host name of the server where the keystore is used.
For example, if a keystore is being created for the Oracle Virtual Directory server on host my.example.com, then the DN of the certificate in this Oracle Virtual Directory keystore 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 HTTP Client, among others. If the host name of the server does not match that of the certificate DN:
A clear warning is displayed (in the case of browser clients).
There may be SSL handshake failure (in the case of other clients).
Thus, whenever you have a keystore 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 keystore.
This can be done by requesting a new certificate with a new DN (based on the new host name).
For a Production Keystore
The steps are:
Generate a new request with the new DN (based on a new host name).
Send this request to a certificate authority (CA).
Get back a new certificate from the CA.
Import the new certificate with the same alias as the key-pair for which certificate request was generated.
For a Self-signed Keystore
The steps are:
Delete the existing keystore.
Create a new keystore with a key-pair using the new DN (based on the new host name).
For Both Keystore Types
For both production and self-signed keystores, once the new certificate is available in the keystore, ensure that it is imported into all the component keystores where it needs to be trusted. For example, if the HTTP listener on Oracle Virtual Directory was SSL-enabled and its certificate changed due to a host name change, then you need to import its new certificate into the client keystore or browser repository so that it can trust its new peer.
This section contains the following topics:
Accessing the Wallet Management Page in Fusion Middleware Control
Accessing the Certificate Management Page for Wallets in Fusion Middleware Control
This section contains the following topics:
You can create two types of wallets:
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 11g Release 1 (11.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.
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 even 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. Modifications to the wallet must occur 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.
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 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.
Oracle recommends that you do not share wallets between component instances or Oracle 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.
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 such as Oracle Internet 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.
An Oracle wallet is associated with the component where it is utilized. To locate a component instance:
Log into Fusion Middleware Control using administrator credentials.
Select the domain of interest.
Note:
You can use Setup to discover a specific Oracle WebLogic Server domain to work with.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.
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.
Navigate to Security, then Wallets.
The Wallets page appears.
On the Wallets page, you can:
Create a wallet.
Delete a wallet.
Import a wallet.
Export a wallet.
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.
This section describes the steps required to perform a range of wallet management functions, including:
Creating a Self-Signed Wallet Using Fusion Middleware Control
Changing a Self-Signed Wallet to a Third-Party Wallet Using Fusion Middleware Control
Changing a Self-Signed Wallet to a Third-Party Wallet Using WLST
Navigate to the Wallets page for your component instance. See Section 8.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."
Click Create.
The Create Wallet page appears.
Enter a wallet name.
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 8.4.1.1, "Password-Protected and Autologin Wallets" for details.
Click Submit.
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 8.4.7.1, "Adding a Certificate Request Using Fusion Middleware Control."
In this example, we choose to add a CR:
Click Finish.
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.
A message appears confirming the wallet creation.
Note:
The WLST commands described in this chapter use Oracle Internet Directory as the example component. The same commands can be executed for Oracle HTTP Server or Oracle Web Cache by changing the third parameter fromoid
to ohs
or webcache
respectively.Assuming the instance name is inst1
, use this command to create a wallet:
createWallet('inst1', 'oid1', 'oid', 'oid2', 'password')
where oid2
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:
Section 6.9.7, "createWallet".Take these steps to create a self-signed wallet:
Navigate to the Wallets page for your component instance. See Section 8.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."
Click Create Self-Signed Wallet.
On the Self-Signed Wallet page, enter data to create the wallet. This includes:
The wallet name
Whether this is an auto-login wallet
The DN information
The key size
Click Submit.
A confirmation message is displayed and the new wallet appears in the list of wallets.
Assuming the instance name is inst1
, use these commands to create a self-signed wallet:
createWallet('inst1', 'oid1', 'oid', 'oid2', 'password') addSelfSignedCertificate('inst1', 'oid1', 'oid', 'oid2', 'password', 'subject_dn', 'key_size')
where oid2
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).
For steps to convert a self-signed wallet into a third-party wallet, see Section 8.4.8.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 8.4.8.3, "Changing a Self-Signed Wallet to a Third-Party Wallet."
Take these steps to export a wallet:
Navigate to the Wallets page for your component instance. See Section 8.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."
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.Click Export.
The Export Wallet page appears.
Enter the filename and the location where the wallet is to be exported.
Click OK.
Assuming the instance name is inst1
, use this command to export a wallet:
exportWallet('inst1', 'oid1', 'oid', '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:
Section 6.9.12, "exportWallet".Take these steps to import a wallet:
Navigate to the Wallets page for your component instance. See Section 8.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control".
Click Import.
The Import Wallet page appears.
If this is an auto-login wallet, check the box and enter the wallet name. No password is required.
If this is not an auto-login wallet, uncheck the auto-login box. Specify both the wallet name and password.
Click OK. The wallet is imported into the repository.
Assuming the instance name is inst1
, use this command to import a wallet:
importWallet('inst1', 'oid1', 'oid', 'oid5', 'password', '/tmp/ewallet.p12')
where 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:
Section 6.9.20, "importWallet".Take these steps to delete a wallet:
Navigate to the Wallets page for your component instance. See Section 8.4.2, "Accessing the Wallet Management Page in Fusion Middleware Control."
Select the row corresponding to the wallet of interest.
Click Delete.
The wallet is deleted and no longer appears on the list of wallets.
Assuming the instance name is inst1
, use this command to delete a wallet:
deleteWallet('inst1', 'oid1', 'oid', 'selfsigned')
See Also:
Section 6.9.9, "deleteWallet".The complete certificate life cycle, starting from wallet creation, includes these actions:
Create an empty wallet (that is, a wallet that does not contain a certificate request).
Add a certificate request to the wallet.
Export the certificate request.
Use the certificate request to obtain the corresponding certificate.
Import trusted certificates.
Import the certificate.
These steps are needed to generate a wallet with a third-party trusted certificate. For details about this task, see Section 8.4.7.9, "Converting a Self-Signed Certificate into a Third-Party Certificate Using Fusion Middleware Control."
An Oracle wallet is associated with the component where it is utilized. To locate a component instance:
Log into Fusion Middleware Control using administrator credentials.
Select the domain of interest.
Note:
You can use Setup to discover a specific Oracle WebLogic Server domain to work with.Use the navigation pane to locate the instance (for example, an Oracle HTTP Server instance) that will use the wallet.
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.
This section describes the following common certificate operations:
Adding a Certificate Request Using Fusion Middleware Control
Exporting a Certificate, Certificate Request, or a Trusted Certificate Using WLST
Importing a Certificate or a Trusted Certificate Using Fusion Middleware Control
Deleting a Certificate Request, a Certificate, or a Trusted Certificate Using WLST
Converting a Self-Signed Certificate into a Third-Party Certificate Using Fusion Middleware Control
Converting a Self-Signed Certificate into a Third-Party Certificate Using WLST
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:
Navigate to the Certificate Management page. See Section 8.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."
Click Add Certificate Request.
A dialog box appears where you enter the CRs DN values:
Fields marked with an asterisk (*) are required.
Click OK.
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.
Assuming the instance name is inst1
, use this command to add a certificate request for a wallet:
addCertificateRequest('inst1', 'oid1', 'oid', '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.
Take these steps to export a certificate, a certificate request (CR), or a trusted certificate:
Navigate to the Certificate Management page. See Section 8.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."
Select the certificate, CR, or trusted certificate and click Export.
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.
Assuming the instance name is inst1
, use this command to export a certificate request:
exportWalletObject('inst1', 'oid1', 'oid', '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
.
Note:
You cannot use Fusion Middleware Control to import DER-encoded certificates or trusted certificates into an Oracle wallet. Use one of these tools instead:Oracle Wallet Manager or
orapki
command-line tool
Take these steps to import a certificate or a trusted certificate:
Navigate to the Certificate Management page. See Section 8.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."
Click Import.
In the Import Certificate dialog, you can select either a certificate or a trusted certificate.
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.
Click OK.
Note:
You cannot use theWLST
command-line tool to import DER-encoded certificates or trusted certificates into an Oracle wallet. Use one of these tools instead:
Oracle Wallet Manager or
orapki
command-line tool
Assuming the instance name is inst1
, use this command to import a certificate into a wallet:
importWalletObject('inst1', 'oid1', 'oid', '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
.
Take these steps to delete a CR, a certificate, or a trusted certificate:
Navigate to the Certificate Management page. See Section 8.4.6, "Accessing the Certificate Management Page for Wallets in Fusion Middleware Control."
Select the row containing the certificate request, certificate or trusted certificate.
Click Delete.
A dialog box appears, requesting confirmation.
Click Yes.
The object no longer appears in the Manage Certificates list.
Assuming the instance name is inst1, use this command to delete a certificate:
removeWalletObject('inst1', 'oid1', 'oid', '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
.
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 and Oracle Web Cache.From the navigation pane, locate your component instance.
Navigate to component_name, the Security, then Wallets.
From the list of wallets, select the wallet that contains the self-signed certificate.
The Manage Certificates page appears. It contains the list of certificates in the wallet.
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:
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.
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.
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
Two files, one containing the newly generated certificate and a second containing its own CA certificate
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 files:
Import the file containing the CA certificate as a trusted certificate (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.The CA returned a single file, which is imported as a trusted certificate:
After import, the certificate issued by the CA replaces the self-signed certificate.
Follow these steps to convert a self signed certificate to a third-party certificate using WLST:
Add a certificate request, for example:
addCertificateRequest('inst1', 'oid1', 'oid', 'selfsigned', 'password', 'subject_dn', 'key_size')
Export the certificate request:
exportWalletObject('inst1', 'oid1', 'oid', 'selfsigned', 'password', 'CertificateRequest', '/tmp', 'subject_dn')
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 two separate files.
If you receive a single file from the CA, run the following command
importWalletObject('inst1', 'oid1', 'oid', '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 files from the CA, import the CA certificate first as a trusted certificate, followed by the newly generated certificate.
importWalletObject('inst1', 'oid1', 'oid', 'selfsigned', 'password', 'TrustedCertificate', '/tmp/cacert.txt') importWalletObject('inst1', 'oid1', 'oid', '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.
This section contains the following administration topics:
This section describes the location of wallets for different components.
Root Directory for an Oracle Internet Directory Wallet
The root directory for wallets is $ORACLE_INSTANCE/OID/admin
.
This root directory will contain subdirectories with wallet names; these subdirectories will contain the actual wallet files.
For example, assuming there are two wallets named oid1
and oid2
, respectively, a sample structure could look like:
$ORACLE_INSTANCE/OID/admin/oid1/cwallet.sso $ORACLE_INSTANCE/OID/admin/oid1/ewallet.p12 $ORACLE_INSTANCE/OID/admin/oid2/cwallet.sso
Root Directory for an Oracle HTTP Server Wallet
The root directory for wallets is $ORACLE_INSTANCE/config/OHS
/ohs_instance_name
/keystores
.
This root directory contains subdirectories with wallet names; these subdirectories contain the actual wallet files.
For example, assuming there are two wallets named ohs1
and ohs2
, respectively, a sample structure could look like:
$ORACLE_INSTANCE/config/OHS/ohs_instance1/keystores/ohs1/cwallet.sso $ORACLE_INSTANCE/config/OHS/ohs_instance1/keystores/ohs1/ewallet.p12 $ORACLE_INSTANCE/config/OHS/ohs_instance1/keystores/ohs2/cwallet.sso
Root Directory for an Oracle Web Cache Wallet
The root directory for wallets is $ORACLE_INSTANCE/config/WebCache
/webcache_instance_name
/keystores
.
This root directory will contain subdirectories with wallet names; these subdirectories will contain the actual wallet files.
For example, assuming there are two wallets named wc1
and wc2
, respectively, a sample structure could look like:
$ORACLE_INSTANCE/config/WebCache/webcache_instance1/keystores/wc1/cwallet.sso $ORACLE_INSTANCE/config/WebCache/webcache_instance1/keystores/wc1/ewallet.p12 $ORACLE_INSTANCE/config/WebCache/webcache_instance1/keystores/wc2/cwallet.sso
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).
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.
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).
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.
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:
Remove the user certificate "CN=my.example.com,O=example
" from the wallet.
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).
Export the certificate request "CN=my.example.com,O=example
" from the wallet and save it to a file.
Give this certificate request file to a third-party certificate authority (CA) such as Verisign.
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
Import the above file(s) into the 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:
Export the certificate request from the wallet (this is the same request for which the current expiring certificate was issued).
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.Remove the existing certificate (the one that is about to expire) from the wallet.
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.
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.