public class KeyShare extends Extension implements java.lang.Cloneable
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.
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:
ffdhe2048
ffdhe3072
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.Extension
,
ExtensionList
Modifier and Type | Class and Description |
---|---|
static class |
KeyShare.KeyShareEntry
Implements the KeyShareEntry struct.
|
Modifier and Type | Field and Description |
---|---|
static ExtensionType |
TYPE
The type (10) of the key_share extension.
|
Constructor and Description |
---|
KeyShare()
Default Constructor.
|
KeyShare(KeyShare.KeyShareEntry[] keyShareEntries)
Creates a KeyShare extension with the given KeyShareEntry list.
|
Modifier and Type | Method and Description |
---|---|
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.
|
getAllowedProtocolVersions, getExtensionType, getName, getType, setCritical
public static final ExtensionType TYPE
public KeyShare()
public KeyShare(KeyShare.KeyShareEntry[] keyShareEntries) throws java.lang.IllegalArgumentException
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.
keyShareEntries
- the KeyShareEntry listjava.lang.IllegalArgumentException
- if any of the given KeyShare entries
share the same NamedGrouppublic static KeyShare createKeyShare(SupportedGroups supportedGroups) throws java.security.InvalidKeyException
For any group contained in the given SupportedGroups extension a KeyShare entry is created for the new KeyShare extension.
supportedGroups
- the SupportedGroups extension from which to
build a KeyShare extensionjava.security.InvalidKeyException
- if an error occurs when generating the
key_exchange information for any of the
KeyShare to be createdpublic NamedGroup[] getNamedGroupList()
null
or empty if
no KeyShareEntry is included in this extensionpublic java.lang.Object clone()