Summary

Clarify the KeyAgreement API to specify that support for exchanges where 3 or more parties are involved is optional unless required by the standard key agreement algorithm.

Problem

The KeyAgreement API is designed to support exchanges with an arbitrary number of participants. The API, however, requires that providers implement the DiffieHellman algorithm. This is defined in the Java Security Standard Algorithm Names document [1] as the PKCS#3 standard [2], which only describes Diffie-Hellman exchanges in the context of two parties.

Solution

Add extra text to the KeyAgreement spec during the introductory paragraph to make three or more party KeyAgreement implementations optional, unless otherwise required by the algorithm's specification.

Specification

--- a/src/java.base/share/classes/javax/crypto/KeyAgreement.java
+++ b/src/java.base/share/classes/javax/crypto/KeyAgreement.java
@@ -52,7 +52,9 @@ import sun.security.jca.GetInstance.Instance;
  * with two other parties, {@code doPhase} needs to be called twice,
  * the first time setting the {@code lastPhase} flag to
  * {@code false}, and the second time setting it to {@code true}.
- * There may be any number of parties involved in a key exchange.
+ * There may be any number of parties involved in a key exchange.  However,
+ * support for key exchanges with more than two parties is implementation
+ * specific or as specified by the standard key agreement algorithm.
  *
  * <p> Every implementation of the Java platform is required to support the
  * following standard {@code KeyAgreement} algorithm:

Reference:

[1] https://docs.oracle.com/en/java/javase/15/docs/specs/security/standard-names.html#keyagreement-algorithms

[2] https://tools.ietf.org/html/rfc2631