Using Host Name Verification

30 Using Host Name Verification

Learn how to configure host name verification in Oracle WebLogic Server. A host name verifier ensures the host name in the URL to which the client connects matches the host name in the digital certificate that the server sends back as part of the SSL connection. A host name verifier is useful when an SSL client (for example, WebLogic Server acting as an SSL client) connects to an application server on a remote host. It helps to prevent man-in-the-middle attacks.

WebLogic Server includes two host name verifiers, and also provides the ability to create and use a custom host name verifier.

Note:

In releases prior to WebLogic Server 14c (14.1.1.0.0), the BEA host name verifier was also known as the default host name verifier. However, as of WebLogic Server release 14c (14.1.1.0.0), the default host name verifier is changed to the wildcard host name verifier.

This chapter includes the following sections:

Using the BEA Host Name Verifier

WebLogic Server provides two host name verifiers, the wildcard host name verfier and the BEA host name verifier. As of WebLogic Server 14c (14.1.1.0.0), the wildcard host name verifier is the default host name verifier and is configured by default.

If you are using any WebLogic Server host name verifier, host name verification passes if the host name in the certificate matches the local machine’s host name, and if the URL specifies localhost, 127.0.01, or the default IP address of the local machine.

As a function of the SSL handshake, WebLogic Server compares the common name in the SubjectDN in the SSL server's digital certificate with the host name of the SSL server used to accept the SSL connection. If these names do not match exactly, the SSL connection is dropped. The SSL client is the actual party that drops the SSL connection if the names do not match.

You can turn off host name verification or configure a custom host name verifier. Turning off host name verification leaves WebLogic Server vulnerable to man-in-the-middle attacks. Oracle recommends leaving host name verification on in production environments.

BEA host name verifier was the default host name verifier in the previous releases of WebLogic Server. To configure the BEA host name verifier, see Configuring the BEA Host Name Verifier.

Note:

If you are using the demo identity certificates in a multi-server domain, Managed Server instances will fail to boot if they are started using the fully-qualified DNS name of the Administration Server. For information about this limitation and suggested workarounds, see Limitation on CertGen Usage.

See the following topics in Oracle WebLogic Server Administration Console Online Help:

Configuring the BEA Host Name Verifier

The BEA host name verifier class name is weblogic.security.utils.SSLWLSHostnameVerifier.DefaultHostnameVerifier. To configure the BEA host name verifier, specify this class as a custom host name verifier in the Servers: Configuration: SSL page of the WebLogic Server Administration Console. See Configure a custom host name verifier in the Oracle WebLogic Server Administration Console Online Help.

Using the Wildcard Host Name Verifier

As of Oracle WebLogic Server 14c (14.1.1.0.0), the default WebLogic Server host name verifier is the wildcard host name verifier. The wildcard host name verifier is configured by default. No action is needed to use it.

In the previous releases of WebLogic Server, the BEA host name verifier was the default host name verifier. For more information about using and configuring the BEA host name verifier, see Using the BEA Host Name Verifier.

The wildcard host name verifier works the same as the BEA host name verifier; however, the wildcard host name verifier also accepts additional SSL session certificates. The wildcard host name verifier accepts the following additional SSL session certificates:

Certificates that contain the asterisk wildcard character (*) in the host name that is obtained from the certificate's Subject CommonName attribute (that is, the CN domain)
SubjectAlternativeName dnsName (SAN) certificates

This section contains the following topics:

How the Wildcard Host Name Verifier Works

If the host name in the SSL session certificate contains a wildcard character that meets the following criteria, the certificate is accepted by the wildcard host name verifier:

The host name contains at least two dot (.) characters.
The host name begins with an asterisk (*) and does not contain any additional asterisks.
When the asterisk (*) is stripped from the CN string, the remaining string must:
- Represent the domain.
- Include a leading dot (.) character.
- Be identical to the ending string of the incoming request domain.
- Not include an additional dot (.) character. (This prevents the wildcard from representing subdomains.

If the host name in the SSL session certificate does not exactly match the expected server name attribute, and the host name also cannot successfully be validated in accordance with the wildcard acceptance criteria, the wildcard host name verifier attempts to validate the SAN extensions.

The SAN extensions are obtained from the SSL session certificate. The SAN extension values are iterated using a case-insensitive match. For any iterated value, if the dnsName attribute in the certificate matches the request URL exactly or by wildcard comparison, host name verification succeeds.

Configuring the Wildcard Host Name Verifier

The wildcard host name verifier is configured by default, and is specified by the class name weblogic.security.utils.SSLWLSWildcardHostnameVerifier. If WebLogic Server uses a different host name verifier and if you want to restore to the default wildcard host name verifier, then specify this class as a custom host name verifier in the Servers: Configuration: SSL page of the WebLogic Server Administration Console. The wildcard host name verifier has no parameters with which it must be configured.

Using a Custom Host Name Verifier

When using a custom host name verifier, the class that implements the custom host name verifier must be specified in the CLASSPATH of WebLogic Server (when acting as an SSL client) or a standalone SSL client.

For more information about using a custom host name verifier, see Configure a custom host name verifier in Oracle WebLogic Server Administration Console Online Help.

Using a Host Name Verifier on Mac OS X Platforms

If WebLogic Server is installed on a Mac OS X platform that is running in a network in which the DHCP server assigns host names, by default Mac OS X dynamically overrides the host name set on your machine, using the one assigned by DHCP. Consequently, if you have generated demo identity certificates, host name verification may fail if the host name in your certificate does not match the one that has been dynamically reassigned to your machine.

This host name reassignment can occur frequently, such as whenever the network is restarted. To use demo identity certificates with WebLogic Server on Mac OS X platforms, do one of the following:

Disable host name verification (not recommended if operating in a production environment).
Prior to installing WebLogic Server, set a fixed host name on your machine. Depending on your environment, you may be able to do this by changing the value of the HOSTNAME property in /etc/hostconfig from -AUTOMATIC- to the name you wish to assign. For example:
```
HOSTNAME=mymachine.example.com
```
In addition, you may also verify that your desired host name is set in the file /Library/Preferences/SystemConfiguration/preferences.plist. Consult the Mac OS X documentation for your platform.