ALPNProtocolNameList (iSaSiLk 6.1 API Documentation)

java.lang.Object
- iaik.security.ssl.Extension
- - iaik.security.ssl.ALPNProtocolNameList

All Implemented Interfaces:

java.lang.Cloneable
```
public class ALPNProtocolNameList
extends Extension
implements java.lang.Cloneable
```
This class implements the ProtocolNameList structure as used by the application_layer_protocol_negotiation TLS extension (see RFC 7301).
The application_layer_protocol_negotiation (ALPN) extension allows to negotiate the application layer protocol within the TLS handshake. For doing so the client sends an ALPN extension containing the names of the application layer protocols it supports (in preference order). The server compares the protocol names got from the client with its locally configured list and sends back an ALPN extension containing the first of its protocol names that matches to any of the protocol names received from the client. If the server does not support any of the client protocols it sends back a fatal "NO APPLICATION PROTOCOL" alert.
RFC 7301 defines an ALPN ProtocolNameList as list of protocol names:
```
   opaque ProtocolName<1..2^8-1>;

  struct {
      ProtocolName protocol_name_list<2..2^16-1>
  } ProtocolNameList;
 
```
When creating an ALPNProtocolName object the encoded and/or not encoded name value have to be specified, e.g.:
```
 String protocolName = ...;
 byte[] encodedProtocolName = ...;
 ALPNProtocolName protocolName = new ALPNProtocolName(protocolName, encodedProtocolName);
 
```
If the encoded name is not specified it is UTF-8 encoding before sent to the peer. If the name is not specified the encoded name is UTF-8 decoded.
On the client side you will use the ALPNProtocolName class to build an ALPNProtocolNameList to be sent to the server. You can create ALPNProtocolName objects on your own or use any of the predefined names e.g.:
```
 // create protocol name list for http/1.1 and http/2
 ALPNProtocolName[] protocolNames = { ALPNProtocolName.PN_HTTP_11, ALPNProtocolName.PN_H_2 };
 ALPNProtocolNameList protocolNameList = new ALPNProtocolNameList(protocolNames);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(protocolNameList);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 
```
When having finished the handshake you may get the negotiated protocol name by asking the SSLSocket for the ProtocolNameList included in the active extension list (extensions negotiated between client and server) or in the peer extension list (extensions got from the server). Since the server is only allowed to send an ALPN extension containing one protocol name only, the ALPNProtocolNameList got from the active extension list should be equal to the one got from the peer extension list (if the server has sent back an ALPN extension):
```
 SSLContext clientContext = ...;
 ...
 // set extensions (including ALPN)
 ...
 String serverName = ...;
 int serverPort = ...;
 // create SSLSocket, perform handshake, e.g.:
 SSLSocket sslSocket = new SSLSocket(serverName, serverPort, clientContext);
 sslSocket.startHandshake();
 ...
 // get ALPN extension and protocol name sent by the server:
 ExtensionList activeExtensions = socket.getActiveExtensions();
 if (activeExtensions != null) {
   ALPNProtocolNameList protocolNameList = (ALPNProtocolNameList)activeExtensions.getExtension(ALPNProtocolNameList.TYPE);
   if (protocolNameList != null) {
     ALPNProtocolName[] protocolNames = protocolNameList.getProtocolNames();
     System.out.println("Using ALPN protocol: " + protocolNames[0]);
   }
 }
 
```
If you set the critical flag of a client-side ALPNProtocolNameList to true (client-side default), the handshake will be aborted if the server does not respond with a ALPN extension or has sent an ALPN extension containing none or more than one protocol names. If the server has sent an "no_application_protocol" fatal alert, the handshake will be aborted in any case, regardless if the client-side ALPNProtocolNameList extension is configured as critical or not critical.
On the server side you may use the ALPNProtocolName class to build an ALPNProtocolNameList to tell the server which protocol names may be accepted from the client e.g.:
```
 // create protocol name list for http/1.1 and http/2
 ALPNProtocolName[] protocolNames = { ALPNProtocolName.PN_HTTP_11, ALPNProtocolName.PN_H_2 };
 ALPNProtocolNameList protocolNameList = new ALPNProtocolNameList(protocolNames);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(protocolNameList);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 
```
If you set the critical flag of a server-side application_layer_protocol_negotiation extension to true, the handshake will be aborted if the client does not send a application_layer_protocol_negotiation extension within the extended ClientHello message or the client has sent an empty ALPN extension.
By default ALPN extensions are not critical.
Version:

File Revision 34

See Also:

ALPNProtocolName, Extension, ExtensionList

Field Summary

Fields
Modifier and Type Field and Description

static ExtensionType TYPE
The type (16) of the application_layer_protocol_negotiation extension.

Fields
Modifier and Type	Field and Description
`static ExtensionType`	`TYPE` The type (16) of the application_layer_protocol_negotiation extension.

Constructor Summary

Constructors
Constructor and Description
`ALPNProtocolNameList()` Creates a new ALPNProtocolNameList.
`ALPNProtocolNameList(ALPNProtocolName protocolName)` Creates an ALPNProtocolNameList for the given protocol name.
`ALPNProtocolNameList(ALPNProtocolName[] protocolNames)` Creates an ALPNProtocolNameList for the given protocol names.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.Object`	`clone()` Returns a clone of this protocol name list.
`boolean`	`contains(ALPNProtocolName protocolName)` Checks if this protocol name list contains the given protocol name.
`boolean`	`equals(java.lang.Object obj)` Checks if this protocol name list is equal to the given object.
`ALPNProtocolName[]`	`getProtocolNames()` Gets the protocol names included in this protocol name list.
`int`	`hashCode()` Gets a hash code of this protocol name list.
`void`	`setProtocolNames(ALPNProtocolName[] protocolNames)` Sets the protocol names of this protocol name list.
`int`	`size()` Gets the number of protocol names included in this protocol name list.
`java.lang.String`	`toString()` Gets a String representation of this protocol name list.

Methods inherited from class iaik.security.ssl.Extension
getAllowedProtocolVersions, 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 (16) of the application_layer_protocol_negotiation extension.
- Constructor Detail
  - ALPNProtocolNameList
```
public ALPNProtocolNameList()
```
    Creates a new ALPNProtocolNameList.
    Protocol names have to be added by calling method setProtocolNames or method addProtocolName.
  - ALPNProtocolNameList
```
public ALPNProtocolNameList(ALPNProtocolName[] protocolNames)
```
    Creates an ALPNProtocolNameList for the given protocol names.
    
    Parameters:
    
    protocolNames - the protocol names
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given ALPNProtocolNames array is empty or contains a null element
  - ALPNProtocolNameList
```
public ALPNProtocolNameList(ALPNProtocolName protocolName)
```
    Creates an ALPNProtocolNameList for the given protocol name.
    Additional protocol names may be added by calling method addProtocolName.
    
    Parameters:
    
    protocolName - the protocol name
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given ALPNProtocolName is null
- Method Detail
  - getProtocolNames
```
public ALPNProtocolName[] getProtocolNames()
```
    Gets the protocol names included in this protocol name list.
    
    Returns:
    
    the protocol names as array of ALPNProtocolName objects; the array maybe empty if no protocol names are included in the list
  - setProtocolNames
```
public void setProtocolNames(ALPNProtocolName[] protocolNames)
```
    Sets the protocol names of this protocol name list.
    
    Parameters:
    
    protocolNames - the protocol names to be set
    
    Throws:
    
    java.lang.IllegalArgumentException - if the given ALPNProtocolNames array is empty or contains a null element
  - size
```
public int size()
```
    Gets the number of protocol names included in this protocol name list.
    
    Returns:
    
    the number of protocol names included in this protocol name list
  - hashCode
```
public int hashCode()
```
    Gets a hash code of this protocol name list.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hash code of this protocol name list
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Checks if this protocol name list is equal to the given object.
    Two protocol name list are treated as equal if they contain the same ALPNProtocolName 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 ALPNProtocolNameList is equal to the given object, false if it is not equal to it
  - contains
```
public boolean contains(ALPNProtocolName protocolName)
```
    Checks if this protocol name list contains the given protocol name.
    
    Returns:
    
    true if this protocol name list contains the given protocol name, false if it does not contain it
  - clone
```
public java.lang.Object clone()
```
    Returns a clone of this protocol name list.
    
    Overrides:
    
    clone in class Extension
    
    Returns:
    
    a clone of this protocol name list
  - toString
```
public java.lang.String toString()
```
    Gets a String representation of this protocol name list.
    
    Specified by:
    
    toString in class Extension
    
    Returns:
    
    a String representation of the protocol name list

Class ALPNProtocolNameList

Field Summary

Constructor Summary

Method Summary

Methods inherited from class iaik.security.ssl.Extension

Methods inherited from class java.lang.Object

Field Detail

TYPE

Constructor Detail

ALPNProtocolNameList

ALPNProtocolNameList

ALPNProtocolNameList

Method Detail

getProtocolNames

setProtocolNames

size

hashCode

equals

contains

clone

toString