Interface AgreementContext

All Superinterfaces:

AutoCloseable, Closeable, CryptoContext

All Known Subinterfaces:

MessageAgreementContext

All Known Implementing Classes:

GenericJcaAgreementContext, GenericJcaMessageAgreementContext, HybridKexContext, KemMessageAgreementAdapter

public non-sealed interface AgreementContext
extends CryptoContext

Context for performing key agreement protocols using a private key and a peer's public key.

An AgreementContext encapsulates the state needed to derive a shared secret between two parties. It is created by a CryptoAlgorithm for the KeyUsage.AGREEMENT role. Typical implementations include elliptic-curve Diffie–Hellman (ECDH) and X25519/X448.

Lifecycle

• Create a context via ZeroEchoSession#createContext(...) for the AGREEMENT role.
• Call setPeerPublic(PublicKey) with the peer’s public key.
• Invoke deriveSecret() once to compute the raw shared secret.
• Dispose of the context with CryptoContext.close() to release any internal resources.

Security considerations

• Shared secrets are returned as raw byte arrays; callers should immediately feed them into a key-derivation function (KDF) and clear the array when done.
• Most agreements require validated public keys. Implementations should enforce curve/mathematical constraints and reject invalid points.
• Contexts are not generally thread-safe; do not share a single instance across concurrent threads.

Since:

1.0

Method Summary

Modifier and Type	Method	Description
byte[]	deriveSecret()	Performs the key agreement and returns the derived raw shared secret.
void	setPeerPublic(PublicKey peer)	Sets the peer's public key to be used in the key agreement.

Methods inherited from interface CryptoContext

algorithm, close, key

Method Details

setPeerPublic

void setPeerPublic(PublicKey peer)

Sets the peer's public key to be used in the key agreement.

This method must be called before deriveSecret(). Implementations may validate that the provided key is suitable for the underlying algorithm (e.g., curve membership checks).

Parameters:

peer - the peer's public key

Throws:

NullPointerException - if peer is null

IllegalArgumentException - if peer is not valid for this algorithm

deriveSecret

byte[] deriveSecret()

Performs the key agreement and returns the derived raw shared secret.

The returned byte array contains secret material and should be used immediately in a KDF. Callers are responsible for clearing or zeroizing the array after use to reduce the risk of leakage.

Returns:

a new byte array containing the raw shared secret

Throws:

IllegalStateException - if the peer public key has not been set before invocation