# Contractless PHP Crypto Modules

These native PHP modules provide the cryptography required by
`php-contractless-rpc`:

- Skein-256 hashing through PHP-Skein-Hash
- Contractless-compatible Falcon-512 signing and verification through liboqs

Contractless uses fixed 666-byte Falcon signatures and a specific FN-DSA raw
message format. The included liboqs-php patch adds the SHAKE256 operation needed
to reproduce that format exactly.

## Supported Environment

The automated installation currently supports 64-bit Debian and Ubuntu systems.
This includes Ubuntu running through WSL.

Native modules are tied to the operating system, CPU architecture, and PHP
extension API. They should normally be compiled on the machine where they will
run.

## Build Requirements

```bash
sudo apt update
sudo apt install -y \
  php-cli php-dev \
  swig cmake ninja-build \
  build-essential git pkg-config libssl-dev
```

## Build

```bash
chmod +x build-linux.sh install-linux.sh
./build-linux.sh
```

This downloads and compiles:

- A minimal liboqs build containing `Falcon-padded-512`
- The patched liboqs-php extension
- The PHP-Skein-Hash extension

Building does not install or enable the modules.

## Install

After a successful build:

```bash
sudo ./install-linux.sh
```

The installer copies both modules into the active PHP extension directory,
creates `contractless-crypto.ini`, enables it through `phpenmod`, and verifies
that PHP can see both modules.

Confirm the installation manually:

```bash
php -m | grep -E '^(skein|oqsphp)$'
```

Expected output:

```text
oqsphp
skein
```

Apache or PHP-FPM may need to be restarted:

```bash
sudo systemctl restart apache2
```

or:

```bash
sudo systemctl restart php8.3-fpm
```

Use the PHP version installed on the server in the service name.

## Compatibility Test

The compatibility test proves that PHP and Contractless Rust produce matching
Skein hashes and mutually valid Falcon signatures:

```bash
cd interop
cargo run --release
cd ..
php tests/native.php
```

The generated private key is a disposable test fixture. Never use it as an
application wallet.

## Using The Modules

Applications normally use these modules through `php-contractless-rpc` rather
than calling them directly.

Direct Skein hashing:

```php
$digest = skein_hash($data, 256);
```

Direct Contractless Falcon handling requires the public-key SHAKE256 prefix and
raw-message marker. `php-contractless-rpc` applies that format automatically,
so application developers should use its `NativeCrypto` class.