APIdia Launch Partner
Top Description Fields Constructors Methods
sun.security.util

public Class HostnameChecker

extends Object
Class Inheritance
Imports
java.io.IOException, java.net.IDN, .InetAddress, .UnknownHostException, java.security.Principal, java.security.cert.*, java.text.Normalizer, java.util.*, javax.security.auth.x500.X500Principal, javax.net.ssl.SNIHostName, sun.net.util.IPAddressUtil, sun.security.x509.X500Name, sun.security.ssl.SSLLogger

Class to check hostnames against the names specified in a certificate as required for TLS and LDAP.

Field Summary

Modifier and TypeField and Description
private static final int
private static final int
private final byte
private static final HostnameChecker
private static final HostnameChecker
public static final byte
public static final byte

Constructor Summary

AccessConstructor and Description
private
HostnameChecker(byte checkType)

Method Summary

Modifier and TypeMethod and Description
public static HostnameChecker
getInstance(byte checkType)

Get a HostnameChecker instance.

public static X500Name
getSubjectX500Name(X509Certificate cert)

Return the subject of a certificate as X500Name, by reparsing if necessary.

private static boolean
hasIllegalWildcard(String template, boolean chainsToPublicCA)

Returns true if the template contains an illegal wildcard character.

private static boolean
isIpAddress(String name)

Test whether the given hostname looks like a literal IPv4 or IPv6 address.

public boolean
isMatched(String name, String template, boolean chainsToPublicCA)

Returns true if name matches against template.

public void
match(String
the expected host name or ip address
expectedName
,
X509Certificate
the certificate to check against
cert
,
boolean
true if the certificate chains to a public root CA (as pre-installed in the cacerts file)
chainsToPublicCA
)

Perform the check.

public void
match(String expectedName, X509Certificate cert)

private void
matchDNS(String expectedName, X509Certificate cert, boolean chainsToPublicCA)

Check if the certificate allows use of the given DNS name.

private static void
matchIP(String expectedIP, X509Certificate cert)

Check if the certificate allows use of the given IP address.

private static boolean
matchLeftmostWildcard(String name, String template)

Returns true if name matches against template.

private static boolean
matchWildCards(String name, String template)

Returns true if the name matches against the template that may contain wildcard char *

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ALTNAME_DNSback to summary
private static final int ALTNAME_DNS
ALTNAME_IPback to summary
private static final int ALTNAME_IP
checkTypeback to summary
private final byte checkType
INSTANCE_LDAPback to summary
private static final HostnameChecker INSTANCE_LDAP
INSTANCE_TLSback to summary
private static final HostnameChecker INSTANCE_TLS
TYPE_LDAPback to summary
public static final byte TYPE_LDAP
TYPE_TLSback to summary
public static final byte TYPE_TLS

Constructor Detail

HostnameCheckerback to summary
private HostnameChecker(byte checkType)

Method Detail

getInstanceback to summary
public static HostnameChecker getInstance(byte checkType)

Get a HostnameChecker instance. checkType should be one of the TYPE_* constants defined in this class.

getSubjectX500Nameback to summary
public static X500Name getSubjectX500Name(X509Certificate cert) throws CertificateParsingException

Return the subject of a certificate as X500Name, by reparsing if necessary. X500Name should only be used if access to name components is required, in other cases X500Principal is to be preferred. This method is currently used from within JSSE, do not remove.

Annotations
@SuppressWarnings:deprecation
hasIllegalWildcardback to summary
private static boolean hasIllegalWildcard(String template, boolean chainsToPublicCA)

Returns true if the template contains an illegal wildcard character.

isIpAddressback to summary
private static boolean isIpAddress(String name)

Test whether the given hostname looks like a literal IPv4 or IPv6 address. The hostname does not need to be a fully qualified name. This is not a strict check that performs full input validation. That means if the method returns true, name need not be a correct IP address, rather that it does not represent a valid DNS hostname. Likewise for IP addresses when it returns false.

isMatchedback to summary
public boolean isMatched(String name, String template, boolean chainsToPublicCA)

Returns true if name matches against template.

The matching is performed as per RFC 2818/6125 rules for TLS and RFC 2830 rules for LDAP.

The name parameter should represent a DNS name. The template parameter may contain the wildcard character '*'.

matchback to summary
public void match(String expectedName, X509Certificate cert, boolean chainsToPublicCA) throws CertificateException

Perform the check.

Parameters
expectedName:String

the expected host name or ip address

cert:X509Certificate

the certificate to check against

chainsToPublicCA:boolean

true if the certificate chains to a public root CA (as pre-installed in the cacerts file)

Exceptions
CertificateException:
if the name does not match any of the names specified in the certificate
matchback to summary
public void match(String expectedName, X509Certificate cert) throws CertificateException
matchDNSback to summary
private void matchDNS(String expectedName, X509Certificate cert, boolean chainsToPublicCA) throws CertificateException

Check if the certificate allows use of the given DNS name. From RFC2818: 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 [RFC6125]. 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.)

matchIPback to summary
private static void matchIP(String expectedIP, X509Certificate cert) throws CertificateException

Check if the certificate allows use of the given IP address. From RFC2818: 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.

matchLeftmostWildcardback to summary
private static boolean matchLeftmostWildcard(String name, String template)

Returns true if name matches against template.

As per RFC 2830, section 3.6 - The "*" wildcard character is allowed. If present, it applies only to the left-most name component. E.g. *.bar.com would match a.bar.com, b.bar.com, etc. but not bar.com.

matchWildCardsback to summary
private static boolean matchWildCards(String name, String template)

Returns true if the name matches against the template that may contain wildcard char *