org.w3c.mwi.mobileok.basic
Interface HostnameVerifier

All Superinterfaces:

javax.net.ssl.HostnameVerifier

public interface HostnameVerifier
extends javax.net.ssl.HostnameVerifier

Interface for checking if a hostname matches the names stored in an X.509 certificate.

The interface implements javax.net.ssl.HostnameVerifier, and completes it with a set of check methods that take resp. an SSLSocket, an X509Certificate, or a list of certificate's CNs and DNS Subject-Alts.

Please note that the check methods throw exceptions when the hostname does not match the certificate whereas verify returns a boolean value.

The interface is provided with 5 implementations:

• HostnameVerifier.DEFAULT (works the same way as Curl and Firefox)
• HostnameVerifier.STRICT (works the same way as java.net.URL)
• HostnameVerifier.ALLOW_ALL (turns verification off)
• HostnameVerifier.DEFAULT_AND_LOCALHOST (localhost-like addresses are accepted)
• HostnameVerifier.STRICT_IE6 (works that same way as IE6)

The implementation is taken from Julius Davies' implementation of the not-yet-commons-ssl package (license: Apache version 2.0).

The original interface was in turn inspired by Sebastian Hauer's original StrictSSLProtocolSocketFactory in the HttpClient "contrib" repository.

The only differences with the original interface is that the dependency to the Certificates class was removed not to have to import the full package, i.e. Certificates.getCNs and Certificates.getDNSSubjectAlts in the initial package were simply moved to this class ; and that a specific SSLHostnameUnverifiedException is thrown by the check methods when the hostname does not match the names of the certificate.

The mobileOK Checker only uses the HostnameVerifier.DEFAULT implementation of the interface and calls the check(String, SSLSocket) method.

Version:

$Revision: 1.1 $

Author:

Julius Davies, Sebastian Hauer, Francois Daoust

Nested Class Summary

static class

HostnameVerifier.AbstractVerifier

Field Summary

static HostnameVerifier	ALLOW_ALL The ALLOW_ALL HostnameVerifier essentially turns hostname verification off.
static HostnameVerifier	DEFAULT The DEFAULT HostnameVerifier works the same way as Curl and Firefox.
static HostnameVerifier	DEFAULT_AND_LOCALHOST The DEFAULT_AND_LOCALHOST HostnameVerifier works like the DEFAULT one with one additional relaxation: a host of "localhost", "localhost.localdomain", "127.0.0.1", "::1" will always pass, no matter what is in the server's certificate.
static HostnameVerifier	STRICT The STRICT HostnameVerifier works the same way as java.net.URL in Sun Java 1.4, Sun Java 5, Sun Java 6.
static HostnameVerifier	STRICT_IE6 The STRICT_IE6 HostnameVerifier works just like the STRICT one with one minor variation: the hostname can match against any of the CN's in the server's certificate, not just the first one.

Method Summary

void	check(java.lang.String[] hosts, javax.net.ssl.SSLSocket ssl)
void	check(java.lang.String[] hosts, java.lang.String[] cns, java.lang.String[] subjectAlts) Checks to see if the supplied hostname matches any of the supplied CNs or "DNS" Subject-Alts.
void	check(java.lang.String[] hosts, java.security.cert.X509Certificate cert)
void	check(java.lang.String host, javax.net.ssl.SSLSocket ssl)
void	check(java.lang.String host, java.lang.String[] cns, java.lang.String[] subjectAlts)
void	check(java.lang.String host, java.security.cert.X509Certificate cert)
boolean	verify(java.lang.String host, javax.net.ssl.SSLSession session)

Field Detail

DEFAULT

static final HostnameVerifier DEFAULT

The DEFAULT HostnameVerifier works the same way as Curl and Firefox.

The hostname must match either the first CN, or any of the subject-alts. A wildcard can occur in the CN, and in any of the subject-alts.

The only difference between DEFAULT and STRICT is that a wildcard (such as "*.foo.com") with DEFAULT matches all subdomains, including "a.b.foo.com".

DEFAULT_AND_LOCALHOST

static final HostnameVerifier DEFAULT_AND_LOCALHOST

The DEFAULT_AND_LOCALHOST HostnameVerifier works like the DEFAULT one with one additional relaxation: a host of "localhost", "localhost.localdomain", "127.0.0.1", "::1" will always pass, no matter what is in the server's certificate.

STRICT

static final HostnameVerifier STRICT

The STRICT HostnameVerifier works the same way as java.net.URL in Sun Java 1.4, Sun Java 5, Sun Java 6. It's also pretty close to IE6. This implementation appears to be compliant with RFC 2818 for dealing with wildcards.

The hostname must match either the first CN, or any of the subject-alts. A wildcard can occur in the CN, and in any of the subject-alts. The one divergence from IE6 is how we only check the first CN. IE6 allows a match against any of the CNs present. We decided to follow in Sun Java 1.4's footsteps and only check the first CN.

A wildcard such as "*.foo.com" matches only subdomains in the same level, for example "a.foo.com". It does not match deeper subdomains such as "a.b.foo.com".

STRICT_IE6

static final HostnameVerifier STRICT_IE6

The STRICT_IE6 HostnameVerifier works just like the STRICT one with one minor variation: the hostname can match against any of the CN's in the server's certificate, not just the first one. This behaviour is identical to IE6's behaviour.

ALLOW_ALL

static final HostnameVerifier ALLOW_ALL

The ALLOW_ALL HostnameVerifier essentially turns hostname verification off. This implementation is a no-op, and never throws the SSLException.

Method Detail

verify

boolean verify(java.lang.String host,
               javax.net.ssl.SSLSession session)

Specified by:

verify in interface javax.net.ssl.HostnameVerifier

check

void check(java.lang.String host,
           javax.net.ssl.SSLSocket ssl)
           throws java.io.IOException

Throws:

java.io.IOException

check

void check(java.lang.String host,
           java.security.cert.X509Certificate cert)
           throws javax.net.ssl.SSLException

Throws:

javax.net.ssl.SSLException

check

void check(java.lang.String host,
           java.lang.String[] cns,
           java.lang.String[] subjectAlts)
           throws javax.net.ssl.SSLException

Throws:

javax.net.ssl.SSLException

check

void check(java.lang.String[] hosts,
           javax.net.ssl.SSLSocket ssl)
           throws java.io.IOException

Throws:

java.io.IOException

check

void check(java.lang.String[] hosts,
           java.security.cert.X509Certificate cert)
           throws javax.net.ssl.SSLException

Throws:

javax.net.ssl.SSLException

check

void check(java.lang.String[] hosts,
           java.lang.String[] cns,
           java.lang.String[] subjectAlts)
           throws javax.net.ssl.SSLException

Checks to see if the supplied hostname matches any of the supplied CNs or "DNS" Subject-Alts. Most implementations only look at the first CN, and ignore any additional CNs. Most implementations do look at all of the "DNS" Subject-Alts. The CNs or Subject-Alts may contain wildcards according to RFC 2818.

Parameters:

cns - CN fields, in order, as extracted from the X.509 certificate.

subjectAlts - Subject-Alt fields of type 2 ("DNS"), as extracted from the X.509 certificate.

hosts - The array of hostnames to verify.

Throws:

javax.net.ssl.SSLException - If verification failed.