iaik.security.ssl
Class ServerNameList

java.lang.Object
  extended by iaik.security.ssl.Extension
      extended by iaik.security.ssl.ServerNameList
All Implemented Interfaces:
java.lang.Cloneable

public class ServerNameList
extends Extension
implements java.lang.Cloneable

This class implements the ServerNameList structure as used by the server_name TLS extension.

Servers that run multiple (virtual) hosts on one ip address may want to know the actual server name used by the client when connecting to the server. This information may help the server to select a proper certificate for authenticating itself to the client.
The server_name extension allows a client to send a list of server names within the extended ClientHello message. The server then may check if he has a certificate that matches to any of the server names contained in the server name list received from the client.
TLS defines a ServerNameList as vector of ServerName objects: (see RFC 4366):

   struct {
       NameType name_type;
       select (name_type) {
           case host_name: HostName;
       } name;
   } ServerName;
 
   enum {
       host_name(0), (255)
   } NameType;
 
   opaque HostName<1..2^16-1>;
    
   struct {
      ServerName server_name_list<1..2^16-1>
   } ServerNameList;
 
Currently only one server name type is defined: DNS host name.

Note that RFC 4366 allows to send more than only one server names of the same type, whilst its successor RFC 6066 does not allow it anymore! You may use method setAllowMoreThanOneServerNamesOfSameType to decide if more than one server name of the same type shall be allowed or not (default: only one server name of the same type is allowed).

On the client side, when you create a ServerNameList to be sent within a server_name extension, specify the server names to be included, e.g.:

 // create ServerNameList
 ServerName[] serverNames = { new ServerName("jce.iaik.tugraz.at") }; 
 ServerNameList serverNameList = new ServerNameList(serverNames);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(serverNameList);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 // extensions are only defined for TLS
 clientContext.setAllowedProtocolVersions(SSLContext.VERSION_TLS10, SSLContext.VERSION_TLS12); 
 ...
 clientContext.setExtensions(extensions);
 ...
 
If you set the critical flag of a client-side ServerNameList to true (client-side default), the handshake will be aborted if the server does not respond with a server_name extension or has sent an "unrecognized_name" warning alert. If the server has sent an "unrecognized_name" fatal alert, the handshake will be aborted in any case, regardless if the client-side ServerNameList extension is configured as critical or not critical.
A critical client-side ServerNameList extension also means that the iSaSiLk client will reject the server certificate if it does not contain any of the suggested server names, provided that you do not have disabled certificate checking by disabling the ChainVerifier or overriding the ChainVerifier method verifyServer in a way to do not check the certificate server name against the ServerNameList extension.

You also may use the empty default ServerNameList constructor to create a ServerNameList on the client side. In this case iSaSiLk tries to calculate a ServerName of type HostName from the host name of the server you are connecting to, e.g.:

 // create empty ServerNameList
 ServerNameList serverNameList = new ServerNameList();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(serverNameList);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 // the host name of the server to connect to 
 String hostName = "jce.iaik.tugraz.at";
 // the server port 
 int port = 443;
 // create Socket
 SSLSocket socket = new SSLSocket(hostName, port, clientContext);
 ...
 
In this example iSaSiLk will calculate a ServerName for the host name "jce.iaik.tugraz.at" and sent it within the ServerNameList in the extended ClientHello message.

On the server side you only have to tell the SSLServerContext configuration whether to support the server_name extension or not. The server only will send an empty ServerNameList extension in response to a server_name extension received from the client. Thus no server names are required when configuring the SSLServerContext to support the server_name extension:

 // create ServerNameList
 ServerNameList serverNameList = new ServerNameList();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(serverNameList);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 
If you set the critical flag of a server-side server_name extension to true, the handshake will be aborted if the client does not send a server_name extension within the extended ClientHello message.

Version:
File Revision 28
See Also:
ServerName, Extension, ExtensionList

Field Summary
static ExtensionType TYPE
          The type (0) of the server_name extension.
 
Constructor Summary
ServerNameList()
          Creates a new ServerNameList.
ServerNameList(ServerName[] serverNames)
          Creates a ServerNameList from the given server names.
 
Method Summary
 java.lang.Object clone()
          Returns a clone of this ServerNameList.
 boolean equals(java.lang.Object obj)
          Checks if this ServerNameList is equal to the given object.
 ServerName[] getServerNames()
          Gets the server names included in this server name list.
 int hashCode()
          Gets a hash code of this ServerNameList.
static void setAllowMoreThanOneServerNamesOfSameType(boolean allow)
          Decides whether more than one server names of the same type shall be allowed or not.
 java.lang.String toString()
          Gets a String representation of this ServerNameList.
 
Methods inherited from class iaik.security.ssl.Extension
getExtensionType, getName, getType, setCritical
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

TYPE

public static final ExtensionType TYPE
The type (0) of the server_name extension.

Constructor Detail

ServerNameList

public ServerNameList()
Creates a new ServerNameList.
This constructor shall be used on the server side to enable server_name extension support for the SSLServerContext configuration:
 // create ServerNameList
 ServerNameList serverNameList = new ServerNameList();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(serverNameList);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 
If you set the critical flag of this extension to true, the handshake will be aborted if the client does not send a server_name extension within the extended ClientHello message.

If the client has sent a server_name extension, the server will respond with an empty server_name extension.

If this constructor is used on the client side iSaSiLk tries to calculate a ServerName of type HostName from the host name of the server you are connecting to.


ServerNameList

public ServerNameList(ServerName[] serverNames)
Creates a ServerNameList from the given server names.
This constructor shall be used on the client side to specify the server names that shall be sent to the server within an extended ClientHello message, e.g.:
 // create ServerNameList
 ServerName[] serverNames = { new ServerName("jce.iaik.tugraz.at"), new ServerName("jce.iaik.at") }; 
 ServerNameList serverNameList = new ServerNameList(serverNames);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(serverNameList);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 
If you set the critical flag of this extension to true (client-side default), the handshake will be aborted if the server does not respond with a server_name extension or has sent an "unrecognized_name" warning alert.

You alternatively may use the empty default constructor to create an empty ServerNameList on the client side. In this case iSaSiLk tries to calculate a ServerName of type HostName from the host name of the server you are connecting to.

Parameters:
serverNames - the server names to be sent to the server (the serverNames array is not cloned or copied by this method)
Throws:
java.lang.IllegalArgumentException - if the given ServerNames array contains multiple ServerNames of same types, but only one name of the same type is allowed
Method Detail

setAllowMoreThanOneServerNamesOfSameType

public static void setAllowMoreThanOneServerNamesOfSameType(boolean allow)
Decides whether more than one server names of the same type shall be allowed or not. RFC 6066 forbids more than one server names of the same type; previous versions had allowed it.

Parameters:
allow - whether to allow more than one server names of the same type or not (default: false)

getServerNames

public ServerName[] getServerNames()
Gets the server names included in this server name list.

Returns:
the server names as array of ServerName; the array maybe null or empty if no server names are included in the list (the returned array is not cloned or copied by this method)

hashCode

public int hashCode()
Gets a hash code of this ServerNameList.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code of this ServerNameList

equals

public boolean equals(java.lang.Object obj)
Checks if this ServerNameList is equal to the given object.

Two ServerNameLists are treated as equal if they contain the same ServerName objects (same number and same order). The critical value is not checked by this method.

Overrides:
equals in class java.lang.Object
Returns:
true if this ServerNameList is equal to the given object, false if it is not equal to it

clone

public java.lang.Object clone()
Returns a clone of this ServerNameList.

Overrides:
clone in class Extension
Returns:
a clone of this ServerNameList

toString

public java.lang.String toString()
Gets a String representation of this ServerNameList.

Specified by:
toString in class Extension
Returns:
a String representation of the ServerNameList

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

iSaSiLk 5.104, (c) 2002 IAIK, (c) 2003 - 2015 SIC