Configuring Identity and Trust 11-7
11.4.1.2 Using the CertGen Utility
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_HOMEserverlib 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.
11.4.1.2.1 Command Syntax and Examples For information about the CertGen utilitys
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.
11.4.1.2.2 Limitation on CertGen Usage By default, WebLogic Server is installed and
configured with the DemoIdentity.jks keystore, which contains a demonstration public certificate and private key for WebLogic Server. This certificate and key are
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 Section 11.4.1.2.2, Limitation on CertGen
Usage.
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 etcnsswitch.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.
11-8 Securing Oracle WebLogic Server
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 Section 12.5, Using
Host Name Verification.
Configuring Identity and Trust 11-9
11.4.1.3 Using Your Own Certificate Authority
