Back to index...

	/*
	* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package javax.net.ssl;

	import java.net.IDN;
	import java.nio.ByteBuffer;
	import java.nio.charset.CodingErrorAction;
	import java.nio.charset.StandardCharsets;
	import java.nio.charset.CharsetDecoder;
	import java.nio.charset.CharacterCodingException;
	import java.util.Locale;
	import java.util.Objects;
	import java.util.regex.Pattern;

	/**
	* Instances of this class represent a server name of type
	* {@link StandardConstants#SNI_HOST_NAME host_name} in a Server Name
	* Indication (SNI) extension.
	* <P>
	* As described in section 3, "Server Name Indication", of
	* <A HREF="http://www.ietf.org/rfc/rfc6066.txt">TLS Extensions (RFC 6066)</A>,
	* "HostName" contains the fully qualified DNS hostname of the server, as
	* understood by the client. The encoded server name value of a hostname is
	* represented as a byte string using ASCII encoding without a trailing dot.
	* This allows the support of Internationalized Domain Names (IDN) through
	* the use of A-labels (the ASCII-Compatible Encoding (ACE) form of a valid
	* string of Internationalized Domain Names for Applications (IDNA)) defined
	* in <A HREF="http://www.ietf.org/rfc/rfc5890.txt">RFC 5890</A>.
	* <P>
	* Note that {@code SNIHostName} objects are immutable.
	*
	* @see SNIServerName
	* @see StandardConstants#SNI_HOST_NAME
	*
	* @since 1.8
	*/
	public final class SNIHostName extends SNIServerName {

	// the decoded string value of the server name
	private final String hostname;

	/**
	* Creates an {@code SNIHostName} using the specified hostname.
	* <P>
	* Note that per <A HREF="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</A>,
	* the encoded server name value of a hostname is
	* {@link StandardCharsets#US_ASCII}-compliant. In this method,
	* {@code hostname} can be a user-friendly Internationalized Domain Name
	* (IDN). {@link IDN#toASCII(String, int)} is used to enforce the
	* restrictions on ASCII characters in hostnames (see
	* <A HREF="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</A>,
	* <A HREF="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122</A>,
	* <A HREF="http://www.ietf.org/rfc/rfc1123.txt">RFC 1123</A>) and
	* translate the {@code hostname} into ASCII Compatible Encoding (ACE), as:
	* <pre>
	* IDN.toASCII(hostname, IDN.USE_STD3_ASCII_RULES);
	* </pre>
	* <P>
	* The {@code hostname} argument is illegal if it:
	* <ul>
	* <li> {@code hostname} is empty,</li>
	* <li> {@code hostname} ends with a trailing dot,</li>
	* <li> {@code hostname} is not a valid Internationalized
	* Domain Name (IDN) compliant with the RFC 3490 specification.</li>
	* </ul>
	* @param hostname
	* the hostname of this server name
	*
	* @throws NullPointerException if {@code hostname} is {@code null}
	* @throws IllegalArgumentException if {@code hostname} is illegal
	*/
	public SNIHostName(String hostname) {
	// IllegalArgumentException will be thrown if {@code hostname} is
	// not a valid IDN.
	super(StandardConstants.SNI_HOST_NAME,
	(hostname = IDN.toASCII(
	Objects.requireNonNull(hostname,
	"Server name value of host_name cannot be null"),
	IDN.USE_STD3_ASCII_RULES))
	.getBytes(StandardCharsets.US_ASCII));

	this.hostname = hostname;

	// check the validity of the string hostname
	checkHostName();
	}

	/**
	* Creates an {@code SNIHostName} using the specified encoded value.
	* <P>
	* This method is normally used to parse the encoded name value in a
	* requested SNI extension.
	* <P>
	* Per <A HREF="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</A>,
	* the encoded name value of a hostname is
	* {@link StandardCharsets#US_ASCII}-compliant. However, in the previous
	* version of the SNI extension (
	* <A HREF="http://www.ietf.org/rfc/rfc4366.txt">RFC 4366</A>),
	* the encoded hostname is represented as a byte string using UTF-8
	* encoding. For the purpose of version tolerance, this method allows
	* that the charset of {@code encoded} argument can be
	* {@link StandardCharsets#UTF_8}, as well as
	* {@link StandardCharsets#US_ASCII}. {@link IDN#toASCII(String)} is used
	* to translate the {@code encoded} argument into ASCII Compatible
	* Encoding (ACE) hostname.
	* <P>
	* It is strongly recommended that this constructor is only used to parse
	* the encoded name value in a requested SNI extension. Otherwise, to
	* comply with <A HREF="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</A>,
	* please always use {@link StandardCharsets#US_ASCII}-compliant charset
	* and enforce the restrictions on ASCII characters in hostnames (see
	* <A HREF="http://www.ietf.org/rfc/rfc3490.txt">RFC 3490</A>,
	* <A HREF="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122</A>,
	* <A HREF="http://www.ietf.org/rfc/rfc1123.txt">RFC 1123</A>)
	* for {@code encoded} argument, or use
	* {@link SNIHostName#SNIHostName(String)} instead.
	* <P>
	* The {@code encoded} argument is illegal if it:
	* <ul>
	* <li> {@code encoded} is empty,</li>
	* <li> {@code encoded} ends with a trailing dot,</li>
	* <li> {@code encoded} is not encoded in
	* {@link StandardCharsets#US_ASCII} or
	* {@link StandardCharsets#UTF_8}-compliant charset,</li>
	* <li> {@code encoded} is not a valid Internationalized
	* Domain Name (IDN) compliant with the RFC 3490 specification.</li>
	* </ul>
	*
	* <P>
	* Note that the {@code encoded} byte array is cloned
	* to protect against subsequent modification.
	*
	* @param encoded
	* the encoded hostname of this server name
	*
	* @throws NullPointerException if {@code encoded} is {@code null}
	* @throws IllegalArgumentException if {@code encoded} is illegal
	*/
	public SNIHostName(byte[] encoded) {
	// NullPointerException will be thrown if {@code encoded} is null
	super(StandardConstants.SNI_HOST_NAME, encoded);

	// Compliance: RFC 4366 requires that the hostname is represented
	// as a byte string using UTF_8 encoding [UTF8]
	try {
	// Please don't use {@link String} constructors because they
	// do not report coding errors.
	CharsetDecoder decoder = StandardCharsets.UTF_8.newDecoder()
	.onMalformedInput(CodingErrorAction.REPORT)
	.onUnmappableCharacter(CodingErrorAction.REPORT);

	this.hostname = IDN.toASCII(
	decoder.decode(ByteBuffer.wrap(encoded)).toString());
	} catch (RuntimeException \| CharacterCodingException e) {
	throw new IllegalArgumentException(
	"The encoded server name value is invalid", e);
	}

	// check the validity of the string hostname
	checkHostName();
	}

	/**
	* Returns the {@link StandardCharsets#US_ASCII}-compliant hostname of
	* this {@code SNIHostName} object.
	* <P>
	* Note that, per
	* <A HREF="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</A>, the
	* returned hostname may be an internationalized domain name that
	* contains A-labels. See
	* <A HREF="http://www.ietf.org/rfc/rfc5890.txt">RFC 5890</A>
	* for more information about the detailed A-label specification.
	*
	* @return the {@link StandardCharsets#US_ASCII}-compliant hostname
	* of this {@code SNIHostName} object
	*/
	public String getAsciiName() {
	return hostname;
	}

	/**
	* Compares this server name to the specified object.
	* <P>
	* Per <A HREF="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</A>, DNS
	* hostnames are case-insensitive. Two server hostnames are equal if,
	* and only if, they have the same name type, and the hostnames are
	* equal in a case-independent comparison.
	*
	* @param other
	* the other server name object to compare with.
	* @return true if, and only if, the {@code other} is considered
	* equal to this instance
	*/
	@Override
	public boolean equals(Object other) {
	if (this == other) {
	return true;
	}

	if (other instanceof SNIHostName) {
	return hostname.equalsIgnoreCase(((SNIHostName)other).hostname);
	}

	return false;
	}

	/**
	* Returns a hash code value for this {@code SNIHostName}.
	* <P>
	* The hash code value is generated using the case-insensitive hostname
	* of this {@code SNIHostName}.
	*
	* @return a hash code value for this {@code SNIHostName}.
	*/
	@Override
	public int hashCode() {
	int result = 17; // 17/31: prime number to decrease collisions
	result = 31 * result + hostname.toUpperCase(Locale.ENGLISH).hashCode();

	return result;
	}

	/**
	* Returns a string representation of the object, including the DNS
	* hostname in this {@code SNIHostName} object.
	* <P>
	* The exact details of the representation are unspecified and subject
	* to change, but the following may be regarded as typical:
	* <pre>
	* "type=host_name (0), value={@literal <hostname>}"
	* </pre>
	* The "{@literal <hostname>}" is an ASCII representation of the hostname,
	* which may contains A-labels. For example, a returned value of an pseudo
	* hostname may look like:
	* <pre>
	* "type=host_name (0), value=www.example.com"
	* </pre>
	* or
	* <pre>
	* "type=host_name (0), value=xn--fsqu00a.xn--0zwm56d"
	* </pre>
	* <P>
	* Please NOTE that the exact details of the representation are unspecified
	* and subject to change.
	*
	* @return a string representation of the object.
	*/
	@Override
	public String toString() {
	return "type=host_name (0), value=" + hostname;
	}

	/**
	* Creates an {@link SNIMatcher} object for {@code SNIHostName}s.
	* <P>
	* This method can be used by a server to verify the acceptable
	* {@code SNIHostName}s. For example,
	* <pre>
	* SNIMatcher matcher =
	* SNIHostName.createSNIMatcher("www\\.example\\.com");
	* </pre>
	* will accept the hostname "www.example.com".
	* <pre>
	* SNIMatcher matcher =
	* SNIHostName.createSNIMatcher("www\\.example\\.(com\|org)");
	* </pre>
	* will accept hostnames "www.example.com" and "www.example.org".
	*
	* @param regex
	* the <a href="{@docRoot}/java/util/regex/Pattern.html#sum">
	* regular expression pattern</a>
	* representing the hostname(s) to match
	* @return a {@code SNIMatcher} object for {@code SNIHostName}s
	* @throws NullPointerException if {@code regex} is
	* {@code null}
	* @throws java.util.regex.PatternSyntaxException if the regular expression's
	* syntax is invalid
	*/
	public static SNIMatcher createSNIMatcher(String regex) {
	if (regex == null) {
	throw new NullPointerException(
	"The regular expression cannot be null");
	}

	return new SNIHostNameMatcher(regex);
	}

	// check the validity of the string hostname
	private void checkHostName() {
	if (hostname.isEmpty()) {
	throw new IllegalArgumentException(
	"Server name value of host_name cannot be empty");
	}

	if (hostname.endsWith(".")) {
	throw new IllegalArgumentException(
	"Server name value of host_name cannot have the trailing dot");
	}
	}

	private final static class SNIHostNameMatcher extends SNIMatcher {

	// the compiled representation of a regular expression.
	private final Pattern pattern;

	/**
	* Creates an SNIHostNameMatcher object.
	*
	* @param regex
	* the <a href="{@docRoot}/java/util/regex/Pattern.html#sum">
	* regular expression pattern</a>
	* representing the hostname(s) to match
	* @throws NullPointerException if {@code regex} is
	* {@code null}
	* @throws PatternSyntaxException if the regular expression's syntax
	* is invalid
	*/
	SNIHostNameMatcher(String regex) {
	super(StandardConstants.SNI_HOST_NAME);
	pattern = Pattern.compile(regex, Pattern.CASE_INSENSITIVE);
	}

	/**
	* Attempts to match the given {@link SNIServerName}.
	*
	* @param serverName
	* the {@link SNIServerName} instance on which this matcher
	* performs match operations
	*
	* @return {@code true} if, and only if, the matcher matches the
	* given {@code serverName}
	*
	* @throws NullPointerException if {@code serverName} is {@code null}
	* @throws IllegalArgumentException if {@code serverName} is
	* not of {@code StandardConstants#SNI_HOST_NAME} type
	*
	* @see SNIServerName
	*/
	@Override
	public boolean matches(SNIServerName serverName) {
	if (serverName == null) {
	throw new NullPointerException(
	"The SNIServerName argument cannot be null");
	}

	SNIHostName hostname;
	if (!(serverName instanceof SNIHostName)) {
	if (serverName.getType() != StandardConstants.SNI_HOST_NAME) {
	throw new IllegalArgumentException(
	"The server name type is not host_name");
	}

	try {
	hostname = new SNIHostName(serverName.getEncoded());
	} catch (NullPointerException \| IllegalArgumentException e) {
	return false;
	}
	} else {
	hostname = (SNIHostName)serverName;
	}

	// Let's first try the ascii name matching
	String asciiName = hostname.getAsciiName();
	if (pattern.matcher(asciiName).matches()) {
	return true;
	}

	// May be an internationalized domain name, check the Unicode
	// representations.
	return pattern.matcher(IDN.toUnicode(asciiName)).matches();
	}
	}
	}

Back to index...