Implement RFC 9180 HPKE sender asymmetric key authentication mode

We already have support for the `base` unauthenticated mode, so this
just adds the `auth` mode where the sender's key pair is added to
the ECDH shared key derivation mix. This ensures that a message may
only be successfully opened if the sender was in possession of the
private key (`skS`) corresponding to the expected public key (`pkS`).

3 files changed, 132 insertions, 5 deletions

diff --git a/security-utils/src/main/java/com/yahoo/security/hpke/DHKemX25519HkdfSha256.java b/security-utils/src/main/java/com/yahoo/security/hpke/DHKemX25519HkdfSha256.java
index 8f6dffcb9c2..91f92bf3b33 100644
--- a/security-utils/src/main/java/com/yahoo/security/hpke/DHKemX25519HkdfSha256.java
+++ b/security-utils/src/main/java/com/yahoo/security/hpke/DHKemX25519HkdfSha256.java
@@ -108,6 +108,40 @@ final class DHKemX25519HkdfSha256 implements Kem {
      * Section 4.1 DH-Based KEM (DHKEM):
      *
      * <pre>
+     * def AuthEncap(pkR, skS):
+     *   skE, pkE = GenerateKeyPair()
+     *   dh = concat(DH(skE, pkR), DH(skS, pkR))
+     *   enc = SerializePublicKey(pkE)
+     *
+     *   pkRm = SerializePublicKey(pkR)
+     *   pkSm = SerializePublicKey(pk(skS))
+     *   kem_context = concat(enc, pkRm, pkSm)
+     *
+     *   shared_secret = ExtractAndExpand(dh, kem_context)
+     *   return shared_secret, enc
+     * </pre>
+     */
+    @Override
+    public EncapResult authEncap(XECPublicKey pkR, XECPrivateKey skS) {
+        var kpE = keyPairGen.get();
+        var skE = (XECPrivateKey)kpE.getPrivate();
+        var pkE = (XECPublicKey)kpE.getPublic();
+
+        byte[] dh = concat(KeyUtils.ecdh(skE, pkR), KeyUtils.ecdh(skS, pkR));
+        byte[] enc = serializePublicKey(pkE);
+
+        byte[] pkRm = serializePublicKey(pkR);
+        byte[] pkSm = serializePublicKey(KeyUtils.extractX25519PublicKey(skS));
+        byte[] kemContext = concat(enc, pkRm, pkSm);
+
+        byte[] sharedSecret = extractAndExpand(dh, kemContext);
+        return new EncapResult(sharedSecret, enc);
+    }
+
+    /**
+     * Section 4.1 DH-Based KEM (DHKEM):
+     *
+     * <pre>
      * def Decap(enc, skR):
      *   pkE = DeserializePublicKey(enc)
      *   dh = DH(skR, pkE)
@@ -130,4 +164,31 @@ final class DHKemX25519HkdfSha256 implements Kem {
         return extractAndExpand(dh, kemContext);
     }
 
+    /**
+     * Section 4.1 DH-Based KEM (DHKEM):
+     *
+     * <pre>
+     * def AuthDecap(enc, skR, pkS):
+     *   pkE = DeserializePublicKey(enc)
+     *   dh = concat(DH(skR, pkE), DH(skR, pkS))
+     *
+     *   pkRm = SerializePublicKey(pk(skR))
+     *   pkSm = SerializePublicKey(pkS)
+     *   kem_context = concat(enc, pkRm, pkSm)
+     *
+     *   shared_secret = ExtractAndExpand(dh, kem_context)
+     *   return shared_secret
+     * </pre>
+     */
+    public byte[] authDecap(byte[] enc, XECPrivateKey skR, XECPublicKey pkS) {
+        var pkE = deserializePublicKey(enc);
+        byte[] dh = concat(KeyUtils.ecdh(skR, pkE), KeyUtils.ecdh(skR, pkS));
+
+        byte[] pkRm = serializePublicKey(KeyUtils.extractX25519PublicKey(skR));
+        byte[] pkSm = serializePublicKey(pkS);
+        byte[] kemContext = concat(enc, pkRm, pkSm);
+
+        return extractAndExpand(dh, kemContext);
+    }
+
 }
diff --git a/security-utils/src/main/java/com/yahoo/security/hpke/Hpke.java b/security-utils/src/main/java/com/yahoo/security/hpke/Hpke.java
index 51f41ab7da7..98dc739f039 100644
--- a/security-utils/src/main/java/com/yahoo/security/hpke/Hpke.java
+++ b/security-utils/src/main/java/com/yahoo/security/hpke/Hpke.java
@@ -39,9 +39,10 @@ import static com.yahoo.security.hpke.LabeledKdfUtils.labeledExtractForSuite;
  * <ul>
  *     <li>Only the <code>DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM</code> ciphersuite is
  *         implemented. This is expected to be a good default choice for any internal use of this class.</li>
- *     <li>Only the "base mode" (unauthenticated sender) is supported, i.e. no PSK support and no
- *         secret exporting. This implementation is only expected to be used for anonymous one-way
- *         encryption.</li>
+ *     <li>Only the "base" (unauthenticated sender) and "auth" (authentication using an asymmetric
+ *         key) modes are supported, i.e. no PSK support and no secret exporting. This implementation
+ *         is only expected to be used for one-way encryption (possibly authenticated, if using the
+ *         "auth" mode).</li>
  *     <li>The API only offers single-shot encryption to keep anyone from being tempted to
  *         use it to build their own multi-message protocol on top. This entirely avoids the
  *         risk of nonce reuse caused by accidentally repeating sequence numbers.</li>
@@ -253,6 +254,37 @@ public final class Hpke {
         return new ContextR(keySchedule(MODE_BASE, sharedSecret, info, DEFAULT_PSK, DEFAULT_PSK_ID));
     }
 
+    /**
+     * Section 5.1.3. Authentication Using an Asymmetric Key:
+     *
+     * <pre>
+     * def SetupAuthS(pkR, info, skS):
+     *   shared_secret, enc = AuthEncap(pkR, skS)
+     *   return enc, KeyScheduleS(mode_auth, shared_secret, info,
+     *                            default_psk, default_psk_id)
+     * </pre>
+     */
+    ContextS setupAuthS(XECPublicKey pkR, byte[] info, XECPrivateKey skS) {
+        var encapped = kem.authEncap(pkR, skS);
+        return new ContextS(encapped.enc(),
+                keySchedule(MODE_AUTH, encapped.sharedSecret(), info, DEFAULT_PSK, DEFAULT_PSK_ID));
+    }
+
+    /**
+     * Section 5.1.3. Authentication Using an Asymmetric Key:
+     *
+     * <pre>
+     * def SetupAuthR(enc, skR, info, pkS):
+     *   shared_secret = AuthDecap(enc, skR, pkS)
+     *   return KeyScheduleR(mode_auth, shared_secret, info,
+     *                       default_psk, default_psk_id)
+     * </pre>
+     */
+    ContextR setupAuthR(byte[] enc, XECPrivateKey skR, byte[] info, XECPublicKey pkS) {
+        byte[] sharedSecret = kem.authDecap(enc, skR, pkS);
+        return new ContextR(keySchedule(MODE_AUTH, sharedSecret, info, DEFAULT_PSK, DEFAULT_PSK_ID));
+    }
+
     public record Sealed(byte[] enc, byte[] ciphertext) {}
 
     /**
@@ -286,6 +318,13 @@ public final class Hpke {
         return new Sealed(encAndCtx.enc, ct);
     }
 
+    public Sealed sealAuth(XECPublicKey pkR, byte[] info, byte[] aad, byte[] pt, XECPrivateKey skS) {
+        var encAndCtx = setupAuthS(pkR, info, skS);
+        var base = encAndCtx.base;
+        byte[] ct = aead.seal(base.key(), base.nonce(), aad, pt);
+        return new Sealed(encAndCtx.enc, ct);
+    }
+
     /**
      * Section 6.1 Encryption and Decryption:
      *
@@ -316,4 +355,11 @@ public final class Hpke {
         return aead.open(base.key(), base.nonce(), aad, ct);
     }
 
+    public byte[] openAuth(byte[] enc, XECPrivateKey skR, byte[] info, byte[] aad, byte[] ct, XECPublicKey pkS) {
+        var ctx = setupAuthR(enc, skR, info, pkS);
+        var base = ctx.base;
+        // TODO wrap any exceptions in OpenError et al?
+        return aead.open(base.key(), base.nonce(), aad, ct);
+    }
+
 }
diff --git a/security-utils/src/main/java/com/yahoo/security/hpke/Kem.java b/security-utils/src/main/java/com/yahoo/security/hpke/Kem.java
index 99c019a9d0b..55bb2e0e662 100644
--- a/security-utils/src/main/java/com/yahoo/security/hpke/Kem.java
+++ b/security-utils/src/main/java/com/yahoo/security/hpke/Kem.java
@@ -18,22 +18,42 @@ public interface Kem {
 
     /**
      * Section 4 Cryptographic Dependencies:
-     *
+     * <blockquote>
      * "Randomized algorithm to generate an ephemeral, fixed-length symmetric key
      * (the KEM shared secret) and a fixed-length encapsulation of that key that can
      * be decapsulated by the holder of the private key corresponding to <code>pkR</code>"
+     * </blockquote>
      */
     EncapResult encap(XECPublicKey pkR);
 
     /**
+     * Section 4: Cryptographic Dependencies:
+     * <blockquote>
+     * "Same as <code>Encap()</code>, and the outputs encode an assurance that the KEM
+     * shared secret was generated by the holder of the private key <code>skS</code>."
+     * </blockquote>
+     */
+    EncapResult authEncap(XECPublicKey pkR, XECPrivateKey skS);
+
+    /**
      * Section 4 Cryptographic Dependencies:
-     *
+     * <blockquote>
      * "Deterministic algorithm using the private key <code>skR</code> to recover the
      * ephemeral symmetric key (the KEM shared secret) from its encapsulated
      * representation <code>enc</code>."
+     * </blockquote>
      */
     byte[] decap(byte[] enc, XECPrivateKey skR);
 
+    /**
+     * Section 4 Cryptographic Dependencies:
+     * <blockquote>
+     * "Same as <code>Decap()</code>, and the recipient is assured that the KEM shared
+     * secret was generated by the holder of the private key <code>skS</code>."
+     * </blockquote>
+     */
+    byte[] authDecap(byte[] enc, XECPrivateKey skR, XECPublicKey pkS);
+
     /** The length in bytes of a KEM shared secret produced by this KEM. */
     short nSecret();
     /** The length in bytes of an encapsulated key produced by this KEM. */