Topics:
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:
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 |
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 Oracle Fusion Middleware Infrastructure Security WLST Command Reference for details about the importKeyStore
, exportKeyStore
, and syncKeyStore
commands.
A JKS keystore is the default JDK implementation of Java keystores. Java EE applications can use the JKS-based keystore and truststore.
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.
Oracle Fusion Middleware provides WLST, orapki and Fusion Middleware Control as 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
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 Oracle Fusion Middleware 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 Oracle Fusion Middleware 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 keyUsage Extension Required for Certificates in JDK7.
Additional Information
Details about the tools are provided in these sections:
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.
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','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
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 Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services.
Oracle wallets provide a full range of management features to enable you to create, maintain, and delete certificates for various applications.
Note:
For wallet configuration in a stand-alone context, for example a stand-alone Oracle HTTP Server, see orapki.
This section contains the following topics:
This discussion assumes that components are installed within a WebLogic domain.
Review these topics for various types of wallets and their recommendation, conventions and requirements.
This section contains the following topics:
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.
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.
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.
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.
JDK7 requires the keyUsage
extension for self-signed CA certificates used for SSL configuration.
For details, see keyUsage Extension Required for Certificates in JDK7.
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 Oracle Fusion Middleware Infrastructure Security WLST Command Reference for details about the importKeyStore
, exportKeyStore
, and syncKeyStore
commands.
Follow these procedures for the steps required to perform a range of wallet management functions.
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.
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]
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.
Review this topic for the typical life cycle event of a certificate, starting from wallet creation.
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 “Replacing Demonstration CA Signed Certificates” in Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services.
Follow these procedures for the steps required to perform a range of certificate management functions.
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.
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.
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/.
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.
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.
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.
Review these topics for more information on maintaining wallet and certificates.
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
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).
You can request a new certificate to import into a production wallet.
The steps are:
See Common Wallet Operations for details about these operations.
To add a new certificate to a self-signed wallet, you need to create a new wallet for the certificate.
The steps are:
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.
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:
See Common Wallet Operations for details about these operations.
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:
See Common Wallet Operations for details about these operations.