com.entrust.toolkit.x509.directory

Class EntrustHostnameVerifier

java.lang.Object

com.entrust.toolkit.x509.directory.EntrustHostnameVerifier

All Implemented Interfaces:

javax.net.ssl.HostnameVerifier

public class EntrustHostnameVerifier
extends java.lang.Object
implements javax.net.ssl.HostnameVerifier

This class is used to determine if the Server Identity check passes according to specification in RFC 2830:

3.6. Server Identity Check

The client MUST check its understanding of the server's hostname against the server's identity as presented in the server's Certificate message, in order to prevent man-in-the-middle attacks.

Matching is performed according to these rules:

• The client MUST use the server hostname it used to open the LDAP connection as the value to compare against the server name as expressed in the server's certificate. The client MUST NOT use the server's canonical DNS name or any other derived form of name.
• If a subjectAltName extension of type dNSName is present in the certificate, it SHOULD be used as the source of the server's identity.
• Matching is case-insensitive.
• The "*" wildcard character is allowed. If present, it applies only to the left-most name component. For example, *.bar.com would match a.bar.com, b.bar.com, etc. but not bar.com. If more than one identity of a given type is present in the certificate (e.g. more than one dNSName name), a match in any one of the set is considered acceptable.

Since:

7.2 patch

See Also:

HostnameVerifier

Constructor Summary

Constructors

Constructor and Description
EntrustHostnameVerifier()

Method Summary

Modifier and Type	Method and Description
static EntrustSSLSocketFactory.InetHandling	getInetHandlingForName(java.lang.String host) This method checks the given hostname and returns the appropriate type of InetHandling mode, which will be one of the following: InetHandling.HOSTNAME InetHandling.IPADDRESS This method should be used when creating a socket using the EntrustSSLSocketFactory when the EntrustSSLSocketFactory.create() method uses a java.net.InetAddress or the unconnected Socket's connect() method uses java.net.SocketAddress.
protected boolean	getTLSServerNameAndMatch(java.lang.String hostname, X509Certificate cert) Extract the TLS servername(s) from the certificate and compare it against the hostname for a match.
boolean	verify(java.lang.String hostname, javax.net.ssl.SSLSession sslSession) Given a hostname and the SSLSession, determine if the Server Identity check passes according to RFC 2830.
protected boolean	verifyServer(java.lang.String hostname, java.lang.String[] names) Do the comparison using a String array of candidate DNS.
boolean	verifyServer(java.lang.String hostname, X509Certificate[] certs) Do the actual Hostname verification.
protected boolean	verifyServerIP(java.lang.String IPString, java.lang.String[] names) Do the comparison using the IP address strings converted to network byte order.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EntrustHostnameVerifier

public EntrustHostnameVerifier()

Method Detail

verify

public boolean verify(java.lang.String hostname,
                      javax.net.ssl.SSLSession sslSession)

Given a hostname and the SSLSession, determine if the Server Identity check passes according to RFC 2830.

Matching is performed according to these rules:

• The client MUST use the server hostname it used to open the LDAP connection as the value to compare against the server name as expressed in the server's certificate. The client MUST NOT use the server's canonical DNS name or any other derived form of name.
• If a subjectAltName extension of type dNSName is present in the certificate, it SHOULD be used as the source of the server's identity.
• Matching is case-insensitive.
• The "*" wildcard character is allowed. If present, it applies only to the left-most name component. For example, *.bar.com would match a.bar.com, b.bar.com, etc. but not bar.com. If more than one identity of a given type is present in the certificate (e.g. more than one dNSName name), a match in any one of the set is considered acceptable.

If the hostname does not match the dNSName-based identity in the certificate per the above check, a vaue of false is returned. If a match is successful a value of true is returned. It is left up to the user to determine what to do with the result of this check. Some clients MAY give the user the opportunity to continue with the connection or terminate the connection and indicate that the server's identity is suspect. Automated clients SHOULD close the connection, returning and/or logging an error indicating that the server's identity is suspect.

Specified by:

verify in interface javax.net.ssl.HostnameVerifier

Parameters:

hostname - the hostname being verifeid

sslSession - the SSLSession which will be verified against the hostname

See Also:

HostnameVerifier

getTLSServerNameAndMatch

protected boolean getTLSServerNameAndMatch(java.lang.String hostname,
                                           X509Certificate cert)

Extract the TLS servername(s) from the certificate and compare it against the hostname for a match. The first valid match will return true. If no matches are found false is returned. It looks for the server name in the following order:

1. the subject alternate name extension (as DNS name)
2. the subject's common name

Parameters:

hostname - The hostname being verified in String format

cert - the Certificate whose server names are being checked

Returns:

true indicating match found, false if no match found

verifyServer

public boolean verifyServer(java.lang.String hostname,
                            X509Certificate[] certs)

Do the actual Hostname verification. The specified hostname will be compared to the certificate specified at position 0 which should be the End user certificate. The following sequence is used:

• Check hostname is not null, return false if it is null
• Get the candidate server names from the certificate (search for subject alternate name and subject name using RFC 2830 guidelines), if these are null, or none are found, return false
• Check for a hostname match, by passing String array to verifier.

Parameters:

hostname - the hostname which will be verified

certs - the array of certificates which will be verified

Returns:

true if a hostname match was found, false if no hostname match found.

verifyServer

protected boolean verifyServer(java.lang.String hostname,
                               java.lang.String[] names)

Do the comparison using a String array of candidate DNS. Breaking The following sequence is used:

• change the hostname and certificate names to lowercase so that it is a case insensitive check according to RFC 2830 guidelines.
• Check for a hostname match, allowing the wildcard '*' character to be used according to RFC 2830

Breaking up the functionality in this way will make it easier to test.

Parameters:

hostname - the hostname which will be verified

names - The array of hostnames that will be used to try and find a match

Returns:

true if a hostname match was found, false if no hostname match found.

verifyServerIP

protected boolean verifyServerIP(java.lang.String IPString,
                                 java.lang.String[] names)

Do the comparison using the IP address strings converted to network byte order. This is more reliable than just a sting comparison of the IP strings, because IPv6 Strings have multiple valid formats.

Parameters:

IPString - the IP String that will be converted to a byte[] in network byte order

names - The array of IPStrings that will be used to try and find a match

Returns:

true if a match was found, false if no match found.

getInetHandlingForName

public static EntrustSSLSocketFactory.InetHandling getInetHandlingForName(java.lang.String host)

This method checks the given hostname and returns the appropriate type of InetHandling mode, which will be one of the following:

• InetHandling.HOSTNAME
• InetHandling.IPADDRESS

This method should be used when creating a socket using the EntrustSSLSocketFactory when the EntrustSSLSocketFactory.create() method uses a java.net.InetAddress or the unconnected Socket's connect() method uses java.net.SocketAddress. For example:

  EntrustSSLSocketFactory factory = new EntrustSSLSocketFactory(tm,km,sr);
  InetSocketAddress address = new InetSocketAddress(host, port);
  InetHandling inet = EntrustHostnameVerifier.getInetHandlingFor(host);
  factory.setInetAddressHandling(inet);
  SSLSocket s = (SSLSocket)factory.createSocket();
  s.setEnabledCipherSuites(CIPHER_SUITES);
  s.connect(address, m_timeout);
 

Parameters:

host - The hostname String which can either be in a hostname format (for example 'test.example.com') or IP address format (192.0.2.4).

Returns:

The InetHandling type appropriate for the given host String