Class XdhAlgorithm

java.lang.Object

zeroecho.core.CryptoAlgorithm

zeroecho.core.alg.AbstractCryptoAlgorithm

zeroecho.core.alg.xdh.XdhAlgorithm

public final class XdhAlgorithm
extends AbstractCryptoAlgorithm

Algorithm definition for XDH (elliptic curve Diffie-Hellman) key agreement, backed by the JCA KeyAgreement API.

This algorithm integrates the XDH family (currently X25519, optionally X448 in supporting providers) into the ZeroEcho registry. It exposes the KeyUsage.AGREEMENT role and produces AgreementContext instances using GenericJcaAgreementContext, which delegates to the standard JCA KeyAgreement primitive (e.g., "XDH", "X25519").

Behavior

• Context type: AgreementContext constructed as a GenericJcaAgreementContext.
• Keys: Requires a local PrivateKey; the peer PublicKey must be supplied via AgreementContext.setPeerPublic(java.security.PublicKey) before calling AgreementContext.deriveSecret().
• Secret material: deriveSecret() returns the raw XDH shared secret. Protocols must apply a KDF before deriving symmetric keys or other session material.
• Providers: The context uses the default JCA provider lookup unless a provider is explicitly configured in GenericJcaAgreementContext (this algorithm passes null).
• Default spec: XdhSpec.X25519 is used when no explicit spec is provided.

Key material and builders

• Asymmetric key pairs are generated or imported via XdhKeyGenBuilder, parameterized by XdhSpec.
• The default builder spec is XdhSpec.X25519.
• Additional asymmetric builders are registered for XdhPublicKeySpec and XdhPrivateKeySpec to import encoded keys directly via the JCA KeyFactory for "XDH".

Example

// Discover the algorithm definition (via ServiceLoader or explicit construction)
CryptoAlgorithm xdh = new XdhAlgorithm();

// Generate key pairs
KeyPair a = xdh.asymmetricKeyPairGenerator(XdhSpec.class).generateKeyPair(XdhSpec.X25519);
KeyPair b = xdh.asymmetricKeyPairGenerator(XdhSpec.class).generateKeyPair(XdhSpec.X25519);

// Perform agreement on side A
AgreementContext ctxA = xdh.createContext(KeyUsage.AGREEMENT, a.getPrivate(), XdhSpec.X25519);
ctxA.setPeerPublic(b.getPublic());
byte[] secretA = ctxA.deriveSecret();

// Perform agreement on side B
AgreementContext ctxB = xdh.createContext(KeyUsage.AGREEMENT, b.getPrivate(), XdhSpec.X25519);
ctxB.setPeerPublic(a.getPublic());
byte[] secretB = ctxB.deriveSecret();

// secretA and secretB are equal; apply a KDF before using them

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
XdhAlgorithm()	Creates a new XDH algorithm registration.

Method Summary

Modifier and Type	Method	Description
List<ParameterSetDescriptor<? extends AlgorithmKeySpec>>	parameterSets()	Returns the discoverable parameter sets (or parameterized templates) supported by this algorithm.

Methods inherited from class AbstractCryptoAlgorithm

capability

Methods inherited from class CryptoAlgorithm

addCapability, asymmetricKeyPairGenerator, bindContext, createContext, displayName, id, keyOperations, listCapabilities, priority, privateKeyImporter, providerName, publicKeyImporter, registerAsymmetricKeyPairGenerator, registerPrivateKeyImporter, registerPublicKeyImporter, registerSymmetricKeyGenerator, registerSymmetricKeyImporter, requiresStatefulSigning, roles, supports, symmetricKeyGenerator, symmetricKeyImporter

Methods inherited from class Object

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

Constructor Details

XdhAlgorithm

public XdhAlgorithm()

Creates a new XDH algorithm registration.

This constructor performs the following registrations:

• Binds the KeyUsage.AGREEMENT role under AlgorithmFamily.AGREEMENT to produce AgreementContext instances with PrivateKey keys and XdhSpec specs, backed by GenericJcaAgreementContext with the JCA name from XdhSpec.keyAgreementName().
• Registers the XdhKeyGenBuilder for key pair generation with XdhSpec, defaulting to XdhSpec.X25519.
• Registers asymmetric key builders for XdhPublicKeySpec and XdhPrivateKeySpec to allow direct key import using KeyFactory ("XDH").

The bound contexts use the platform’s default JCA provider (provider = null).

Method Details

parameterSets

public List<ParameterSetDescriptor<? extends AlgorithmKeySpec>> parameterSets()

Description copied from class: CryptoAlgorithm

Returns the discoverable parameter sets (or parameterized templates) supported by this algorithm.

Callers (UIs, provisioning tools, policy engines) use this list to present users with valid, named key-generation options without prior knowledge of the concrete algorithm. Each entry is either a pre-built ParameterSetDescriptor.Concrete (ready spec) or a ParameterSetDescriptor.Template (user-supplied arguments produce the spec).

The default implementation returns an empty list. Algorithms with finite, enumerable parameter sets should override this method. Overrides must return immutable lists in stable order, with unique nonblank descriptor identifiers. Registry loading validates a snapshot; external providers remain responsible for maintaining the contract on subsequent calls. Implementations may use ParameterSetDescriptor.snapshot(List) to validate and copy their list.

Overrides:

parameterSets in class CryptoAlgorithm

Returns:

immutable list of parameter set descriptors; never null