11 Configuring Identity and Trust

This chapter describes how to configure identity and trust for WebLogic Server.

This chapter includes the following sections:

Before performing the steps in this chapter, review "Identity and Trust" in Understanding Security for Oracle WebLogic Server.

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 for at least one trusted certificate authority (CA). WebLogic Server supports private keys, digital certificates, and trusted CA certificates from the following sources:

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

  • The private key and self-signed digital certificate for WebLogic Server that are created by the keytool utility. Note the following:

    • After you create the private key and self-signed certificate, use keytool to generate a Certificate Signing Request (CSR). Submit the CSR to a CA to obtain a digital certificate for WebLogic Server.

    • Use the keytool utility to update the self-signed digital certificate with a new digital certificate.

    • You can also use the keytool utility to obtain trust and identity when using WebLogic Server in a production environment.

    For more information, see Using the Keytool Utility.

  • The digital certificates and private keys generated by the CertGen utility. However, these should be used only for demonstration or testing purposes in a development environment, not in a production environment. 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.) For more information about using the CertGen utility to obtain private keys and digital certificates, see Using the CertGen Utility.

    Note:

    The Certificate Request Generator servlet is deprecated. Use the keytool utility instead, described in Using the Keytool Utility.

Supported Formats for Identity and Trust

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 (Java KeyStore).

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. For more information, 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. For more information, 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.

Identity and Trust Keystores

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 (private key/digital certificate pairs) 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.

How WebLogic Server Locates Trust

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

  1. If the keystore is specified by the -Dweblogic.security.SSL.trustedCAkeystore command-line argument, load the trusted CA certificates from that keystore.

  2. Else if the keystore is specified in the configuration file (config.xml), load 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 and the JDK cacerts keystores.

  3. Else if the trusted CA file is specified in the configuration file (config.xml), load trusted CA certificates from that file (this is only for compatibility with 6.x SSL configurations).

  4. Else load trusted CA certificates from WL_HOME\server\lib\cacerts keystore.

Configuring Identity and Trust: Main Steps

To create identity and trust for a server:

  1. Obtain digital certificates, private keys, and trusted CA certificates. See Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authority Certificates .

  2. Create the identity and trust keystores. See Tools and Utilities for Creating Keystores and Loading Private Keys and Certificates .

  3. Store the private keys, digital certificates, and trusted CA certificates in the keystores. See Storing Private Keys, Digital Certificates, and Trusted Certificate Authority Certificates .

    Note:

    The preferred keystore format is JKS (Java 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.

  4. Configure the keystores for WebLogic Server. See Configuring Identity and Trust Keystores for WebLogic Server.

Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authority
Certificates

You have multiple choices for obtaining private keys, digital certificates, and trusted CA certificates for your WebLogic Server environment. When choosing, note the following considerations:

  • You can obtain keys, certificates, and trusted CA artifacts from the CertGen utility, the keytool utility, or a reputable vendor such as Entrust or Symantec Corporation. However, for a production environment, you should obtain private keys and digital certificates only from a reputable certificate authority such as Entrust or Symantec Corporation.

  • You can also use the digital certificates, private keys, and trusted CA certificates provided by WebLogic Server. However, these should be used in a development environment only.

This section describes the tools and methods for obtaining keys, certificates, and trusted CA certificates. The following topics are included:

Using the Keytool Utility

Keytool is a key and certificate management utility. It allows users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.

For an example of using keytool to obtain key pairs, a self-signed server certificate, and a trusted CA certificate, see Creating a Keystore: An Example. For complete details about keytool, see "keytool — Key and Certificate Management Tool" at http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html

Note:

When you use the keytool utility, the default key pair generation algorithm is Digital Signature Algorithm (DSA). WebLogic Server does not support DSA. Specify another key pair generation and signature algorithm when using WebLogic Server.

Table 11-1 lists keytool commands commonly used for creating and using JKS keystores with WebLogic Server. In this table, brackets surrounding an option signify that the user is prompted for the value(s) if the option is not specified on the command line.

Caution:

Although the keytool command includes options for specifying passwords, which are described in Table 11-1, you should never include unencrypted passwords in command lines. Instead, you should allow keytool to prompt you for any required passwords after you enter the command, as in the following example. User input is shown in bold.

C:\DOMAIN_NAME>keytool -genkeypair -keystore MyKeyStore
Enter keystore password:
Re-enter new password:

Unlike passwords that are specified in command-line options, passwords entered in response to prompts are not echoed in the command window, and are not captured in logs, which allows for secure password input.

Table 11-1 Commonly Used keytool Commands

Command Description
keytool -genkeypair -keystore keystorename

-storepass keystorepassword

Generates a key pair (a public key and associated private key) and self-signed digital certificate in a keystore. If the keystore does not exist, it is created.

keytool -importcert -alias aliasforprivatekey 
-file privatekeyfilename.pem 
-keyfilepass privatekeypassword 
-keystore keystorename -storepass keystorepassword

Updates the self-signed digital certificate with one signed by a trusted CA.

keytool -importcert -alias rootCA 
-trustcacerts -file RootCA.pem 
-keystore trust.jks -storepass keystorepassword
keytool -importcert -alias intermediate 
-trustcacerts -file Intermediate.pem 
-keystore keystorename -storepass keystorepassword

Creates a custom keystore to be used for holding an intermediate CA certificate.

  • The first keytool command creates the keystore, trust.jks, which holds the root CA certificate.

  • The second keytool command imports the intermediate CA certificate into trust.jks.

This enables WebLogic Server's SSL implementation to transmit the intermediate certificate with the server's public certificate to the client during the SSL handshake.

keytool -importcert -alias aliasfortrustedca 
-trustcacerts -file trustedcafilename.pem 
-keystore keystorename -storepass keystorepassword

Loads a trusted CA certificate into a keystore. If the keystore does not exist, it is created.

keytool -certreq -alias alias 
-sigalg sigalg 
-file certreq_file 
-keyfilepass privatekeypassword 
-storetype keystoretype 
-keystore keystorename 
-storepass keystorepassword 

Generates a Certificate Signing Request (CSR), using the PKCS#10 format, and a self-signed certificate with a private key.

Stores the CSR in the specified certreq_file, and the certificate/private key pair as a key entry in the specified keystore under the specified alias.

keytool -list -keystore keystorename 

Displays the contents of the keystore.

keytool -delete -keystore keystorename
-storepass keystorepassword
-alias privatekeyalias

Deletes the entry identified by the specified alias from the keystore.

keytool -help

Provides online help for keytool.


Using the CertGen Utility

Note:

The CertGen utility generates digital certificates and private keys that should only be used for demonstration or testing purposes, not in a production environment. For important information about limitations on its use, see Limitation on CertGen Usage.

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.

The CertGen utility generates public certificate and private key files in PEM and DER formats. On Windows, double-click .der files to view the details of the generated digital certificate. The .pem files can be used when you boot WebLogic Server or use the digital certificates with a client.

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 need not specify CA files on the command line. Alternatively, you can specify CA files on the command line.

Command Syntax and Examples

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

For an example that generates a certificate and private key using the CertGen utility, and then creates a keystore and stores a private key using the ImportPrivateKey utility, see "ImportPrivateKey" in the Command Reference for Oracle WebLogic Server.

Note:

If you do not explicitly specify a hostname with the -cn option, CertGen uses the JDK InetAddress.getHostname() method to get the hostname that it puts in the Subject common name. The getHostName() method works differently on different platforms. It returns a fully qualified domain name (FQDN) on some platforms (for example, Solaris) and a short host name on other platforms (for example, Windows NT). On Solaris, 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 by default host name verification is enabled), you need to ensure that the host name specified in the URL matches the Subject common name in the server certificate. Otherwise, connections will 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 will 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
      
  • To start 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 a production environment.

Using Your Own Certificate Authority

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

  1. Ensure the trusted CA certificates are in PEM format.

  2. Create a trust keystore and store the trusted CA certificate in it. For more information, see Storing Private Keys, Digital Certificates, and Trusted Certificate Authority Certificates .

  3. Configure WebLogic Server to use the trust keystore. For more information, see Configuring Keystores for Production.

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:

  1. In Windows Explorer, select the file (filename.p7b) you want to convert. Double-click on the file to display a Certificates window.

  2. In the left pane of the Certificates window, expand the file.

  3. Expand the Certificates folder to display a list of certificates.

  4. Select a certificate to convert to PEM format. Right-click on the certificate, then choose All Tasks > Export to display the Certificate Export Wizard.

  5. In the wizard, click Next.

  6. Select the Base-64 encoded X.509 (.CER) option. Then click Next. (Base-64 encoded is the PEM format.)

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

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

Obtaining a Digital Certificate for a Web Browser

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.

The digital certificate you receive 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. Later you will present the digital certificate when authentication is requested.

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.

Using Certificate Chains (Deprecated)

Note:

The use of file-based certificate chains is deprecated. Now the whole certificate chain is imported into a keystore. The steps in this section are provided for the purpose of backward compatibility only.

To use certificate chains with WebLogic Server:

  1. Ensure that all the digital certificates are in PEM format. If they are in DER format, you can convert them using the "der2pem" utility. If you are using a digital certificate issued by Microsoft, see Converting a Microsoft p7b Format to PEM Format. You can use the steps in the section to convert other types of digital certificates. Save the digital certificate in Base 64 format.

  2. Open a text editor and include all the digital certificate files into a single file. The order is important. The server digital certificate should be the first digital certificate in the file. The issuer of that digital certificate should be the next in the file and so on until you get to the self-signed root certificate authority (CA) certificate. This digital certificate should be the last certificate in the file.

    You cannot have blank lines between digital certificates.

  3. Specify the file in the Server Certificate File Name field on the Configuration > SSL page in the WebLogic Server Administration Console.

Example 11-1 shows a sample certificate chain.

Example 11-1 Sample File with Certificate Chain

-----BEGIN CERTIFICATE-----
MIICyzCCAjSgAwIBAgIBLDANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUB
gNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJk
RlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4
XDTAyMTEwMTIwMDIxMloXDTA2MTAxNTIwMDIxMlowgZ8xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYD
VQQHEw1TYW4gRnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MRkwFwYDVQQDExB3Z
WJsb2dpYy5iZWEuY29tMR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0QGJlYS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAo
GBAMJX8nKUgsFej8pEu/1IVcHUkwY0c2JbBzOryu3sce4QjX+rGxiCjoPm2MY=yts2BvonuJ6CztdZf8B/LBEWCz+qRrtdFn9
mKSZWGvrAkmMPz2RhXEOThpoRo5kZz2FQ9XF/PxIJXTYCM7yooRBwXoKYjquRwiZNtUiU9kYi6Z3prAgMBAAEwDQYJKoZIhvc
NAQEEBQADgYEAh2eqQGxEMUnNTwEUD

0tBq+7YuAkjecEocGXvi2G4YSoWVLgnVzJoJuds3c35KE6sxBe1luJQuQkE9SzALG/6lDIJ5ctPsHFmZzZxY7scLl6hWj5ON8
oN2YTh5Jo/ryqjvnZvqiNIWe/gqr2GLIkajC0mz4un1LiYORPig3fBMH0=

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

MIIC+jCCAmOgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUB
gNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJk
RlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4
XDTAyMTEwMTIwMDIxMVoXDTA2MTAxNjIwMDIxMVowgbYxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYD
VQQHEw1TYW4gRnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MS8wLQYDVQQDEyZEZ
W1vIENlcnRpZmljYXRlIEF1dGhvcml0eSBDb25zdHJhaW50czEfMB0GCSqGSIb3DQEJARYQc2VjdXJpdHlAYmVhLmNvbTCBnz
ANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3ynD8l5JfLob4g6d94dNtI0Eep6QNl9bblmswnrjIYz1BVjjRjNVal9fRs+8jvm
85kIWlerKzIMJgiNsj50WlXzNX6orszggSsW15pqV0aYE9Re9K

CNNnORlsLjmRhuVxg9rJFEtjHMjrSYr2IDFhcdwPgIt0meWEVnKNObSFYcCAwEAAaMWMBQwEgYDVR0TAQH/BAgwBgEB/wIBAT
ANBgkqhkiG9w0BAQQFAAOBgQBS+0oqWxGyqbZO028zf9tQT2RKojfuwywrDoGW96Un5IqpFnBHIu5atliJo3OUpiH18KkwLN8
DVP/3t3K3O3kXdIuLbqAL0i5xyBlAhr7gE5eVhIyeMg7ETBPLyGO2BF13Y24LlsO+MX9jW7fxMraPN608QeJXkZw0E0cGwrw2AQ==

-----END CERTIFICATE-----

Storing Private Keys, Digital Certificates, and Trusted Certificate Authority
Certificates

Once you have obtained private keys, digital certificates, and trusted CA certificates, you need to store them so that WebLogic Server can use them to find and verify identity. Private keys, their associated digital certificates, and trusted CA certificates are stored in keystores. Then you need to configure those keystores with WebLogic Server.

This section contains the following topics:

For a step-by-step example of using the keytool utility to create a keystore and store keys and certificates in it, see Creating a Keystore: An Example.

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. However, do not use the demonstration keystores in a production environment. Because the digital certificates and trusted CA certificates in the demonstration keystores are signed by a WebLogic Server demonstration certificate authority, a WebLogic Server installation using the demonstration keystores will trust any WebLogic Server installation that also uses the demonstration keystores. You want to create a secure environment where only your installations trust each other.

Interoperating With Keystores From Prior Versions

If you are using WebLogic Server version 12.1.2 together with a previous version of WebLogic Server, be aware that the demo trust keystore of the previous versions does not contain the demo CA certificate used by version 12.1.2. Therefore, if a 12.1.2 instance of WebLogic Server sends its public certificate to an instance of WebLogic Server running a prior version, that public certificate will not automatically be trusted.

For interoperability with prior releases, you can use either of the following methods:

  • Use the system property -Dsecurity.use.interopCA=true to generate interoperable demo certificates signed by the previous demo CA certificate.

  • On the 12.1.2 instance of WebLogic Server, use the CertGen utility with the -cacert -cakey arguments to generate demo certificates signed by the previous demo CA certificate. Then, use ImportPrivateKey to import them into DemoIdentity.jks, as shown in the following example:

    java utils.CertGen 
        -certfile <cert_file>
        -keyfile <private_key_file>
        -keyfilepass DemoIdentityPassPhrase
        -cacert $WL_HOME/server/lib/CertGenInteropCA.der
        -cakey $WL_HOME/server/lib/CertGenInteropCAKey.der
        -cakeypass password
     
     
    java utils.ImportPrivateKey
        -certfile <cert_file>
        -keyfile <private_key_file>
        -keyfilepass DemoIdentityPassPhrase
        -keystore DemoIdentity.jks
        -storepass DemoIdentityKeyStorePassPhrase
        -alias DemoIdentity
        -keypass DemoIdentityPassPhrase
    

Tools and Utilities for Creating Keystores and Loading Private Keys
and Certificates

A keystore is for the secure storage and management of private keys/digital certificate pairs and trusted CA certificates. Use the following mechanisms to create a keystore and load private keys and trusted CA certificates into the keystore:

  • The WebLogic ImportPrivateKey utility. The ImportPrivateKey utility allows you to take private key and digital certificate files and load them into a keystore. For more information, see "ImportPrivateKey" in the Command Reference for Oracle WebLogic Server.

  • The keytool utility. Use the keytool utility to generate a key pair (a public key and associated private key) and a self-signed digital certificate and store them in the keystore. While you can use the keytool utility to generate new key pairs and digital certificates and add them to a keystore, the utility does not allow you to take an existing private key from a file and import it into the keystore. Instead, use the WebLogic ImportPrivateKey utility.

    Note:

    The keytool utility does allow you to import trusted CA certificates from a file into a keystore.

    For step-by-step instructions explaining how to use keytool to create a keystore, see Creating a Keystore: An Example.

  • Custom utilities. WebLogic Server can use keystores created with custom tools or utilities. How to create and use these utilities is outside the scope of this document.

All private key entries in a keystore are accessed by WebLogic Server via unique aliases. You specify the alias when loading the private key into the keystore. Aliases are case-insensitive: the aliases Hugo and hugo would refer to the same keystore entry. Aliases for private keys are specified in the Private Key Alias field on the Configuration > SSL page in the WebLogic Server Administration Console. 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.

All certificate authorities in a keystore identified as trusted by WebLogic Server are trusted.

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:

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

  2. Copy ORACLE_HOME/wlserver/server/lib/cacerts to the jre/lib/security directory of the WebLogic Server's JVM.

  3. Restart both WebLogic Server and the client.

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

Configuring Identity and Trust Keystores for WebLogic Server

This section includes the following topics:

Configuring Keystores for Production

After you have created the identity and trust keystores that you intend to use in a production environment, you must configure them with WebLogic Server. You can use any of the following methods to do this:

Configuring Keys and Certificates Stored in a File or JKS Keystore
Accessed by the WebLogic Keystore Provider

For the purpose of backward compatibility, private keys and trusted CA certificates can be stored in a file or in a JKS keystore accessed via the WebLogic Keystore provider. In addition, trusted CA certificates can be stored in a JKS keystore. Use the Configuration > SSL page of the WebLogic Server Administration Console to specify identity and trust options when using a file or a JKS keystore accessed via the WebLogic Keystore provider.

Creating a Keystore: An Example

This section shows an example of using 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 Identity and Trust Keystores. For complete details about each of the keytool command options shown in this section, see "keytool — Key and Certificate Management Tool" at http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html.

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

  1. Create a directory to hold the keystore; for example: ORACLE_HOME/keystores.

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

  3. Change to the directory to hold the keystore, which you created in Step 1.

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

  5. Make a backup copy of the keystore created in Step 4.

  6. 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:
    
    Keystore type: JKS
    Keystore provider: SUN
     
    Your keystore contains 1 entry
     
    Alias name: server_cert
    Creation date: Sep 13, 2010
    Entry type: PrivateKeyEntry
    Certificate chain length: 1
    Certificate[1]:
    Owner: CN=server.avitek.com, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB
    Issuer: CN=server.avitek.com, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB
    Serial number: 4c8e1ad5
    Valid from: Mon Sep 13 13:36:37 BST 2010 until: Sun Dec 12 12:36:37 GMT 2010
    Certificate fingerprints:
    MD5: 1A:4A:3B:42:7E:BD:94:65:67:0E:9B:02:28:90:D6:A8
    SHA1: C1:53:48:50:EB:F1:FD:A0:DC:28:9F:EF:3B:C8:FB:22:82:9F:8E:EE
    Signature algorithm name: SHA1with RSA
    Version: 3
     
     
    *******************************************
    *******************************************
    
  7. 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
    

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

  9. In the directory you created for your keystore, save the server certificate, and also the trusted root CA certificate, in individual files. For example, the server certificate can be saved as server.pem, and the root CA certificate as rootCA.pem.

    If the CA has multiple root certificates, save them also in your keystore directory using names such as rootCA2.pem, rootCA3.pem, and so on.

  10. Import each root CA certificate 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
    
  11. 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
    ]
    
  12. 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
    

    For example:

    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]
    ]
     
    *******************************************
    *******************************************
    

Using a Certificate Callback Handler to Validate End User Certificates

WebLogic Server provides a means to examine details about information passed by an end user issuing a request to determine whether authentication should succeed or fail. The details may include the end user's certificate, Subject, and IP address. This capability is provided by the weblogic.security.SSL.CertificateCallback interface, which you can implement to create a certificate callback handler. When configured with WebLogic Server, this callback handler is invoked automatically whenever a client request is received over a secure RMI connection; for example, one that uses the T3s or IIOPS protocols.

To configure a certificate callback handler so that it is in effect for all secure inbound RMI connections, you define it as a WebLogic Server system property that is passed in the server startup command.

The following topics describe how a certificate callback handler works and how to implement and configure one:

How End User Certificate Callback Handlers Work

When a client makes a secure RMI connection to a WebLogic Server instance that is configured with a certificate callback handler, WebLogic Server invokes the callback handler. The callback evaluates details about the end user that are contained in the connection request, then returns a boolean value indicating whether authentication is successful.

The CertificateCallback interface calls the validate method on an CertificateCallbackInfo instance, which contains methods to obtain the following information from the end user that is contained in the RMI connection request:

  • Client host name, IP address, and port

  • Client domain name

  • Destination host name, IP address, and port

  • Authenticated Subject

  • Client certificate

The callback implementation includes the logic that evaluates the client data that is obtained and returns true or false as follows:

  • If the callback returns true, authentication succeeds and the client connection to WebLogic Server is made.

  • If the callback returns false, a RemoteException is thrown containing the "Authentication denied" message.

Note:

If you use a certificate callback implementation in WebLogic Server, a callback is generated whenever a request is received over a secure port. As a result, using certificate callbacks may impose a performance overhead that should be taken into consideration.

Creating a Certificate Callback Implementation

The weblogic.security.SSL.CertificateCallback interface contains a single invocation on the validate method on a weblogic.security.SSL.CertificateCallbackInfo instance. The CertificateCallbackInfo instance contains methods to obtain details about the end user that are passed over the secure RMI connection.

You implement logic that evaluates the data that is returned and returns a true or false. The logic does not need to evaluate all data that is returned. Typically, only the certificate is evaluated; for example, obtaining the common name (cn) or distinguished name (dn).

For more information, see the following Javadoc in the Java API Reference for Oracle WebLogic Server:

Configuring the Certificate Callback with WebLogic Server

To configure the callback with WebLogic Server, specify the callback implementation as a system property in the WebLogic Server start command. The property should point to the callback implementation class that is on the server's classpath. For example, if the callback implementation class is MyCertificateCallback.java in the package com.mycompany.security, and MyCertificateCallback.class is in the server's classpath, the following command sets the callback implementation property in WebLogic Server:

java weblogic.Server -Dweblogic.security.SSL.CertificateCallback=com.mycompany.security.MyCertificateCallback

Note that if WebLogic Server is configured for one-way SSL, a client certificate is never sent to the server. Oracle recommends using certificate callbacks handlers only when WebLogic Server is configured for two-way SSL. For more information, see Chapter 12, "Configuring SSL".