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

This chapter includes the following sections:

Using the Default WebLogic Server Host Name Verifier

If you are using the default 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. The default host name verifier is configured by default. No action is needed to use it.

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.

If anything other than the default behavior is desired, either 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.

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:

Using the Default 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.

Using the Wildcarded Host Name Verifier

In addition to the default WebLogic Server host name verifier, WebLogic Server includes an alternative host name verifier called the wildcarded host name verifier. The wildcarded host name verifier works the same as the default WebLogic Server host name verifier; however, the wildcarded host name verifier also accepts additional SSL session certificates.

The wildcarded 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 Wildcarded 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 wildcarded 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 wildcarded 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 Wildcarded Host Name Verifier

The wildcarded host name verifier class name is weblogic.security.utils.SSLWLSWildcardHostnameVerifier. To configure the wildcarded host name verifier, specify this class as a custom host name verifier in the Servers: Configuration: SSL page of the WebLogic Server Administration Console. The wildcarded host name verifier has no parameters with which it must be configured. See Configure a custom host name verifier in the Oracle WebLogic Server Administration Console Online Help.

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.