Configuring Keystores

29 Configuring Keystores

Learn how to configure Oracle WebLogic Server to use JKS keystores for identity and trust.

For background information about identity and trust keystores, see Identity and Trust in Understanding Security for Oracle WebLogic Server. For information about how to configure the Oracle OPSS Keystore Service (KSS), see Configuring Oracle OPSS Keystore Service.

About Configuring Keystores in WebLogic Server

Learn about the concepts related to the configuration and use of keystores with WebLogic Server.

About Private Keys, Digital Certificates, and Trusted Certificate Authorities

Private keys, digital certificates, and trusted certificate authorities establish and verify server identity and trust.

SSL uses public key encryption technology for authentication. With public key encryption, a public key and a private key are generated for a server. Data encrypted with the public key can only be decrypted using the corresponding private key and data encrypted with the private key can only be decrypted using the corresponding public key. The private key is carefully protected so that only the owner can decrypt messages that were encrypted using the public key.

The public key is embedded in a digital certificate with additional information describing the owner of the public key, such as name, street address, and e-mail address. A private key and digital certificate provide identity for the server.

The data embedded in a digital certificate is verified by a certificate authority (CA) and digitally signed with the CA's digital certificate. Well-known certificate authorities include Entrust and Symantec Corporation. The trusted CA certificate establishes trust for a certificate.

An application participating in an SSL connection is authenticated when the other party evaluates and accepts the application's digital certificate. Web browsers, servers, and other SSL-enabled applications generally accept as genuine any digital certificate that is signed by a trusted CA and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the CA used to sign it expired. A server certificate can be invalidated if the host name in the digital certificate of the server does not match the URL specified by the client.

Servers need a private key, a digital certificate containing the matching public key, and a certificate of at least one trusted certificate authority (CA). WebLogic Server supports private keys, digital certificates, and trusted CA certificates from the following sources:

Private keys and digital certificates issued by a reputable CA, such as Entrust or Symantec Corporation.
The private key and self-signed digital certificate for WebLogic Server that are created by the keytool utility.
The demonstration digital certificates, private keys, and trusted CA certificates in the DOMAIN_HOME\security, WL_HOME\server\lib, and JAVA_HOME\jre\lib\security directories.

Note:

The demonstration digital certificates, private keys, and trusted CA certificates should be used in a development environment only.
Use the digital certificates and private keys generated by the CertGen utility only for testing and demonstration purposes. These certificates should be used in a development environment only, never in a production environment.

Using Separate Keystores for Identity and Trust

When you configure SSL, you must decide how identity and trust will be stored. Although one keystore can be used for both identity and trust, Oracle recommends using separate keystores for both identity and trust because the identity keystore (holding the private key and associated digital certificate) and the trust keystore (trusted CA certificates) may have different security requirements. For example:

For trust, you only need the certificates (non-sensitive data) in the keystore. However, for identity, you add the certificate and the private key (sensitive data) in the keystore.
The identity keystore may be prohibited by company policy from ever being put on the corporate network, while the trust keystore can be distributed over the network.
The identity keystore may be protected by the operating system for both reading and writing by non-authorized users, while the trust keystore only needs to be write protected.
The identity keystore password is generally known to fewer people than the password for the trust keystore.

In general, systems within a domain have the same trust rules — they use the same set of trusted CAs — but they tend to have per-server identity. Identity requires a private key, and private keys should not be copied from one system to another. Therefore, you should maintain separate identity keystores for each system, each keystore containing only the server identity needed for that system. However, trust keystores can be copied from system to system, thus making it easier to standardize trust conventions.

Identity is more likely to be stored in hardware keystores such as nCipher. Trust can be stored in a file-based JDK keystore without having security issues because a trust store contains only certificates, not private keys.

Configuring Keystores: Main Steps

To configure identity and trust keystores for a WebLogic Server instance being used in a production environment, complete the following steps:

Create the keystore to hold the server identity certificate. See Creating a Keystore.
Create a Certificate Signing Request (CSR), and submit it to a reputable Certificate Authority. See Generating a Certificate Signing Request. Oracle strongly recommends this step for production environments.
Import the identity and trust certificates returned by the CA. See Importing Certificates into the Trust and Identity Keystores.
Configure the trust and identity keystores with WebLogic Server. See Configuring Keystores with WebLogic Server

If you are working in a development environment where security requirements typically are less stringent, you can use the demonstration certificates included with WebLogic Server and create self-signed certificates. However, do not use these certificates in a production environment. See Using Keystores and Certificates in a Development Environment.

How WebLogic Server Locates Trust

WebLogic Server uses the following algorithm when it loads its trusted CA certificates:

If, when the Managed Server is started, the keystore is specified by the -Dweblogic.security.SSL.trustedCAkeystore command-line argument, then WebLogic Server loads the trusted CA certificates from that keystore.

Note:
If, however, the Managed Server instance is started using DOMAIN_DIR/bin/startManagedWebLogic.sh managed_instance_name admin_SSL_url, then steps 2 and 3 are not applicable to the outbound SSL connection established with the Administration Server for downloading the configuration.
Else if the keystore is specified in the configuration file (config.xml), WebLogic Server loads trusted CA certificates from the specified keystore. If the server is configured with DemoTrust, trusted CA certificates will be loaded from the WL_HOME\server\lib\DemoTrust.jks (or kss://system/trust if Oracle OPSS Keystore Service [KSS] is used) and the JDK cacerts keystores.
Else if the trusted CA file is specified in the configuration file (config.xml), WebLogic Server loads trusted CA certificates from that file (this is only for compatibility with 6.x SSL configurations).
Else WebLogic Server loads trusted CA certificates from the keystore WL_HOME\server\lib\cacerts.

Creating a Keystore

You can create a JKS keystore using either the keytool or the ImportPrivateKey utilities. Oracle recommends that you keep server certificates and trusted CA certificates in separate keystores.

The following sections explain how to create a keystore. However, in practice, creating a keystore is typically done in conjunction with obtaining a server certificate for the identity keystore or importing a trusted CA certificate into the trust keystore, as explained in Obtaining and Storing Certificates for Production Environments.

Note:

The preferred keystore format is JKS (JKS keystore). WebLogic Server supports private keys and trusted CA certificates stored in files or in the WebLogic Keystore provider for the purpose of backward compatibility only.

Keystore File Name Requirements

When choosing a name for the keystore file:

Do not choose a file name longer than 256 characters.
Do not use special characters, except for an underscore (_) or hyphen (-).
Do not use non-ASCII characters.
Follow the operating system-specific rules for directory and file names.

Creating a Keystore Using Keytool

Keytool is a key and certificate management utility that is included in the JDK. It allows you to administer your own public/private key pairs and associated certificates for use in self-authentication (in which you authenticate yourself to other users or services) or data integrity and authentication services, using digital signatures. Keytool also allows you to cache the public keys, in the form of certificates, of your communicating peers.

When you use keytool to create a public and private key pair, keytool also creates a keystore if one does not already exist in the current directory.

To use keytool to create a JKS keystore, complete the following steps:

Create a directory to hold the keystore. For example: ORACLE_HOME/keystores.
Change to the bin subdirectory of your WebLogic domain root directory. For example:
```
prompt> cd DOMAIN_HOME/bin
```
Run the setDomainEnv script, which sets the domain-wide environment for starting and running WebLogic Server instances.
Change to the directory you created for the keystore and enter the following command:
```
prompt> keytool -genkeypair -alias alias -keyalg RSA -keysize 1024 -dname dn -keystore keystore
```
In the command, enter the following values:
- A private key alias, represented by alias.
- The X.500 Distinguished Name associated with the private key alias, represented by dn.
- The name of the keystore being created, represented by keystore.
- The key pair generation algorithm RSA.

When you enter the keytool command as described in the preceding steps, keytool automatically prompts you for the following:

The keystore password
The password for the private key, which is represented by its alias

For example:

prompt> keytool -genkeypair -alias server_cert -keyalg RSA -keysize 2048 -dname "CN=server.avitek.com,OU=Support,O=Avitek,L=Reading,ST=Berkshire,C=GB" -keystore keystore.jks
Enter keystore password:
Re-enter new password:
Enter key password for <server_cert>
        (RETURN if same as keystore password):
Re-enter new password:

Note the following from the preceding example:

The keystore file is named keystore.jks.
The private key alias is server_cert.
The X.500 Distinguished Name, which consists of the WebLogic Server host and DNS domain name, is server.avitek.com.

Note:

Make note of the private key alias and passwords you specify, and be sure to record passwords only in a safe location.

For a summary of keytool commands commonly used with WebLogic Server, see Keytool Command Summary. For complete details about keytool, see "keytool" at http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html.

Creating a Keystore Using ImportPrivateKey

If you have a certificate and private key, you use the ImportPrivateKey utility to create a keystore in which you can store that certificate and key.

If you used CertGen to create a private key file that is protected by a password, that password is the one required by ImportPrivateKey to extract the key from the key file and insert the key in the keystore being created.

To create a keystore using ImportPrivateKey, complete the following steps:

Change to the bin subdirectory of your WebLogic domain root directory.
Run the setDomainEnv script, which sets the domain-wide environment for starting and running WebLogic Server instances.
Change to the directory in which you want to create the keystore.
Generate the certificate and private key.

For example, using CertGen:
1. Enter the following command to generate the certificate file named testcert and the private key file named testkey:
```
prompt> java utils.CertGen -keyfilepass mykeyfilepass -certfile testcert -keyfile testkey
Generating a certificate with common name return and key strength 1024
issued by CA with certificate from CertGenCA.der file and key from CertGenCAKey.der file
```
2. Convert the certificate from DER format to PEM format. For example:
```
prompt> java utils.der2pem CertGenCA.der
```
  Note:
  
  By default, the CertGen utility looks for the CertGenCA.der and CertGenCAKey.der files in the current directory, or in the WL_HOME/server/lib directory, as specified in the weblogic.home system property or the CLASSPATH.
  
  Alternatively, you can specify CA files on the command line. If you want to use the default settings, there is no need to specify CA files on the command line.
Concatenate the certificate and the Certificate Authority (CA) certificate. For example:
```
prompt> cat testcert.pem CertGenCA.pem >> newcerts.pem
```

Create a new keystore and load the private key.

For example, to create a keystore named mykeystore and load the private key located in the file testkey.pem, enter the following command:

prompt> java utils.ImportPrivateKey -keystore mykeystore -storepass mystorepasswd-keyfile mykey -keyfilepass mykeyfilepass -certfile newcerts.pem -keyfiletestkey.pem -alias passalias
No password was specified for the key entry
Key file password will be used

Imported private key testkey.pem and certificate newcerts.pem
into a new keystore mykeystore of type jks under alias passalias

For more information about using the ImportPrivateKey utility, see ImportPrivateKey in Command Reference for Oracle WebLogic Server.

Using Keystores and Certificates in a Development Environment

Learn about the tools and procedures to generate digital certificates and private keys for demonstration or testing purposes in a development environment. This information does not apply to a WebLogic Server production environment.

This section includes the following topics:

Using the Demonstration Keystores

By default, WebLogic Server is configured with two keystores, which are located in the DOMAIN_HOME\security and WL_HOME\server\lib directories, respectively:

DemoIdentity.jks—Contains a demonstration private key for WebLogic Server. This keystore contains the identity for WebLogic Server.

Note:

As of version 12.1.2 of WebLogic Server, the DemoIdentity.jks keystore is generated at domain creation and is located in the DOMAIN_HOME\security directory. The demo CA certificate has a 2048-bit key size, uses the SHA256 message digest algorithm, and has a Key Identifier extension.
DemoTrust.jks—Contains the trusted certificate authorities from the WL_HOME\server\lib\DemoTrust.jks and the JDK cacerts keystores. This keystore establishes trust for WebLogic Server.

For testing and development purposes, the keystore configuration is complete. The digital certificates and trusted CA certificates in the demonstration keystores are signed by a WebLogic Server demonstration certificate authority. For this reason, a WebLogic Server installation that uses these demonstration keystores will trust any WebLogic Server installation that also uses these demonstration keystores. Therefore, you should never use these demonstration keystores in a production environment. For information about how to configure keystores for use in a production environment, see Obtaining and Storing Certificates for Production Environments.

Creating Demonstration Certificates Using CertGen

The following sections explain the use of CertGen for creating demonstration certificates and private keys for use in a development environment:

About CertGen

The CertGen utility provides command line options to specify a CA certificate and key to be used for issuing generated certificates. The digital certificates generated by the CertGen utility by default have only the host name of the machine on which they were generated, and not the fully-qualified DNS name, as the value for its common name field (cn). Command line options let you specify values for the cn and other Subject domain name (DN) fields, such as orgunit, organization, locality, state, and countrycode.

Use the CertGen utility if you want to set an expiration date in the digital certificate or specify a correct host name in the digital certificate so that you can use host name verification. (The demonstration digital certificate provided by WebLogic Server uses the machine's default host name as the host name.)

The CertGen utility generates public certificate and private key files in PEM and DER formats. To view the details of the generated digital certificate on Windows platforms, double-click .der files in Windows Explorer

By default, the CertGen utility uses the following demonstration digital certificate and private-key files: CertGenCA.der and CertGenCAKey.der. CertGen looks for these files in the current directory, or in the WL_HOME/server/lib directory, as specified in the weblogic.home system property or the CLASSPATH. If you want to use these files, you do not need to specify CA files in the CertGen command; however, you can specify those CA files in the command is desired.

For complete details about the CertGen utility's syntax and arguments, see CertGen in the Command Reference for Oracle WebLogic Server.

Using CertGen to Create a Certificate and Private Key

To create a certificate and private key using CertGen, complete the following steps:

Open a command window and change to the bin subdirectory of your WebLogic domain root directory.
Run the setDomainEnv script. This script sets the domain-wide environment for starting and running WebLogic Server instances.
Optionally, change to the directory in which you want to create the certificate and private key.
Generate the certificate and private key using the following command:
```
java utils.CertGen -keyfilepass keyfilepass -certfile cert-name -keyfile keyfile-name
```
In the preceding command:
- keyfilepass represents the password for the private key file.
- cert-name represents the name of the certificate.
- keyfile-name represents the name of the private key file.
For example, the following command generates the certificate file named testcert and the private key file named testkey:
```
prompt> java utils.CertGen -keyfilepass mykeyfilepass -certfile testcert -keyfile testkey
Generating a certificate with common name return and key strength 1024
issued by CA with certificate from CertGenCA.der file and key from CertGenCAKey.der file
```

CertGen Usage Notes

Note the following about using CertGen:

By default, the CertGen utility looks for the CertGenCA.der and CertGenCAKey.der files in the current directory, or in the WL_HOME/server/lib directory, as specified in the weblogic.home system property or the CLASSPATH.

Alternatively, you can specify CA files on the command line. If you want to use the default settings, there is no need to specify CA files on the command line.
If you do not explicitly specify a host name with the -cn option, CertGen uses the JDK InetAddress.getHostname() method to get the host name, which CertGen inserts in the Subject common name.

However, note that the results of the getHostName() method depends on the platform on which it is used. For example:
- On some platforms, such as Solaris, this method returns a fully qualified domain name (FQDN).
- On other platforms, such as Windows NT, this method returns a short host name.
- On Solaris platforms, the result of InetAddress.getHostname() depends on how the hosts entry is configured in the /etc/nsswitch.conf file.
If WebLogic Server is acting as a client and host name verification is enabled (which it is by default), you need to ensure that the host name specified in the URL matches the Subject common name in the server certificate. Otherwise, connections fail because the host names do not match.

Limitation on CertGen Usage

By default, a WebLogic Server domain is configured with the DemoIdentity.jks keystore, which contains a demonstration public certificate and private key for WebLogic Server. This certificate and key are created by CertGen with the default options of containing only the host name in the common name field (cn), and not the fully-qualified DNS name. As a result, attempts to establish SSL connections may fail in some situations due to a host name verification exception. This section describes this limitation and provides some workarounds.

If you are using the demo certificates in a multi-server domain, Managed Server instances fail to boot if they cannot establish an SSL connection with the Administration Server. An error message similar to the following may be generated:

BAD_CERTIFICATE alert was
received from node-name.avitek.com - xxx.yy.zzz.yyy. Check the peer to
determine why it rejected the certificate chain (trusted CA configuration,
hostname verification). SSL debug tracing may be required to determine the
exact reason the certificate was rejected.

This error occurs because the host name verifier, which is enabled by default in all WebLogic domains and which is used during the SSL handshake, compares the value of the cn field in the certificate with the fully-qualified DNS name of the SSL server that accepts the SSL connection. If these names do not match, the SSL connection is dropped.

If you use the demo identity certificates in a WebLogic domain, you can use the following workarounds:

Specify the SSL listen address of each WebLogic Server instance in a domain as the host name that appears in the certificate's cn field. Avoid using the fully-qualified DNS name or IP address. This workaround consists of two steps:
1. When using the Configuration Wizard to create the WebLogic domain, specify the listen address of each WebLogic Server instance as a simple host name as it appears in the certificate's cn field, not as a fully-qualified DNS name or IP address. For example, if the host name in the certificate is avitek01, the listen address for the server instance should be specified simply as avitek01.
2. At run time, when specifying the SSL listen address of a server instance, make sure the URL also matches the host name for that server as specified as the certificate's cn field. For example:
```
https://avitek01:7002
```
When starting a Managed Server instance, pass the URL of the Administration Server's SSL listening address as a parameter to the startManagedWebLogic script. The URL should be specified in a form that excludes the domain suffix. For example:
```
C:\mydomain\bin> startManagedWebLogic.cmd https://admin01:7002
```
Disable host name verification. This causes WebLogic Server to skip the verification check of ensuring that the host name in the URL to which a connection is made matches the host name in the digital certificate that the server sends back as part of the SSL connection.

You can disable host name verification by including a command similar to the following in the setDomainEnv script:
```
set JAVA_OPTIONS=%JAVA_OPTIONS% -Dweblogic.security.SSL.ignoreHostnameVerification=true
```
For information about configuring host name verification, see Using Host Name Verification.

Note:

Oracle does not recommend using the demo certificates, or turning off host name verification, in production environments.

Using Your Own Certificate Authority

Many companies act as their own certificate authority. To use those trusted CA certificates with WebLogic Server:

Ensure the trusted CA certificates are in PEM format.
- If the trusted CA certificate is in DER format, use the der2pem utility to convert them.
- If the trusted CA certificate was issued by Microsoft, see Converting a Microsoft p7b Format to PEM Format.
- If the trusted CA certificate has a custom file type, use the steps in Converting a Microsoft p7b Format to PEM Format to convert the trusted CA certificate to PEM format.
Create the trust keystore to hold the trusted CA certificate, as explained in Creating a Keystore.
Store the trusted CA certificate in the trust keystore. See Importing Certificates into the Trust and Identity Keystores.
Configure WebLogic Server to use the trust keystore. See Configuring Keystores with WebLogic Server.

Converting a Microsoft p7b Format to PEM Format

Digital certificates issued by Microsoft are in a format (p7b) that cannot be used by WebLogic Server. The following example converts a digital certificate in p7b (PKCS#7) format to PEM format on Windows XP:

In Windows Explorer, select the file (filename.p7b) you want to convert. Double-click on the file to display a Certificates window.
In the left pane of the Certificates window, expand the file.
Expand the Certificates folder to display a list of certificates.
Select a certificate to convert to PEM format. Right-click on the certificate, then choose All Tasks > Export to display the Certificate Export Wizard.
In the wizard, click Next.
Select the Base-64 encoded X.509 (.CER) option. Then click Next. (Base-64 encoded is the PEM format.)
In the File name field, enter a name for the converted digital certificate; then click Next.

Note:

The wizard appends a .cer extension to the output file. The .cer extension is a generic extension which is appended to both base-64 encoded certificates and DER certificates. You can change the extension to .pem after you exit the wizard.
Verify that the settings are correct. If the settings are correct, click Finish; if they are not correct, click Back and make any necessary modifications.

Note:

For p7b certificate files that contain certificate chains, you need to concatenate the issuer PEM digital certificates to the certificate file. The resulting certificate file can be used by WebLogic Server.

Configuring Demo Certificates for Clients

To use SSL in development mode between a client such as Eclipse and WebLogic Server, configure the demo certificates in the JVM for both the client and the server as follows:

Copy ORACLE_HOME/wlserver/server/lib/cacerts to the jre/lib/security directory of the client's JVM. For example, if you are using Eclipse with its default JDK, copy cacerts to ORACLE_HOME/jdk/jre/lib/security.
Copy ORACLE_HOME/wlserver/server/lib/cacerts to the jre/lib/security directory of the WebLogic Server's JVM.
Restart both WebLogic Server and the client.

As an alternative, you can import the certificates, rather than copying the cacerts files.

Obtaining and Storing Certificates for Production Environments

To obtain a digital certificate for use in a production environment, you must generate a Certificate Signing Request (CSR) and issue it to a reputable CA. The CA returns a digital certificate that is signed with the CA's private key and that is used for establishing identity. The CA also returns the CA's signed public certificate, which is used for trust. You then import the digital certificate for identity into your identity keystore, and the CA's public certificate into the trust keystore.

The following sections explain these steps in detail:

Generating a Certificate Signing Request

Oracle strongly recommends that all certificates used in a production environment are signed by a reputable Certificate Authority (CA). To obtain a CA-signed certificate, you must issue an individual Certificate Signing Request (CSR) for each certificate that you plan to use in that production environment.

To generate a CSR, complete the following steps:

Create a keystore to hold the identity of the WebLogic Server instance, if you have not already done so, as explained in Creating a Keystore.
Open a command window, change to the bin subdirectory of your WebLogic domain, and run the setDomainEnv script. For example, on Windows systems:
```
prompt> cd DOMAIN_HOME/bin
prompt> setDomainEnv
```
In the preceding path, DOMAIN_HOME represents the WebLogic domain root directory.
Change to the directory that contains your keystore and create a CSR using the keytool command with the following syntax:
```
keytool -certreq -v -alias alias -file certreq_file -keystore keystore
```
In the preceding command syntax:
- alias represents the private key alias specified when you created the keystore
- certreq_file represents the name of the file that contains the CSR.
- keystore represents the keystore.
Note that when you enter the preceding command, you are prompted for the passwords for the keystore and the private key, which you specified when you created the keystore.
Submit the CSR file to a certificate authority (CA) of your choice.

The CSR file is encoded in PKCS#10 format and may look similar to the following:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBtzCCASACAQAwdzELMAkGA1UEBhMCR0IxEjAQBgNVBAgTCUJlcmtzaGlyZTEQMA
4GA1UEBxMHUmVhZGluZzEPMA0GA1UEChMGT3JhY2xlMRAwDgYDVQQLEwdTdXBwb3J0
MR8wHQYDVQQDExZtYXJzaGFsbC51ay5vcmFjbGUuY29tMIGfMA0GCSqGSIb3DQEBA
QUAA4GNADCBiQKBgQCEopgMZp1lI6jWXxb1rM1kWIc1l8bhiV/0UTcsdKzeaSHxbO
SLO3Ed9kxNWAZgXaR9f5FBlwkaRJ+IR163e64v3SplHenxHfVRaHYWPZx4KlJz/6p
Yd1fAlF0PdQm1DNoFtKmCHVk/cRuvGRpsp38l7K2mYlyQ+GxH38llS7g3owIDAQAB
oAAwDQYJKoZIhvcNAQEFBQADgYEAD/sG1+rSI76OjihHg3WezT+VIbSRJxyly9nbx
4uwXbDHh8DGgQLAXV51C9ioaMrm+dM0eygVDDMESXFxvJiYipS/pphgYt1xDBgnEH
GcNiX3BnTaLNtzYlc5eAMsmbDlpk/qOxvQiH3bKN+UKYQlBXJZWPL6FusXu2LMTrk
zsY=
-----END NEW CERTIFICATE REQUEST-----

Note:

The Certificate Request Generator servlet is deprecated. Use the keytool utility instead.

Importing Certificates into the Trust and Identity Keystores

After you submit a CSR to a CA, the CA returns the following:

The CA's signed public certificate. (This certificate may be an intermediate certificate that is signed by a high-level CA, or it may be a self-signed (root) certificate.)

You place this certificate into the keystore designated as the trust keystore.
A CA-signed digital certificate for WebLogic Server. This is often referred to simply as the server certificate.

You place the server certificate into the keystore designated as the identity keystore.
Optionally, one or more intermediate certificates that establish the chain of trust to the root CA certificate.

To import the CA-signed certificates into the trust and identity keystores, complete the following steps:

Open a command window, change to the bin subdirectory of your WebLogic domain, and run the setDomainEnv script. For example, on Windows systems:
```
prompt> cd DOMAIN_HOME/bin
prompt> setDomainEnv
```
In the preceding path, DOMAIN_HOME represents the WebLogic domain root directory.
Change to the directory to hold the trust keystore and enter the following keytool command. This command creates the trust keystore, if it does not already exist, and imports the CA-signed certificate:
```
keytool -importcert -file CAcert -alias CAcert-alias -keystore keystore
```
In the preceding command:
- CAcert represents the name of the CA's signed public certificate.
- CAcert-alias represents the alias of the CA's signed public certificate.
- keystore represents the keystore file name.
If you currently have additional trusted CA-signed public certificates or intermediate certificates, or receive them in the future, you can add them to the preceding trust keystore using the same keytool command. For example:
```
keytool -importcert -file CAcert2 -alias CAcert2-alias -keystore keystore
```
If you are importing certificates that are part of a sequentially-ordered certificate path, you must import those certificates into the trust keystore in the order in which they exist in that path. If you import them in the wrong sequence, the SSL handshake when making a connection may fail. For example, consider the following certificate path:
- Root CA certificate, rootCA
- Intermediate certificate ICA1, which is signed by rootCA
- Intermediate certificate ICA2, which is signed by ICA1
In the preceding certificate path, you would import rootCA into the trust keystore first, followed by ICA1, then finally by ICA2. If these certificates are imported into the keystore in the wrong sequence,
Note:

Note the following:
- A root CA may impose a limit on the number of intermediate certificates that may exist in a certificate path based on a root certificate issued by that CA. See Certificate Authorities in Understanding Security for Oracle WebLogic Server.
- If your trust keystore does not contain the certificate of the intermediate CA that signed your server certificate, but that intermediate CA is trusted by the target of an SSL connection that you are making, the SSL connection may succeed by means of transitive trust.
Make a backup copy of the trust keystore.
Change to the directory that contains the identity keystore for WebLogic Server.
Import the CA-signed server certificate into your keystore using the following keytool command:
```
keytool -importcert -v -alias alias -file servercert_file -keystore keystore
```
In the preceding syntax:
- alias represents the alias of the server certificate, which must be the same as the private key alias assigned in Step 4.)
- servercert_file represents the name of the file that contains the CA-signed server certificate.
- keystore represents the name of your keystore.
- Using the -v option increases the amount of information displayed in the command output.
For example, the following command imports the server certificate server.pem into the keystore, using the alias (server_cert) assigned in Step 4:
```
prompt> keytool -importcert -v -alias server_cert -file server.pem -keystore keystore.jks
Enter keystore password:
Certificate reply was installed in keystore[Storing keystore.jks
]
```
Make a backup copy of the identity keystore.

Configuring Keystores with WebLogic Server

All private key entries in a keystore are accessed by WebLogic Server through the use of aliases, which you specify when loading private keys into the keystore. Although WebLogic Server does not use the alias to access trusted CA certificates, the keystore does require an alias when loading a trusted CA certificate into the keystore. After you have created the identity and trust keystores, you need to configure WebLogic Server to use them.

Aliases are case-insensitive: the aliases Hugo and hugo would refer to the same keystore entry. When subsequently you configure SSL, aliases for private keys are specified in the Private Key Alias field on the Configuration > SSL page in the WebLogic Server Administration Console.

This section includes the following topics:

Configuring Keystores Using the Administration Console

To configure the identity and trust keystores for a WebLogic Server instance using the WebLogic Server Administration Console, complete the following steps:

Start the WebLogic Server Administration Console, if necessary.
In the left pane of the Console, expand Environment and select Servers.
Click the name of the WebLogic Server instance for which you want to configure the identity and trust keystores.
Select Configuration > Keystores.

This displays the console page in which you configure your trust and identity keystores, shown in Figure 29-1.

Figure 29-1 Keystore Configuration Console Page

Description of "Figure 29-1 Keystore Configuration Console Page"
Select Change to modify the configuration rules that WebLogic Server uses to locate the server's identity and trust keystores, and select one of the following choices:
- Demo Identity and Demo Trust — Keep this configuration setting if you are using the demo certificates only for development use. This is the default setting, using the demonstration identity and trust keystores located in the DOMAIN_HOME/security and ORACLE_HOME/server/lib directories, respectively, and the JDK cacerts keystore.
- Custom Identity and Java Standard Trust — Select this configuration to use an identity keystore you created and the trusted CAs that are defined in the cacerts file in the JAVA_HOME\jre\lib\security directory.
- Custom Identity and Custom Trust — Select this configuration to use both identity and trust keystores that you created (typically you select this for a production environment).
- Custom Identity and Command Line Trust — Select this configuration to use an identity keystore you created, but a trust keystore that is passed as an argument in the command that starts WebLogic Server.
Depending on the configuration rules you specify, followed by clicking Save, the Keystore Configuration console page displays the appropriate fields for entering the identity and trust keystore information that is needed.
Specify the identity and trust keystore information required as appropriate for the selected keystore configuration rules, and click Save.
To ensure that all the SSL connections exist according to the specified configuration, you have two options:
- Select the Restart SSL button on the Control: Start/Stop page, shown in Figure 29-2. This option enables you to put keystore changes into effect for new connections without rebooting WebLogic Server.
- Reboot WebLogic Server. This option puts keystore changes into effect for all connections.
Figure 29-2 Restarting SSL

Description of "Figure 29-2 Restarting SSL"

For information about configuring keystores for WebLogic Server using the WebLogic Server Administration Console, see Configure keystores in the Oracle WebLogic Server Administration Console Online Help.

Configuring a Keystore Using WLST

This section provides an example of using WLST to configure the identity and trust keystores for WebLogic Server. Example 29-1 does the following:

Connects to the Managed Server instance for which the identity and trust keystores are being configured.
Navigates to the MBean that corresponds to the specific server instance for which the identity and trust keystores are to be configured, myserver.
Sets the configuration rule that WebLogic Server uses to locate the identity and trust keystores, CustomIdentityAndCustomTrust.
Sets the name and location of the identity keystore file, Identity.jks.
Sets the passphrase for the identity keystore.
Sets the identity keystore type to JKS.
Sets the name and location of the trust keystore file, Trust.jks.
Sets the passphrase for the trust keystore.
Sets the trust keystore type to JKS.
Saves and activates the new keystore configuration, then disconnects from the Managed Server instance.

Example 29-1 Configuring Custom Identity and Trust Keystores

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
edit()
startEdit()
cd ('Servers/myserver')
 
cmo.setKeyStores('CustomIdentityAndCustomTrust')
cmo.setCustomIdentityKeyStoreFileName('/path/keystores/Identity.jks')  
cmo.setCustomIdentityKeyStorePassPhrase('passphrase') 
cmo.setCustomIdentityKeyStoreType('JKS')
cmo.setCustomTrustKeyStoreFileName('/path/keystores/Trust.jks')  
cmo.setCustomTrustKeyStorePassPhrase('passphrase') 
cmo.setCustomTrustKeyStoreType('JKS')
 
 
save()
activate()
disconnect()

Viewing Keystore Contents

Use the keytool command to view the contents of a keystore.

Use the following keytool command syntax, where keystore represents the name of the keystore you created:

keytool -list -v -keystore keystore

When you enter the preceding command, you are prompted for the keystore password. For example, the following command lists the contents of keystore.jks:

prompt> keytool -list -v -keystore keystore.jks
Enter keystore password:

Alias name: rootcacert
Creation date: Sep 13, 2010
Entry type: trustedCertEntry
 
Owner: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB
Issuer: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB
Serial number: c47f4774c2ef014c
Valid from: Fri Jan 09 10:27:18 GMT 2009 until: Mon May 26 11:27:18 BST 2036
Certificate fingerprints:
MD5: E9:24:39:56:DE:34:44:DB:46:93:45:93:8E:82:66:AC
SHA1: 17:39:92:C0:43:9B:28:F3:C2:54:55:9B:5E:97:CA:EE:71:5D:9C:26
Signature algorithm name: SHA1withRSA
Version: 3
 
Extensions:
 
#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 67 57 BA 54 BB 9B C0 38 9A 71 AA 28 82 23 4B 08 gW.T...8.q.(.#K.
0010: 72 B9 FC C1 r...
]
]
 
#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:true
PathLen:2147483647
]
 
#3: ObjectId: 2.5.29.35 Criticality=false
 
[CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB]
SerialNumber: [ c47f4774 c2ef014c]
]
 
*******************************************
*******************************************
 
Alias name: server_cert
Creation date: Sep 13, 2010
Entry type: PrivateKeyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=server.avitek.com, OU=Support, O=Avitek, L=Reading, ST=Berkshire,
C=GB
Issuer: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB
Serial number: e
Valid from: Mon Sep 13 14:02:00 BST 2010 until: Sat Sep 22 14:02:00 BST 2012
Certificate fingerprints:
MD5: CB:B8:07:32:22:B5:76:78:44:BB:94:D2:CE:EF:A3:CA
SHA1: 1E:3E:C6:BC:17:EB:43:50:19:01:0B:11:50:D8:23:60:21:B2:57:3E
Signature algorithm name: MD5withRSA
Version: 1
Certificate[2]:
Owner: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB
Issuer: CN=SSL Training CA, OU=Support, O=Avitek, L=Readin g, ST=Berkshire, C=GB
Serial number: c47f4774c2ef014c
Valid from: Fri Jan 09 10:27:18 GMT 2009 until: Mon May 26 11:27:18 BST 2036
Certificate fingerprints:
MD5: E9:24:39:56:DE:34:44:DB:46:93:45:93:8E:82:66:AC
SHA1: 17:39:92:C0:43:9B:28:F3:C2:54:55:9B:5E:97:CA:EE:71:5D:9C:26
Signature algorithm name: SHA1withRSA
Version: 3
 
Extensions:
 
#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 67 57 BA 54 BB 9B C0 38 9A 71 AA 28 82 23 4B 08 gW.T...8.q.(.#K.
0010: 72 B9 FC C1 r...
]
]
 
#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:true
PathLen:2147483647
]
 
#3: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 67 57 BA 54 BB 9B C0 38 9A 71 AA 28 82 23 4B 08 gW.T...8.q.(.#K.
0010: 72 B9 FC C1 r...
]
 
[CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB]
SerialNumber: [ c47f4774 c2ef014c]
]
 
*******************************************
*******************************************

Setting Certificate Expiry Notifications

You can set reminders to notify you when your SSL certificates are about to expire. Reminders appear in the Security Warnings Report in the Administration Console.

To set a certificate expiry notification:

Start the Administration Console, if necessary.
On the home page, click Configure Security Warnings under Security Validation.
Make sure at least one of Check Identity Certificates or Check Trust Certificates is enabled.
In the Number of days before expiration for warnings field, enter a number (in days) to specify how far ahead of the certificate's expiration should the Security Warnings Report start warning you.
By default, WebLogic Server checks that no certificates are expiring within the next 30 days.
In the Number of days between certificates checking field, enter a number (in days) to specify how often WebLogic Server should check if the certificates are set to expire.
By default, WebLogic Server checks daily if certificates are about to expire.
Click Save.

Replacing Expiring Certificates

You must replace an expiring certificate before it actually expires to avoid or reduce application downtime.

You can set a notification to remind you prior to its expiration. See Setting Certificate Expiry Notifications.

To replace a certificate, complete the following steps:

Open a command window, change to the DOMAIN_HOME/bin directory, and run the setDomainEnv script.
Change to the directory that contains the identity keystore that stores the certificate needing to be replaced.
Generate a CSR, as explained in Generating a Certificate Signing Request, using the same private key alias specified when you created the keystore for which the current expiring certificate was issued.
Submit the CSR to the CA that issued the original certificate. 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 3 and 4 are not required if the CA already maintains the certificate request in a repository. In that case, simply ask the CA to issue a new certificate.
Import the newly issued certificate into the identity keystore using the alias of the private key.
If the new certificate is 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 identity certificate.

Creating a Keystore: An Example

Learn how to use the keytool utility for creating a keystore and storing keys and certificates in it.

Note that this section shows only how to create one keystore. In a production environment, Oracle recommends that you have two keystores: one for trust, and another for identity, as explained in Using Separate Keystores for Identity and Trust. For complete details about each of the keytool command options shown in this section, see "keytool — Key and Certificate Management Tool" at the following locations:

UNIX:

http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html

Windows:

http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html

To create a keystore and populate it with private keys and certificates, complete the following steps:

Create a directory to hold the keystore; for example: ORACLE_HOME/keystores.
Run the following script, which sets the domain-wide environment for starting and running WebLogic Server instances:
```
DOMAIN_HOME/bin/setDomainEnv
```
In the preceding path, DOMAIN_HOME represents the WebLogic domain root directory.
Change to the directory to hold the keystore, which you created in Step 1.
Create the keystore using the following keytool command syntax. This command also creates a key pair (a public key and associated private key) and an alias for the private key.
```
keytool -genkeypair -alias alias -keyalg RSA -keysize 1024 -dname dn -keystore keystore
```
In the preceding command syntax:
- alias represents the private key alias.
- dn represents the X.500 Distinguished Name associated with the private key alias.
- keystore represents the name of the keystore being created.
For example:
```
prompt> keytool -genkeypair -alias server_cert -keyalg RSA -keysize 1024
-dname "CN=server.avitek.com,OU=Support,O=Avitek,L=Reading,ST=Berkshire,C=GB"
-keystore keystore.jks
```
Note the following in the preceding example:
- server.avitek.com represents the WebLogic Server host and DNS domain name.
- Although the keytool command includes the -storepass and -keypass options for specifying the keystore and private key passwords, respectively, Oracle recommends that you avoid using these command-line options. When you enter a keytool command that requires one or more passwords, but you omit the command-line options for passing them, you are subsequently prompted to enter them. However, unlike passwords passed in command-line options, passwords entered in response to a prompt are not displayed in the command window and are not captured in any log.
- Make note of the private key alias and passwords you specify, and be sure to record passwords only in a safe location.
Make a backup copy of the keystore created in Step 4.
Create a Certificate Signing Request (CSR) using the following keytool command syntax:
```
keytool -certreq -v -alias alias -file certreq_file -keystore keystore
```
In the preceding command syntax:
- alias represents the private key alias specified in Step 4.
- certreq_file represents the name of the file that contains the CSR.
- keystore represents the keystore created in Step 4.
Note that when you create a CSR using the preceding command, you are prompted to enter the passwords for the keystore and the private key.

For example, the following command creates a CSR in the file server.csr:
```
prompt> keytool -certreq -v -alias server_cert -file server.csr -keystore keystore.jks
```
Submit the CSR file to a certificate authority (CA) of your choice. The CA returns:
- A digital certificate for WebLogic Server. This certificate is signed by the CA and is often referred to simply as the server certificate.
- The public certificate of the CA that signed your server certificate.
- Optionally, one or more intermediate CA certificates. For example, if the CA that signed your certificate is an intermediate CA, you might also receive the public certificate of the intermediate CA that signed your CA's certificate. (If your CA's certificate was signed by a root CA, you might also receive the root certificate.)
In the directory you created for your keystore, save the server certificate, and also the CA certificates, in individual files. For example, the server certificate can be saved as server.pem, and the CA certificate as rootCA.pem.

If you have an intermediate CA who also returns other intermediate certificates, save them also in your keystore directory using names such as intermediateCA2.pem, intermediateCA3.pem, and so on, to properly establish the certificate path in a way that indicates the correct sequence of that path.
Import the CA certificate, including any additional intermediate certificates and the root certificate if available, into your keystore using the following keytool command syntax:
```
keytool -importcert -v -noprompt -trustcacerts -alias alias -file rootca_file -keystore keystore
```
In the preceding syntax:
- alias represents the alias of the root CA certificate.
- rootca_file represents the name of the file that contains the root CA certificate.
- keystore represents the name of your keystore.
For example, the following command imports the root CA certificate in file rootCA.pem into the keystore, assigning it the alias rootcacert:
```
prompt> keytool -importcert -v -noprompt -trustcacerts -alias rootcacert -file rootCA.pem -keystore keystore.jks
Enter keystore password:
Certificate was added to keystore
Storing keystore.jks
```
Note:

If your CA returns a certificate chain, make sure you import the certificates in the proper sequence, as explained in Importing Certificates into the Trust and Identity Keystores.
Import the server certificate into your keystore using the following keytool command syntax:
```
keytool -importcert -v -alias alias -file servercert_file -keystore keystore
```
In the preceding syntax:
- alias represents the alias of the server certificate, which must be the same as the private key alias assigned in Step 4.)
- servercert_file represents the name of the file that contains the server certificate.
- keystore represents the name of your keystore.
For example, the following command imports the server certificate server.pem into the keystore, using the alias (server_cert) assigned in Step 4:
```
prompt> keytool -importcert -v -alias server_cert -file server.pem -keystore keystore.jks
Enter keystore password:
Certificate reply was installed in keystore[Storing keystore.jks
]
```
To view the contents of the keystore, use the following keytool command syntax, where keystore represents the name of your keystore:
```
keytool -list -v -keystore keystore
```

Supported Formats for Identity and Trust Certificates

The PEM (Privacy Enhanced Mail) format is the preferred format for private keys, digital certificates, and trusted certificate authority (CA) certificates. The preferred keystore format is JKS.

A .pem format file begins with this line:

----BEGIN CERTIFICATE----

and ends with this line:

----END CERTIFICATE----

A .pem format file supports multiple digital certificates (for example, a certificate chain can be included). The order of certificates within the file is important. The server's digital certificate should be the first digital certificate in the file, followed by the issuer certificate, and so on. Each certificate in the chain is followed by its issuer certificate. If the last certificate in the chain is the self-signed (self-issued) root certificate of the chain, the chain is considered complete. Note that the chain does not have to be complete.

When using the deprecated file-based private keys, digital certificates, and trusted CA certificates, WebLogic Server can use digital certificates in either PEM or distinguished encoding rules (DER) format.

A .der format file contains binary data for a single certificate. Thus, a .der file can be used only for a single certificate, while a .pem file can be used for multiple certificates.

Microsoft is often used as a CA. Microsoft issues trusted CA certificates in p7b format, which must be converted to PEM before they can be used with WebLogic Server. See Converting a Microsoft p7b Format to PEM Format.

Private key files (meaning private keys not stored in a keystore) must be in PKCS#5/PKCS#8 PEM format.

You can still use private keys and digital certificates used with other versions of WebLogic Server with this version of WebLogic Server. Convert the private key and digital certificate from distinguished encoding rules (DER) format to privacy-enhanced mail (PEM) format. See the description of the der2pem utility in "Using the WebLogic Server Java Utilities" in Command Reference for Oracle WebLogic Server.

After converting the files, ensure the digital certificate file has the -----BEGIN CERTIFICATE----- header and the -----END CERTIFICATE----- footer. Otherwise, the digital certificate will not work.

Note:

OpenSSL can add a header to the PEM certificate it generates. In order to use such certificates with WebLogic Server, everything in front of "-----BEGIN CERTIFICATE-----" should be removed from the certificate, which you can do with a text editor.

Obtaining a Digital Certificate for a Web Browser

The digital certification you receive for a web browser contains public information, including your name and public key, and additional information you would like authenticated by a third party, such as your E-mail address. You are required to present the digital certificate when authentication is requested.

Low-security browser certificates are easy to acquire and can be done from within the Web browser, usually by selecting the Security menu item in Options or Preferences. Go to the Personal Certificates item and ask to obtain a new digital certificate. You will be asked for some information about yourself.

As part of the process of acquiring a digital certificate, the Web browser generates a public-private key pair. The private key should remain secret. It is stored on the local file system and should never leave the Web browser's machine, to ensure that the process of acquiring a digital certificate is itself safe. With some browsers, the private key can be encrypted using a password, which is not stored. When you encrypt your private key, you will be asked by the Web browser for your password at least once per session.

Note:

Digital certificates obtained from Web browsers do not work with other types of Web browsers or on different versions of the same Web browser.