com.entrust.toolkit.smproxy

Class SMProxyHostnameVerifier

java.lang.Object

com.entrust.toolkit.smproxy.SMProxyHostnameVerifier

All Implemented Interfaces:

javax.net.ssl.HostnameVerifier

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

This class is used to determine if the Server Identity check passes according to the specification for HTTP Over TLS RFC 2830:

3.1. Server Identity

In general, HTTP/TLS requests are generated by dereferencing a URI. As a consequence, the hostname for the server is known to the client. If the hostname is available, the client MUST check it against the server's identity as presented in the server's Certificate message, in order to prevent man-in-the-middle attacks.

If the client has external information as to the expected identity of the server, the hostname check MAY be omitted. (For instance, a client may be connecting to a machine whose address and hostname are dynamic but the client knows the certificate that the server will present.) In such cases, it is important to narrow the scope of acceptable certificates as much as possible in order to prevent man in the middle attacks. In special cases, it may be appropriate for the client to simply ignore the server's identity, but it must be understood that this leaves the connection open to active attack.

If a subjectAltName extension of type dNSName is present, that MUST be used as the identity. Otherwise, the (most specific) Common Name field in the Subject field of the certificate MUST be used. Although the use of the Common Name is existing practice, it is deprecated and Certification Authorities are encouraged to use the dNSName instead.

Matching is performed using the matching rules specified by [RFC2459]. 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.) Names may contain the wildcard character * which is considered to match any single domain name component or component fragment. E.g., *.a.com matches foo.a.com but not bar.foo.a.com. f*.com matches foo.com but not bar.com.

In some cases, the URI is specified as an IP address rather than a hostname. In this case, the iPAddress subjectAltName must be present in the certificate and must exactly match the IP in the URI.

Since:

8.1

Constructor Summary

Constructors

Constructor and Description
SMProxyHostnameVerifier()

Method Summary

Modifier and Type	Method and Description
static SMProxySSLSocketFactory.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 HTTP Over TLS 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

SMProxyHostnameVerifier

public SMProxyHostnameVerifier()

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 HTTP Over TLS RFC 2830.

Matching is performed according to these rules:

Matching is performed using the matching rules specified by [RFC2459]. 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.) Names may contain the wildcard character * which is considered to match any single domain name component or component fragment. E.g., *.a.com matches foo.a.com but not bar.foo.a.com. f*.com matches foo.com but not bar.com.

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 verified

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 2818

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