README

Installation

composer require paragonie/hpke

Usage

Instantiating HPKE

First, you need to decide on an HPKE ciphersuite. You can build these yourself by component, or use the standard modes that ship with RFC 9180:

• DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM
• DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20Poly1305
• DHKEM(P-256, HKDF-SHA256), HKDF-SHA256, AES-128-GCM
• DHKEM(P-256, HKDF-SHA256), HKDF-SHA512, AES-128-GCM
• DHKEM(P-256, HKDF-SHA256), HKDF-SHA256, ChaCha20Poly1305
• DHKEM(P-521, HKDF-SHA512), HKDF-SHA512, AES-256-GCM

Additional Post-Quantum KEMs:

• MLKEM768-X25519, HKDF-SHA256, AES-128-GCM
• ML-KEM-768, HKDF-SHA256, AES-128-GCM
• ML-KEM-1024, HKDF-SHA256, AES-256-GCM
• MLKEM768-X25519, HKDF-SHA256, ChaCha20Poly1305
• ML-KEM-768, HKDF-SHA256, ChaCha20Poly1305
• ML-KEM-1024, HKDF-SHA256, ChaCha20Poly1305

Tip

We recommend enabling opcache and JIT if you cannot install the pqcrypto extension.

To instantiate one of these ciphersuites, you can use the Factory class, like so:

<?php
use ParagonIE\HPKE\Factory;

// Either approach will work fine.
$ciphersuite = Factory::init('DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM');
$otherCS = Factory::dhkem_p256sha256_hkdf_sha256_chacha20poly1305();

Generating and Managing Key Pairs

Once you've instantiated your ciphersuite, you can now use it to generate/load keys.

<?php
use ParagonIE\HPKE\HPKE;
use ParagonIE\HPKE\KEM\DHKEM\{DecapsKey, EncapsKey};
use Mdanter\Ecc\Serializer\{
    PublicKey\PemPublicKeySerializer,
    PrivateKey\PemPrivateKeySerializer
};

/** @var HPKE $hpke */

/**
 * @var EncapsKey $public
 * @var DecapsKey $secret
 */
[$secret, $public] = $hpke->kem->generateKeys();

// You can now use Easy-ECC or PHP-ECC to manage these keys:
$decapsulationKeyToSaveToDisk = (new PemPrivateKeySerializer())
    ->serialize($secret->toPrivateKey());

$encapsKeySharePublicly = (new PemPublicKeySerializer())
    ->serialize($public->toPublicKey());

Setting Up Encryption Contexts

To set up an encryption context, simply use the setupBaseSender() and setupBaseReceiver() APIs.

<?php
use ParagonIE\HPKE\HPKE;
use ParagonIE\HPKE\KEM\DHKEM\{DecapsKey, EncapsKey};

/** 
 * @var HPKE $hpke 
 * @var EncapsKey $public
 * @var DecapsKey $secret
 */
 
const INFO = 'my custom protocol name';

// On one side
[$enc, $sender] = $hpke->setupBaseSender($public, INFO);

// On te other
$receiver = $hpke->setupBaseReceiver($secret, $enc, INFO);

// And now you can encrypt/decrypt:
$encrypted1 = $sender->seal('test message', 'first message AAD');
$decrypted1 = $receiver->open($encrypted1, 'first message AAD');

// The sequence is advanced automatically by our API

One-Shot Encryption API

<?php
use ParagonIE\HPKE\HPKE;
use ParagonIE\HPKE\KEM\DHKEM\{DecapsKey, EncapsKey};

/** 
 * @var HPKE $hpke 
 * @var EncapsKey $public
 * @var DecapsKey $secret
 */
 
const INFO = 'my custom protocol name';

// Sending (encryption)
$sealed = $hpke->sealBase($public, 'plaintext message', 'aad', INFO);

// Receiving (decryption)
$opened = $hpke->openBase($secret, $sealed, 'aad', INFO);