iaik.security.ssl
Class KeyShare

java.lang.Object
  iaik.security.ssl.Extension
      iaik.security.ssl.KeyShare

All Implemented Interfaces:

java.lang.Cloneable

public class KeyShare
extends Extension
implements java.lang.Cloneable

This class implements the TLS 1.3 KeyShare (key_share) TLS extension as specified by RFC 8446.

TLS 1.3 defines the KeyShare extension as list of KeyShareEntries or NamedGroup (see RFC 8446), depending on if the KeyShare extension is sent within a ClientHello or ServerHello or HelloRetryRequest message:

  struct {
      KeyShareEntry client_shares<0..2^16-1>;
  } KeyShareClientHello;
  
  
  struct {
      NamedGroup selected_group;
  } KeyShareHelloRetryRequest;
   
   
  struct {
      KeyShareEntry server_share;
  } KeyShareServerHello;
 

When sent within the ClientHello message the KeyShare extension maybe empty (to tell the server to respond with a HelloRetryRequest message indicating the named group to be used) or may contain a list of KeyShareEntry elements suggesting which groups and key exchange values may be used. The KeyShareEntry list has to be built in accordance to the list of NamedGroup elements sent within the SupportedGroups extensions. The KeyShareEntry list may not contain a KeyShareEntry for any group contained in the SupportedGroups extension, but is not allowed to contain a KeyShareEntry for a group that is not included in the SupportedGroups extension.
A KeyShare extension included in the ServerHello message at any time does contain one KeyShareEntry element only.

Generally an (client or server side) application may not have to take care about the KeyShare extension because iSaSiLk uses default KeyShare values if no KeyShare extension has been set by the application. By default iSaSiLk uses the following groups -- if cryptographically supported -- and generates KeyShareEntries for them:

Named Curves:
• secp256r1
• secp384r1
• secp521r1

FFDHE Groups:

ffdhe2048

ffdhe3072

An application that wants to use different than (or additional to) the default groups/KeyShareEntries may explicitly create a SupportedGroups and KeyShare entries and add the groups/KeyShareEntries that shall be supported. The following example creates SupportedGroups and KeyShare extensions for the TLS 1.3 recommended elliptic curve groups secp256r1 and x25519:

 // the extension list
 ExtensionList extensions = new ExtensionList();
 
 // SupportedGroups extension
 NamedGroup[] namedGroups = { 
      SupportedGroups.NC_PRIME_SECP256R1,
      SupportedGroups.NC_X25519 };
 SupportedGroups supportedGroups = new SupportedGroups(namedGroups);
 extensions.addExtension(supportedGroups);
 
 // KeyShare extension
  KeyShareEntry[] keyShareEntries = {
    new KeyShareEntry(SupportedEllipticCurves.NC_PRIME_SECP256R1),
    new KeyShareEntry(SupportedEllipticCurves.NC_X25519),
 };
 KeyShare keyShare = new KeyShare(keyShareEntries);
 extensions.addExtension(keyShare);
 
 // add extensions to SSLContext
 SSLContext sslContext = ...;
 sslContext.setExtensions(extensions);
 

Instead of explicitly creating the KeyShare extension you also can create the SupportedGroups extension only and then use method createKeyShare to let iSaSiLk create the KeyShare extension from the supported groups:

 KeyShare keyShare = KeyShare.createKeyShare(supportedGroups);
 

When using the default constructor of a SupportedGroups extension a SupportedGroups extension with the default groups -- if cryptographically supported -- secp256r1 ,secp384r1, secp521r1, ffdhe2048 and ffdhe3072 is created. However, when using the constructor of a KeyShare extension an empty KeyShare extension without any key share entries is created. Creating an empty KeyShare extension may be meaningful at the client side only to tell the server to respond with an HellyRetryRequest containing the group the server wants to use for the upcoming session. Using an empty KeyShare extension on the server side does not make any sense.

Version:

File Revision 51

See Also:

Extension, ExtensionList

Nested Class Summary

static class

KeyShare.KeyShareEntry Implements the KeyShareEntry struct.

Field Summary

static ExtensionType

TYPE The type (10) of the key_share extension.

Constructor Summary

KeyShare()
Default Constructor.

KeyShare(KeyShare.KeyShareEntry[] keyShareEntries)
Creates a KeyShare extension with the given KeyShareEntry list.

Method Summary

java.lang.Object	clone() Returns a clone of this KeyShare extension object.
static KeyShare	createKeyShare(SupportedGroups supportedGroups) Creates a KeyShare extension that corresponds to the group entries of the given SupportedGroups extension.
NamedGroup[]	getNamedGroupList() Gets the list of supported groups used by the entries of this KeyShare extension.
java.lang.String	toString() Gets a String representation of this KeyShare object.

Methods inherited from class iaik.security.ssl.Extension

getAllowedProtocolVersions, getExtensionType, getName, getType, setCritical

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final ExtensionType TYPE

The type (10) of the key_share extension.

Constructor Detail

KeyShare

public KeyShare()

Default Constructor.
This constructor may be used by the client to send an empty KeyShare extension within the ClientHello message to tell the server to answer with a HelloRetryMessage to select the group to be used.

KeyShare

public KeyShare(KeyShare.KeyShareEntry[] keyShareEntries)
         throws java.lang.IllegalArgumentException

Creates a KeyShare extension with the given KeyShareEntry list.

This constructor is used on the client side to send the KeyShare extension within the ClientHello message or on the server side to include a KeyShare extension (containing only one KeyShareEntry) in the ServerHello message.
If the Client calls constructor with null or an empty list as argument, the client will send an empty KeyShare extension within the ClientHello message to tell the server to answer with a HelloRetryMessage to select the group to be used.

Parameters:

keyShareEntries - the KeyShareEntry list

Throws:

java.lang.IllegalArgumentException - if any of the given KeyShare entries share the same NamedGroup

Method Detail

createKeyShare

public static KeyShare createKeyShare(SupportedGroups supportedGroups)
                               throws java.security.InvalidKeyException

Creates a KeyShare extension that corresponds to the group entries of the given SupportedGroups extension.

For any group contained in the given SupportedGroups extension a KeyShare entry is created for the new KeyShare extension.

Parameters:

supportedGroups - the SupportedGroups extension from which to build a KeyShare extension

Returns:

the new KeyShareExtension

Throws:

java.security.InvalidKeyException - if an error occurs when generating the key_exchange information for any of the KeyShare to be created

getNamedGroupList

public NamedGroup[] getNamedGroupList()

Gets the list of supported groups used by the entries of this KeyShare extension.

Returns:

the list of supported groups used by the entries of this KeyShare extension as array of NamedGroup objects; the array maybe null or empty if no KeyShareEntry is included in this extension

clone

public java.lang.Object clone()

Returns a clone of this KeyShare extension object.

Overrides:

clone in class Extension

Returns:

a clone of this KeyShare extension object

toString

public java.lang.String toString()

Gets a String representation of this KeyShare object.

Specified by:

toString in class Extension

Returns:

a String representation of the KeyShare object