https://github.com/paragonie/hpke-php

PHP Implementation of RFC 9180 (Hybrid Public-Key Encryption)
https://github.com/paragonie/hpke-php

Last synced: about 2 months ago
JSON representation

PHP Implementation of RFC 9180 (Hybrid Public-Key Encryption)

• Host: GitHub
• URL: https://github.com/paragonie/hpke-php
• Owner: paragonie
• License: isc
• Created: 2025-01-28T06:48:59.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2026-04-08T21:58:39.000Z (2 months ago)
• Last Synced: 2026-04-08T23:32:36.374Z (2 months ago)
• Language: PHP
• Size: 1.69 MB
• Stars: 8
• Watchers: 4
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Hybrid Public-Key Encryption (HPKE, RFC 9180) for PHP

[![Build Status](https://github.com/paragonie/hpke-php/actions/workflows/test.yml/badge.svg)](https://github.com/paragonie/hpke-php/actions)

[![Latest Stable Version](https://poser.pugx.org/paragonie/hpke/v/stable)](https://packagist.org/packages/paragonie/hpke)

[![Total Downloads](https://poser.pugx.org/paragonie/hpke/downloads)](https://packagist.org/packages/paragonie/hpke)

[![Latest Unstable Version](https://poser.pugx.org/paragonie/hpke/v/unstable)](https://packagist.org/packages/paragonie/hpke)

[![License](https://poser.pugx.org/paragonie/hpke/license)](https://packagist.org/packages/paragonie/hpke)

## Installation

```terminal

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](https://www.rfc-editor.org/rfc/rfc9180.html#name-iana-considerations):

* 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](https://github.com/paragonie/ext-pqcrypto).

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

```php

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

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

sealBase($public, 'plaintext message', 'aad', INFO);

// Receiving (decryption)

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

```