![]() ![]() ![]() ![]() ![]() ![]() ![]() |
This following sections describe how to configure identity and trust for WebLogic Server:
Before performing the steps in this chapter, review the Identity and Trust section in Understanding WebLogic Security.
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 and digitally signed with the certificate authority’s digital certificate. Well-know certificate authorities include Verisign and Entrust.net. The trusted certificate authority (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 certificate authority and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the certificate authority 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.
To create identity and trust for a server:
keytool
utility, or a reputable vendor such as Entrust or Verisign. You can also use the digital certificates, private keys, and trusted CA certificates provided by the WebLogic Server kit. The demonstration digital certificates, private keys, and trusted CA certificates should be used in a development environment only.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. |
The remaining sections describe these steps.
The PEM (Privacy Enhanced Mail) format is the preferred format for private keys, digital certificates, and trusted certificate authorities (CAs). The preferred keystore format is the JKS (Java KeyStore) format.
A.pem
format file begins with this line:
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 CAs, 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 certificate authority. 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 WebLogic Server Command Reference.
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. |
Servers need a private key, a digital certificate containing the matching public key, and a certificate for at least one trusted certificate authority. WebLogic Server supports private keys, digital certificates, and trusted CA certificates from the following sources:
WL_HOME\
server\lib
directory and the JAVA_HOME
\jre\lib\security
directory.The demonstration digital certificates, private keys, and trusted CA certificates should be used in a development environment only.
keytool
utility can also be used to generate a private key, a self-signed digital certificate for WebLogic Server, and a Certificate Signing Request (CSR).
For more information about Sun's keytoo
l utility, see the keytool-Key and Certificate Management Tool description at
http://java.sun.com/j2se/1.5.0/docs/tooldocs/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. |
Note: | The Certificate Request Generator servlet is deprecated. Use the keytool utility from Sun Microsystems in place of the Certificate Request Generator servlet. For more information about keytool , see Common Keytool Commands. |
Table 10-1 lists keytool
commands you use when creating and using JKS keystores with WebLogic Server.
Note: | The keytool utility is a product of Sun Microsystems. Therefore, BEA Systems does not provide complete documentation on the utility. For more information, see the keytool-Key and Certificate Management Tool description at
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html. |
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. |
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 have the host name of the machine on which they were generated as the value for its common name field (cn
) by default only. 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.
For information about the CertGen
utility’s syntax and arguments, see
CertGen in the WebLogic Server Command Reference.
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 WebLogic Server Command Reference.
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. |
Note: | 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. |
Many companies act as their own certificate authority. To use those trusted CA certificates with WebLogic Server:
der2pem
utility to convert them.
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:
filename
.p7b
) you want to convert. Double-click on the file to display a Certificates window.Base-64 encoded X.509 (.CER)
option. Then click Next. (Base-64 encoded is the PEM format.)File name:
field, enter a name for the converted digital certificate; then click Nest.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. |
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. |
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. |
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:
You cannot have blank lines between digital certificates.
Listing 10-1 shows a sample certificate chain.
-----BEGIN CERTIFICATE-----
MIICyzCCAjSgAwIBAgIBLDANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMloXDTA2MTAxNTIwMDIxMlowgZ8xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MRkwFwYDVQQDExB3ZWJsb2dpYy5iZWEuY29tMR4wHAYJKoZIhvcNAQkBFg9zdXBwb3J0QGJlYS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMJX8nKUgsFej8pEu/1IVcHUkwY0c2JbBzOryu3sce4QjX+rGxiCjoPm2MY=yts2BvonuJ6CztdZf8B/LBEWCz+qRrtdFn9mKSZWGvrAkmMPz2RhXEOThpoRo5kZz2FQ9XF/PxIJXTYCM7yooRBwXoKYjquRwiZNtUiU9kYi6Z3prAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAh2eqQGxEMUnNTwEUD
0tBq+7YuAkjecEocGXvi2G4YSoWVLgnVzJoJuds3c35KE6sxBe1luJQuQkE9SzALG/6lDIJ5ctPsHFmZzZxY7scLl6hWj5ON8oN2YTh5Jo/ryqjvnZvqiNIWe/gqr2GLIkajC0mz4un1LiYORPig3fBMH0=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIC+jCCAmOgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBtjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xFTATBgNVBAoTDEJFQSBXZWJMb2dpYzERMA8GA1UECxMIU2VjdXJpdHkxLzAtBgNVBAMTJkRlbW8gQ2VydGlmaWNhdGUgQXV0aG9yaXR5IENvbnN0cmFpbnRzMR8wHQYJKoZIhvcNAQkBFhBzZWN1cml0eUBiZWEuY29tMB4XDTAyMTEwMTIwMDIxMVoXDTA2MTAxNjIwMDIxMVowgbYxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJhbmNpc2NvMRUwEwYDVQQKEwxCRUEgV2ViTG9naWMxETAPBgNVBAsTCFNlY3VyaXR5MS8wLQYDVQQDEyZEZW1vIENlcnRpZmljYXRlIEF1dGhvcml0eSBDb25zdHJhaW50czEfMB0GCSqGSIb3DQEJARYQc2VjdXJpdHlAYmVhLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3ynD8l5JfLob4g6d94dNtI0Eep6QNl9bblmswnrjIYz1BVjjRjNVal9fRs+8jvm85kIWlerKzIMJgiNsj50WlXzNX6orszggSsW15pqV0aYE9Re9K
CNNnORlsLjmRhuVxg9rJFEtjHMjrSYr2IDFhcdwPgIt0meWEVnKNObSFYcCAwEAAaMWMBQwEgYDVR0TAQH/BAgwBgEB/wIBATANBgkqhkiG9w0BAQQFAAOBgQBS+0oqWxGyqbZO028zf9tQT2RKojfuwywrDoGW96Un5IqpFnBHIu5atliJo3OUpiH18KkwLN8DVP/3t3K3O3kXdIuLbqAL0i5xyBlAhr7gE5eVhIyeMg7ETBPLyGO2BF13Y24LlsO+MX9jW7fxMraPN608QeJXkZw0E0cGwrw2AQ==
-----END CERTIFICATE-----
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. The keystores can be configured through the WebLogic Server Administration Console or specified on the command line. Use the Configuration > Keystore page in the WebLogic Server Administration Console to configure identity and trust keystores for WebLogic Server. See Configuring Keystores in the Administration Console online help.
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.
When you configure SSL, you have to decide how identity and trust will be stored. Although one keystore can be used for both identity and trust, BEA 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:
In general, systems within a domain have the same trust rules (use the same set of trusted CAs), while 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 rules.
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.
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:
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 WebLogic Server Command Reference.keytool
utility. Use the keytool
utility to generate a private key/digital certificate pair and then import the signed private key into the keystore. For more information, see How WebLogic Server Locates Trust. While you can use the keytool
utility to generate new private keys 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. |
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.
WebLogic Server uses the following algorithm when it loads its trusted CA certificates:
-Dweblogic.security.SSL.trustedCAkeystore
command-line argument, load the trusted CA certificates from that keystore.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.config.xml
), load trusted CA certificates from that file (this is only for compatibility with 6.x SSL configurations).WL_HOME\server\lib\cacerts
keystore.
By default, WebLogic Server is configured with two keystores:
DemoIdentity.jks
—Contains a demonstration private key for WebLogic Server. This keystore contains the identity for WebLogic Server.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.
These keystores are located in the WL_HOME
\server\lib
directory. 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.
To configure keystores for use in a production environment:
You can also use the WebLogic Scripting Tool or Java Management Extensions (JMX) APIs to create a new security configuration. For more information see the WebLogic Scripting Tool and Developing Custom Management Utilities with JMX manuals.
![]() ![]() ![]() |