Download the PHP package guycalledseven/php-ext-oqs without Composer

php-ext-oqs: post-quantum cryptography for PHP

Native PHP extension for post-quantum key encapsulation (ML-KEM) and signatures (ML-DSA, SLH-DSA), with liboqs built in.

php-ext-oqs is a native extension (no FFI) built on the C library liboqs from the Open Quantum Safe (OQS) project. The prebuilt binaries contain liboqs, so there is no system library to install.

Status: experimental. liboqs states that it is meant for research and prototyping and is not currently recommended for production use or for protecting sensitive data. The same applies to this extension, which has not been independently audited.

It provides an object-oriented API for the NIST-standardized PQC algorithms ML-KEM (Kyber), ML-DSA (Dilithium), SLH-DSA (SPHINCS+), and other algorithms supported by liboqs.

Influenced and inspired by great DEF CON 33 - Post Quantum Panic talk by K Karagiannis.

Features

• Key Encapsulation Mechanisms (KEMs): Securely generate and exchange shared secrets using algorithms like ML-KEM.
• Digital Signature Schemes (SIGs): Create and verify signatures with algorithms like ML-DSA.
• Modern API: A clean, object-oriented interface (Oqs\Kem, Oqs\Sig).
• Type Safe: Exposes algorithm identifiers as class constants (e.g., Oqs\Kem::ALG_ML_KEM_768) for safe, typo-free code and IDE autocompletion.
• Exception-based Error Handling: Throws Oqs\Exception for clear error handling.

Requirements

• PHP 8.1+ (prebuilt binaries: PHP 8.1 - 8.5, non-thread-safe, Linux glibc x86_64/arm64 and macOS arm64)
• Nothing else for the prebuilt binaries: liboqs is linked statically into oqs.so.
• Only when building from source: PHP development headers (php-dev, phpize), a C compiler, make, cmake, and liboqs.

Project files

• config.m4 - contains the code that will go into the configure script. checks for the oqs/oqs.h header and uses pkg-config to find the liboqs library, fallback to a hardcoded prefix
• php_oqs.h - header file containing C declarations and macro definitionsto be shared between several source files. defines the necessary object structs (php_oqs_kem_obj, php_oqs_sig_obj) and utility functions for fetching these objects
• oqs.c (module init + class registration) sets up the module entry, defines the custom object handlers, and registers the Oqs\Kem and Oqs\Sig classes with their respective methods
• sig.c (module init + class registration)
• kem.c (module init + class registration)
• tests - unit tests

Roadmap

• [x] Expose Algorithm Details
• [ ] Implement Dedicated Key Objects?
• [x] Expose Algorithm Names as Constants
• [x] Add Documentation on KDFs

Development Notes

• Safety: The extension has no module globals and no per-request state; the only state is the liboqs handle owned by each Oqs\Kem / Oqs\Sig object.
• Input validation: keys and ciphertexts of the wrong length are rejected with Oqs\Exception before they reach liboqs. Sig::verify() returns false for a signature of impossible length.
• Output Format: All cryptographic outputs (keys, ciphertexts, signatures) are returned as raw binary strings.
• liboqs Version: release 0.2.0 bundles liboqs 0.16.0 (each release names its bundled liboqs in CHANGELOG.md; php --ri oqs shows it at runtime). Because liboqs is linked statically, a liboqs security fix reaches you through a new release of this extension, not through a system update. The set of ALG_* constants follows whatever the linked liboqs enables, so it changes between liboqs releases (0.16.0 dropped the SPHINCS+-* names in favour of SLH-DSA, and added HQC, eFrodoKEM and MQOM).

Installation

Every release ships prebuilt binaries. They contain liboqs, so there is nothing to compile and no library to install.

Not covered yet: Alpine (musl), thread-safe (ZTS) PHP, Intel Macs, Windows. On those, build from source (below).

With PIE

PIE picks the right binary for your PHP, installs it and enables it:

If there is no binary for your platform, PIE falls back to a source build. That needs liboqs on the system and its location: pie install guycalledseven/php-ext-oqs --with-oqs=/usr/local.

Manual download

Then enable it by adding extension=oqs to a php.ini (php --ini lists the files in use), and check:

macOS only: a file downloaded with a browser is quarantined, clear that once with xattr -d com.apple.quarantine "$(php -r 'echo ini_get("extension_dir");')/oqs.so".

In a Dockerfile

Building from source

The release binaries are produced by ci/build.sh, which builds liboqs and the extension in a scratch directory, runs the tests and writes the zip to dist/:

The manual steps follow.

Debian:

macOS:

Build liboqs for static linking

Install liboqs into a prefix outside this directory. make clean deletes every *.a below the extension directory, which would silently remove a liboqs installed inside it.

build php extension

An explicit --with-oqs=DIR always wins over pkg-config. If DIR/lib/liboqs.a exists it is linked statically (-force_load on macOS, --whole-archive on Linux); configure fails if DIR contains no liboqs at all.

confirm if static

Check which liboqs actually got linked (headers and library versions must agree):

Build the extension with dynamically linked liboqs (optional)

Build liboqs

Build extension

Test and use

php -q --info

test in browser with phpinfo

macOS config after setup

A Stub & Docs Generator Script

Generate the IDE stub file:

Generate the Markdown file: (This command is unchanged)

Test if working

Debugging

macOS:

linux:

Important Security Point - clarification of the role of a KDF

KEM implementation returns a raw shared secret. In practice, this shared secret should almost never be used directly as an encryption key. It should be used as input to a Key Derivation Function (KDF) like HKDF to produce keys of the desired length and properties.

It is strongly recommended to use PHP's built-in hash_hkdf() function.

Quick start

3. Algorithm Details

You can retrieve detailed metadata about an algorithm using the details() method.

PHP API test

Comparation with similar php extension php-liboqs:

• Object-oriented API design vs static.
• Error handling with a custom Oqs\Exception.
• Complete function signatures (arginfo) for better IDE/static analysis support.
• An extra useful method (Kem::sizes()).

Global Constants

These constants provide version information for the underlying liboqs C library that the extension was compiled against.

Oqs\Kem Constants

Oqs\Sig Constants