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 56

See Also:

Extension, ExtensionList