115 lines
2.5 KiB
Markdown
115 lines
2.5 KiB
Markdown
|
# 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.
|