org.eclipse.californium.scandium.dtls.cipher

Class XECDHECryptography

java.lang.Object

org.eclipse.californium.scandium.dtls.cipher.XECDHECryptography

All Implemented Interfaces:

Destroyable

public final class XECDHECryptography
extends Object
implements Destroyable

A helper class to execute the XDH and ECDHE key agreement and key generation. Support X25519 and X448 with java 11. The API is simplified compared to the previous API of the deprecated ECDHECryptography. A ECDHE key exchange starts with negotiating a curve. The possible curves are listed at IANA Transport Layer Security (TLS) Parameters - TLS Supported Groups. The XECDHECryptography.SupportedGroup reflects that and offer the curve's Enum.name() (description in the IANA table) or XECDHECryptography.SupportedGroup.getId() (value in the IANA table). You may refer directly a member, e.g. XECDHECryptography.SupportedGroup.X25519, or get it by id XECDHECryptography.SupportedGroup.fromId(int) or by the curve-name XECDHECryptography.SupportedGroup.valueOf(String). Once you have a curve negotiated, you create a instance of XECDHECryptography(SupportedGroup) providing this curve as parameter. This will also create the ephemeral key-pair for the key exchange. After each peer creates such a instance (and so different key-pairs), the "public key" is sent to the other peer. Though the curve is transfered by it's XECDHECryptography.SupportedGroup.getId() (named curve), the public key itself is sent just by the getEncodedPoint() and not the ASN.1 encoding (Key.getEncoded()). Each peer converts the received encoded point of the other peer into a PublicKey and applies that to KeyAgreement.doPhase(java.security.Key, boolean). Outside of this class only the encoded point and the XECDHECryptography.SupportedGroup is used to do the key exchange. Access to the PrivateKey nor PublicKey is required outside.

 
 SupportedGroup group = SupportedGroup.X25519;
 
 // peer 1
 XECDHECryptography ecdhe1 = new XECDHECryptography(group);
 byte[] point1 = ecdhe1.getEncodedPoint();
 
 // send group + encoded point to other peer
 
 // peer 2, use received group 
 XECDHECryptography ecdhe2 = new XECDHECryptography(group);
 byte[] point2 = ecdhe2.getEncodedPoint();
 SecretKey secret2 = ecdhe2.generateSecret(point1);
 
 // send own encoded point back to first peer
 
 // peer 1
 SecretKey secret1 = ecdhe1.generateSecret(point2);
 
 

results in same secrets secret1 and secret2.

Since:

2.3

See Also:

RFC 7748

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XECDHECryptography.SupportedGroup The Supported Groups as defined in the official IANA Transport Layer Security (TLS) Parameters.

Field Summary

Fields

Modifier and Type	Field and Description
protected static org.slf4j.Logger	LOGGER

Constructor Summary

Constructors

Constructor and Description
XECDHECryptography(XECDHECryptography.SupportedGroup supportedGroup) Creates an ephemeral ECDH key pair for a given supported group.

Method Summary

Methods

Modifier and Type	Method and Description
void	destroy()
SecretKey	generateSecret(byte[] encodedPoint) Generate secret of key exchange.
byte[]	getEncodedPoint() Get public key as encoded point.
XECDHECryptography.SupportedGroup	getSupportedGroup() Get the supported group (curve) of this key exchange.
boolean	isDestroyed()

Methods inherited from class java.lang.Object

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

Field Detail

LOGGER

protected static final org.slf4j.Logger LOGGER

Constructor Detail

XECDHECryptography

public XECDHECryptography(XECDHECryptography.SupportedGroup supportedGroup)
                   throws GeneralSecurityException

Creates an ephemeral ECDH key pair for a given supported group.

Parameters:

supportedGroup - a curve as defined in the IANA Supported Groups Registry

Throws:

GeneralSecurityException - if the key pair cannot be created from the given supported group, e.g. because the JRE's crypto provider doesn't support the group

Method Detail

getSupportedGroup

public XECDHECryptography.SupportedGroup getSupportedGroup()

Get the supported group (curve) of this key exchange.

Returns:

supported group

getEncodedPoint

public byte[] getEncodedPoint()

Get public key as encoded point. The key exchange contains the used curve by its XECDHECryptography.SupportedGroup.getId(), therefore the ASN.1 Key.getEncoded() is not required.

Returns:

encoded point to be sent to the other peer

generateSecret

public SecretKey generateSecret(byte[] encodedPoint)
                         throws GeneralSecurityException

Generate secret of key exchange.

Parameters:

encodedPoint - the other peer's public key as encoded point

Returns:

the premaster secret

Throws:

NullPointerException - if encodedPoint is null.

GeneralSecurityException - if a crypt error occurred.

destroy

public void destroy()

Specified by:

destroy in interface Destroyable

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface Destroyable