iaik.security.ssl
Class ServerName

java.lang.Object
  iaik.security.ssl.ServerName

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class ServerName
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

This class represents a ServerName as used by the TLS server_name extension (see RFC 4366).

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 ServerName as type and name struct (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>;
 

Currently only one server name type is defined: DNS host name.

When creating a ServerName object the name type and (encoded and/or not encoded) name value have to be specified, for instance call

 ServerName serverName = new ServerName(ServerName.HOST_NAME, "jce.iaik.tugraz.at", null);
 

to create a ServerName object of type HostName with name "jce.iaik.tugraz.at". Since HostName is the default (and currently also only defined) name type, you alternatively may use constructor ServerName(String name) which sets the name type automatically to HostName:

 ServerName serverName = new ServerName("jce.iaik.tugraz.at");
 

You also can create a ServerName object from its encoded representation:

 byte[] encodedServerName = ...;
 ServerName serverName = new ServerName(encodedServerName);
 

The encodedServerName does not represent the full TLS encoded server name struct (including name type and name), rather it represents the encoded name component (without the name type) only. Thus for the HostName) type, encodedServerName is the UTF-8 encoded server name.

For getting the (String or encoded) representation from a ServerName object, use methods getName or getEncodedName, respectively, e.g.:

 String name = serverName.getName();
 

Currently this ServerName implementation supports the server name type hostName since it is the only name type that is defined by the TLS Extensions specification (see 4366). Thus, methods getEncodedName or getName return the UTF-8 en/decoded host name respectively. If you want to support other name types / encoding formats you may use the creating constructor, or you may write your own ServerName class and override the corresponding getTLSServerName SecurityProvider implementation.

On the client side you will use the ServerName class to build up a ServerNameList to be sent to the server, e.g.:

 // create server name list
 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);
 ...
 

On the server side you may use the ServerName class to associate specific server names with server credentials for the SSLServerContext configuration. You may let the KeyAndCert calcualte any server names or set it explicitly, e.g.:

  // server certificate chain
  X509Certificate certChain = ...;
  // server private key
  PrivateKey privateKey = ...;
  // create server credentials
  KeyAndCert serverCredentials = new KeyAndCert(certChain, privateKey);
  // add server credentials to the SSLServerContext
  SSLServerContext serverContext = new SSLServerContext();
  serverContext.addServerCredentials(serverCredentials);
 

See Also:

ServerNameList, SecurityProvider.getTLSServerName(int, byte[]), SecurityProvider.getTLSServerName(int, X509Certificate), KeyAndCert, Serialized Form

Field Summary

static int

HOST_NAME Pre-defined NameType (DNS) host_name (0).

Constructor Summary

ServerName(byte[] encodedHostName)
Creates a new ServerName for the given encoded host name.

ServerName(int type, java.lang.String name, byte[] encodedName)
Creates a new ServerName from given type, name and encoded name.

ServerName(int type, java.lang.String name, byte[] encodedName, boolean checkForIpAddress)
Creates a new ServerName from given type, name and encoded name.

ServerName(java.lang.String hostName)
Creates a new ServerName for the given host name.

Method Summary

java.lang.Object	clone() Gets a clone of this ServerName.
boolean	equals(java.lang.Object obj) Checks if this ServerName is equal to the given object.
byte[]	getEncodedName() Gets the (UTF-8) encoded name of the server.
java.lang.String	getName() Gets the name of the server as String.
int	getType() Gets the type of this ServerName.
java.lang.String	getTypeAsString() Gets the type of this ServerName as String.
int	hashCode() Gets a hash code of this ServerName.
boolean	isTypeSupported() Asks whether the type of this ServerName is supported or not.
java.lang.String	toString() Gets a String representation of this ServerName.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

HOST_NAME

public static final int HOST_NAME

Pre-defined NameType (DNS) host_name (0).

See Also:

Constant Field Values

Constructor Detail

ServerName

public ServerName(byte[] encodedHostName)

Creates a new ServerName for the given encoded host name. The name type is set to HOST_NAME.

Parameters:

encodedHostName - the (UTF-8) encoded host name (the encodedHostName byte array is not cloned or copied by this constructor)

ServerName

public ServerName(java.lang.String hostName)
           throws java.io.UnsupportedEncodingException

Creates a new ServerName for the given host name. The name type is set to HOST_NAME.

Parameters:

hostName - the host name as String

Throws:

java.io.UnsupportedEncodingException - if an error occurs when trying to encode the name

java.lang.IllegalArgumentException - if the given hostName represents an ipAddress

ServerName

public ServerName(int type,
                  java.lang.String name,
                  byte[] encodedName)
           throws java.io.UnsupportedEncodingException

Creates a new ServerName from given type, name and encoded name. Both name and encodedName are not allowed to be null. If encodedName is null this default ServerName implementation tries to UTF-8 encode the given name String when method getEncodedName is called. If name is null this default implementation tries to UTF-8 decode the given encoded name when method getName is called.

Parameters:

type - the type of this ServerName

name - the name; maybe null if encodedName is not null

encodedName - the encoded name; maybe null if name is not null. (the encodedName array is not cloned or copied by this method)

Throws:

java.lang.IllegalArgumentException - if type is out of range (not between 0 and 255) or encodedName is greater than 2^16-1, or if name and encodedName are both null, or if ServerName type is HOST_NAME and name is not null and represents an ipAddress (encodedName is not checked if representing an iPAddress to avoid interoperability problems on the receiving side)

java.io.UnsupportedEncodingException - if an error occurs when trying to encode the name (if encodedName is null)

ServerName

public ServerName(int type,
                  java.lang.String name,
                  byte[] encodedName,
                  boolean checkForIpAddress)
           throws java.io.UnsupportedEncodingException

Creates a new ServerName from given type, name and encoded name. Both name and encodedName are not allowed to be null. If encodedName is null this default ServerName implementation tries to UTF-8 encode the given name String when method getEncodedName is called. If name is null this default implementation tries to UTF-8 decode the given encoded name when method getName is called.

Parameters:

type - the type of this ServerName

name - the name; maybe null if encodedName is not null

encodedName - the encoded name; maybe null if name is not null. (the encodedName array is not cloned or copied by this method)

checkForIpAddress - whether to check for iPAddress (and throw an Exception if the provided name represents an ipAddress)

Throws:

java.lang.IllegalArgumentException - if type is out of range (not between 0 and 255) or encodedName is greater than 2^16-1, or if name and encodedName are both null, or if checkForIpAddress is true and ServerName type is HOST_NAME and name is not null and represents an ipAddress (encodedName is not checked if representing an iPAddress to avoid interoperability problems on the receiving side)

java.io.UnsupportedEncodingException - if an error occurs when trying to encode the name (if encodedName is null)

Method Detail

getType

public int getType()

Gets the type of this ServerName.

Returns:

the type of this ServerName.

isTypeSupported

public boolean isTypeSupported()

Asks whether the type of this ServerName is supported or not. If the ServerNameList received from the client does contain an unsupported server name, the server sends back an "unrecognized_name" AlertMessage, which maybe fatal depending on the critical flag of the ServerNameList configuration on the server side.
This default ServerName implementation supports the HostName name type which currently is the only name type defined by the TLS Extensions specification (RFC 4366).

Returns:

true of the type of this ServerName is supported, false if it is not supported

getTypeAsString

public java.lang.String getTypeAsString()

Gets the type of this ServerName as String.

Returns:

the type of this ServerName as String

getName

public java.lang.String getName()
                         throws java.io.UnsupportedEncodingException

Gets the name of the server as String.

Returns:

the name of the server as String.

Throws:

java.io.UnsupportedEncodingException - if an error occurs when trying to decode the name to get its String representation (if it has not been decoded so far)

getEncodedName

public byte[] getEncodedName()
                      throws java.io.UnsupportedEncodingException

Gets the (UTF-8) encoded name of the server. The encoded server name does not represent the full TLS encoded server name struct (including name type and name), rather it represents the encoded name component (without the name type) only. Thus for the HostName) type, this method returns the UTF-8 encoded server name. If you want to support other name types / encoding formats you may use the creating constructor, or you may write your own ServerName class and override the corresponding getTLSServerName SecurityProvider implementation.

Returns:

the encoded name of the server (the returned byte array is not cloned or copied by this method)

Throws:

java.io.UnsupportedEncodingException - if an error occurs when trying to encode the name

hashCode

public int hashCode()

Gets a hash code of this ServerName.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code of this ServerName

equals

public boolean equals(java.lang.Object obj)

Checks if this ServerName is equal to the given object. This current default ServerName implementation does no full IDNA host name comparison as required by RCF 4366. This method checks of the encoded name representations are equal. If only String representations of the names are available this method performs a case insensitive comparison of the name strings. This equality check should be sufficient for most ServerNames of type HostName (which currently is the only name type definded by the TLS extension specification; see RFC 4366).

If you want to implement a more sophisticated name comparison algorithm, you may extend this ServerName class and override methods of the iSaSiLk SecurityProvider to let them return an insance of your ServerName implementation.

Overrides:

equals in class java.lang.Object

Returns:

true if this ServerName is equal to the given object, false if it is not equal to it

clone

public java.lang.Object clone()

Gets a clone of this ServerName.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this ServerName

toString

public java.lang.String toString()

Gets a String representation of this ServerName.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this ServerName