document HPKE's mode_psk as unsupported

Author: overheadhunter

README.md

@@ -10,7 +10,7 @@
 - [RFC 7516 (JWE)](https://datatracker.ietf.org/doc/html/rfc7516) and [RFC 7518 (JWA)](https://datatracker.ietf.org/doc/html/rfc7518): compact and JSON serialization (incl. multiple recipients with per-recipient headers), `A256KW`, `PBES2-HS512+A256KW`, `ECDH-ES+A256KW` (P-256/P-384/P-521), `A128GCM`/`A256GCM`
 - [RFC 7515 (JWS)](https://datatracker.ietf.org/doc/html/rfc7515): compact serialization, `HS256`/`HS384`/`HS512`
 - [draft-ietf-jose-hpke-encrypt](https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-encrypt/): use of HPKE ([RFC 9180](https://www.rfc-editor.org/rfc/rfc9180) / [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/draft-ietf-hpke-hpke/)) with JWE, in both Key Management Modes —
-  Integrated Encryption (`HPKE-0`, `HPKE-1`, `HPKE-2`) and Key Encryption (`HPKE-0-KE`, `HPKE-1-KE`, `HPKE-2-KE`)
+  Integrated Encryption (`HPKE-0`, `HPKE-1`, `HPKE-2`) and Key Encryption (`HPKE-0-KE`, `HPKE-1-KE`, `HPKE-2-KE`); HPKE `mode_base` only, `mode_psk` (`psk_id`) is not supported yet
 - [draft-ietf-jose-hpke-pq-pqt](https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-pq-pqt/): PQ/T hybrid HPKE — `HPKE-9` and `HPKE-9-KE`, based on the MLKEM768-X25519 KEM and SHAKE256 KDF from [draft-ietf-hpke-pq](https://datatracker.ietf.org/doc/draft-ietf-hpke-pq/); the KEM is identical to X-Wing ([draft-connolly-cfrg-xwing-kem](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/))
 - [RFC 9964 (AKP JWKs)](https://www.rfc-editor.org/rfc/rfc9964): parsing Algorithm Key Pair JWKs for the PQ/T hybrid algorithms
 

src/main/java/org/cryptomator/jose/Alg.java

@@ -21,6 +21,8 @@
 /// A JWE algorithm, identified by its `alg` header value. It is split by direction into [EncryptionAlg] and [DecryptionAlg], and by JWE Key Management Mode
 /// into key management (protecting a content encryption key, [RFC 7518 Section 4](https://www.rfc-editor.org/rfc/rfc7518#section-4)) and Integrated Encryption
 /// ([draft-ietf-jose-hpke-encrypt Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-encrypt/#section-5), where HPKE encrypts the payload directly and there is no CEK).
+///
+/// All HPKE algorithms (`hpke0`…`hpke9`, `hpke0Ke`…`hpke9Ke`) run in HPKE `mode_base` only; `mode_psk` and the `psk_id` header parameter are not supported.
 public sealed interface Alg permits DecryptionAlg, EncryptionAlg {
 
 	/// The `alg` (algorithm) header parameter value identifying this algorithm.

src/main/java/org/cryptomator/jose/IntegratedDecryptionAlg.java

@@ -3,6 +3,7 @@
 import org.cryptomator.jose.alg.HPKEIntegratedAlg;
 
 /// Decryption for the Integrated Encryption Key Management Mode: HPKE decrypts the payload directly, without a separate content encryption key.
+/// Only HPKE `mode_base` is supported; a token with a `psk_id` header parameter (`mode_psk`) cannot be decrypted.
 public sealed interface IntegratedDecryptionAlg extends DecryptionAlg permits HPKEIntegratedAlg {
 
 }

src/main/java/org/cryptomator/jose/IntegratedEncryptionAlg.java

@@ -4,6 +4,7 @@
 
 /// HPKE Integrated Encryption as defined in [draft-ietf-jose-hpke-encrypt, Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-encrypt/#section-5):
 /// HPKE encrypts the payload directly — there is no CEK, no `enc` or `ek` header parameter, the JWE IV and Authentication Tag are empty, and there is exactly one recipient.
+/// Only HPKE `mode_base` is supported; `mode_psk` (`psk_id` header parameter) is not.
 public sealed interface IntegratedEncryptionAlg extends EncryptionAlg permits HPKEIntegratedAlg {
 
 	/// Encrypts the payload in a single HPKE operation.

src/main/java/org/cryptomator/jose/alg/HPKEIntegratedAlg.java

@@ -14,6 +14,9 @@
 /// HPKE Integrated Encryption as defined in [draft-ietf-jose-hpke-encrypt, Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-encrypt/#section-5):
 /// HPKE encrypts the payload directly, the encapsulated secret travels in the JWE Encrypted Key field, and the JWE Protected Header
 /// (as well as an optional JWE AAD) is bound to the ciphertext via the HPKE `aad` parameter.
+///
+/// Only HPKE `mode_base` is supported. The draft also allows `mode_psk`, signalled by the `psk_id` header parameter; a token carrying `psk_id` is not understood
+/// (it is rejected when listed in `crit`, and otherwise fails to decrypt because the PSK never enters the key schedule).
 public final class HPKEIntegratedAlg implements IntegratedEncryptionAlg, IntegratedDecryptionAlg {
 
 	private static final byte[] EMPTY = new byte[0];

src/main/java/org/cryptomator/jose/alg/HPKEKeyEncryptionAlg.java

@@ -16,6 +16,9 @@
 
 /// HPKE Key Encryption as defined in [draft-ietf-jose-hpke-encrypt, Section 6](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-encrypt/#section-6):
 /// HPKE seals the CEK, the encapsulated secret travels in the `ek` header parameter, and the content is encrypted with a regular [org.cryptomator.jose.Enc].
+///
+/// Only HPKE `mode_base` is supported. The draft also allows `mode_psk`, signalled by the `psk_id` header parameter; a token carrying `psk_id` is not understood
+/// (it is rejected when listed in `crit`, and otherwise fails to decrypt because the PSK never enters the key schedule).
 public final class HPKEKeyEncryptionAlg extends AbstractKeyAlg {
 
 	private static final byte[] SEPARATOR = {(byte) 0xFF};

src/main/java/org/cryptomator/jose/hpke/HPKE.java

@@ -15,7 +15,8 @@
 import java.security.PublicKey;
 
 /// An HPKE ciphersuite (KEM, KDF, AEAD) as defined in [draft-ietf-hpke-hpke](https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-03), offering the base mode
-/// sender and recipient setup. The static factory methods provide the suites registered for JOSE in
+/// sender and recipient setup. Only `mode_base` is implemented: `mode_psk` (a pre-shared key authenticating the sender, draft-ietf-hpke-hpke Section 5.1.2) as
+/// well as `mode_auth` and `mode_auth_psk` are not supported, although the key schedule already accepts the PSK inputs. The static factory methods provide the suites registered for JOSE in
 /// [draft-ietf-jose-hpke-encrypt](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-encrypt/) and
 /// [draft-ietf-jose-hpke-pq-pqt](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-pq-pqt/); `baseName` is the JOSE `alg` name of the suite's
 /// Integrated Encryption variant (the Key Encryption variant appends `-KE`).
@@ -132,8 +133,9 @@ public record Sender(byte[] enc, Context context) {
 	/// @param mode A one-byte value indicating the HPKE mode, defined in Table 1.
 	/// @param sharedSecret A KEM shared secret generated for this transaction.
 	/// @param info Application-supplied information (optional).
-	/// @param psk A pre-shared key (PSK) held by both the sender and the recipient (optional).
-	/// @param pskId An identifier for the PSK (optional).
+	/// @param psk A pre-shared key (PSK) held by both the sender and the recipient; must be empty, as only `mode_base` is supported
+	/// @param pskId An identifier for the PSK; must be empty, as only `mode_base` is supported
+	/// @throws UnsupportedOperationException for any mode other than `mode_base`
 	// visible for testing
 	Context keySchedule(byte mode, SecretKey sharedSecret, byte[] info, byte[] psk, byte[] pskId) {
 		if ((psk.length == 0) != (pskId.length == 0)) {
@@ -143,7 +145,7 @@ Context keySchedule(byte mode, SecretKey sharedSecret, byte[] info, byte[] psk,
 			throw new IllegalArgumentException("PSK input provided when not needed");
 		}
 		if (mode != 0x00) {
-			throw new UnsupportedOperationException("Only mode_base is currently supported");
+			throw new UnsupportedOperationException("Only mode_base is supported (no mode_psk, mode_auth or mode_auth_psk)");
 		}
 
 		var derived = kdf.combineSecrets(mode, sharedSecret, info, psk, pskId, suiteId, "AES", aead.nk, aead.nn);