Interface MessageAgreementContext

All Superinterfaces:

AgreementContext, AutoCloseable, Closeable, CryptoContext

All Known Implementing Classes:

GenericJcaMessageAgreementContext, HybridKexContext, KemMessageAgreementAdapter

public interface MessageAgreementContext
extends AgreementContext

Extension of AgreementContext for message-based key agreement protocols.

A MessageAgreementContext models algorithms where the two parties must exchange explicit protocol messages in addition to providing a public key. Examples include many KEM-based protocols where initiators send an encapsulation and responders decapsulate it to derive the shared secret.

Design

• For Diffie–Hellman–style agreements (e.g., X25519, ECDH), no explicit peer message is required. The peer’s public key is sufficient, and the message-related methods are unused.
• For KEM-based agreements (e.g., FrodoKEM, Kyber), the initiator generates an encapsulation ciphertext to send, and the responder must receive and decapsulate it. These flows rely on the setPeerMessage(byte[]) and getPeerMessage() methods.

Lifecycle

• Create a context via ZeroEchoSession#createContext(...) for the KeyUsage.AGREEMENT role.
• Initiators call getPeerMessage() to obtain the message to send to the responder, then invoke AgreementContext.deriveSecret().
• Responders call setPeerMessage(byte[]) to supply the received encapsulation, then invoke AgreementContext.deriveSecret().
• Finally, call CryptoContext.close() to release any internal resources.

Security considerations

• Shared secrets must be passed through a key derivation function (KDF) immediately after computation; raw bytes should be cleared from memory once used.
• Malformed peer messages must be rejected without leaking side-channel information (e.g., via constant-time checks).
• As with other CryptoContext types, instances are not guaranteed to be thread-safe.

Since:

1.0

Method Summary

Modifier and Type	Method	Description
byte[]	getPeerMessage()	Retrieves the peer message produced by this context.
void	setPeerMessage(byte[] message)	Supplies the peer’s message to this context.

Methods inherited from interface AgreementContext

deriveSecret, setPeerPublic

Methods inherited from interface CryptoContext

algorithm, close, key

Method Details

setPeerMessage

void setPeerMessage(byte[] message)

Supplies the peer’s message to this context.

Typically used by a responder in KEM-based protocols to provide the initiator’s encapsulation ciphertext. Diffie–Hellman contexts do not require peer messages and may throw if this method is called.

Parameters:

message - the peer’s message (e.g., encapsulated ciphertext), may be null to reset

Throws:

IllegalStateException - if the current role does not accept peer messages

getPeerMessage

byte[] getPeerMessage()

Retrieves the peer message produced by this context.

Typically used by an initiator in KEM-based protocols to obtain the encapsulation ciphertext that must be sent to the responder. Returns a clone to prevent accidental modification of internal state.

Returns:

a clone of the message to send (never null)

Throws:

IllegalStateException - if the current role does not produce messages