Install M7 PHP Crypto from source

Version 0.3.0 is a verified development candidate. A final public download has not yet been verified. These instructions apply to reviewed candidate archives supplied to you; see release status.

For one continuous AlmaLinux server procedure, use Build and install M7 Crypto on AlmaLinux. It includes dependency packages, both builds, test expectations, sanitizers/Valgrind, standard installation paths, PHP-FPM activation and rollback. The instructions can be adapted to another distribution while retaining the compatibility and validation checks.

Compatibility and dependency order

Build and validate M7 C Crypto 0.3.0 first, then compile this extension against that exact C prefix. The extension needs C 0.3+ at build and runtime, including the encryption getter. Its source archive does not bundle a C library binary. Headers and the loaded library must agree.

The initial validated PHP target is 8.4 NTS, tested with PHP 8.4.4 and module API 20240924 on macOS arm64, OpenSSL 3.6.3. The compile-time header gate requires PHP 8.4+; it is not evidence that every later PHP version, ZTS build or platform has passed acceptance. Linux 0.3.0 acceptance remains pending. PHP 8.1 support is later work, independent of the Identity SDK's own baseline.

Use matching PHP headers, phpize, php-config and runtime, plus a C compiler, make, autoconf and compatible OpenSSL libraries in the PHP process. M7 C Crypto needs OpenSSL 3.0+; all-profile testing requires ML-DSA provider support, normally OpenSSL 3.5+. The test suite also needs a compatible OpenSSL CLI; the separate interoperability test uses Node.js.

A compiled m7crypto.so is specific to PHP API, NTS/ZTS, OS, CPU, C-library ABI and dependency runtime. A source archive is not a universal extension binary. Do not load an arbitrary build into another PHP installation.

Verify before extraction

Obtain the archive, checksum and manifest together from a trusted release channel. In a fresh working directory:

shasum -a 256 -c m7-php-crypto-0.3.0.tar.gz.sha256
tar -tzf m7-php-crypto-0.3.0.tar.gz

sha256sum -c is equivalent where available. Stop on a checksum failure. Inspect for one m7-php-crypto-0.3.0/ root, without absolute paths, parent traversal, links or unexpected entries. Then:

tar -xzf m7-php-crypto-0.3.0.tar.gz
cmp m7-php-crypto-0.3.0.tar.gz.manifest.json m7-php-crypto-0.3.0/MANIFEST.json
(cd m7-php-crypto-0.3.0 && shasum -a 256 -c CHECKSUMS.sha256)
python3 m7-php-crypto-0.3.0/scripts/release.py verify \
  m7-php-crypto-0.3.0.tar.gz --integrity-only

Require all checks to pass. The final command needs Python 3.10+ as a verifier, not a runtime dependency. It checks inventory, metadata and reproducibility; integrity-only success does not establish native acceptance. Verify the C archive and sidecars independently too. Checksums detect mismatches, while publisher trust depends on the distribution channel.

Isolated build and first load

Place both extracted source directories beside each other. Complete the C build/tests and install it into staging/m7-c-crypto-0.3.0 beneath this working directory. For all-profile acceptance its tests must require ML-DSA support.

Set PATH to your selected PHP 8.4 NTS toolchain before these commands. Check that the displayed versions and API match; stop if they do not:

m7_php_runtime=$(command -v php)
m7_phpize=$(command -v phpize)
m7_php_config=$(command -v php-config)
"$m7_php_runtime" -n -r 'printf("PHP %s %s\n", PHP_VERSION, PHP_ZTS ? "ZTS" : "NTS");'
"$m7_phpize" --version
"$m7_php_config" --version

From the directory containing both extracted sources, build in a new directory:

m7_crypto_workspace=$(pwd)
m7_crypto_prefix="$m7_crypto_workspace/staging/m7-c-crypto-0.3.0"
m7_php_source="$m7_crypto_workspace/m7-php-crypto-0.3.0"
cd "$m7_php_source"
"$m7_phpize"
mkdir build-local
cd build-local
"$m7_php_source/configure" --with-php-config="$m7_php_config" \
  --with-m7crypto="$m7_crypto_prefix"
make -j2
m7_php_module="$PWD/modules/m7crypto.so"
"$m7_php_runtime" -n -d "extension=$m7_php_module" --ri m7crypto

Check that the module reports 0.3.0 and resolves the intended C library. otool -L shows macOS link references; DYLD_PRINT_LIBRARIES=1 on a fresh module-load command shows actual macOS library resolution. On Linux use ldd on your trusted module. An @rpath reference alone does not identify the resolved C installation.

Run the six PHPT cases and the separate encryption interoperability test:

TEST_PHP_EXECUTABLE="$m7_php_runtime" \
M7CRYPTO_TEST_OPENSSL="$(command -v openssl)" \
M7CRYPTO_TEST_PREFIX="$m7_crypto_prefix" \
NO_INTERACTION=1 REPORT_EXIT_STATUS=1 \
  make test TESTS="$m7_php_source/tests"
PHP_BINARY="$m7_php_runtime" M7CRYPTO_TEST_MODULE="$m7_php_module" \
  node "$m7_php_source/tests/encryption_interop.mjs"

Require six passes, zero failures/warnings/skips, and passing interoperability. These checks do not replace the release's recorded memory/stress tests. Save either integration example in the current directory and run:

"$m7_php_runtime" -n -d "extension=$m7_php_module" example.php

Do not require the declaration stub. Loading the native module registers the class. The isolated command avoids modifying the regular PHP configuration.

Deployment and troubleshooting

For deployment, build against the actual worker/SAPI toolchain and install the validated C library and extension as a matched pair. Configure extension=m7crypto.so only in that runtime's intended INI after placing the module in its extension directory and making the C dependency resolvable. Retain the previous pair/configuration for rollback. Reload the relevant workers as a separate deployment step and verify the loaded extension in that SAPI; a shell PHP success does not prove a web worker uses the same configuration.

  • Header or getter missing at configure: use the verified C 0.3+ prefix, including both its headers and library.
  • PHP API or architecture mismatch: rebuild with the target runtime's matching tools and NTS/ZTS mode; do not copy another build blindly.
  • Library not found or undefined symbol at load: check actual loader paths and C version, including an older library found before the intended prefix.
  • Provider failure or skipped profile tests: check compatible OpenSSL libraries/provider configuration and the OpenSSL CLI used by tests.
  • Class missing: confirm --ri m7crypto in the same PHP runtime and SAPI; loading the stub is not a substitute.

Neither a local installation nor a passing shell example establishes a public release. Ordinary Identity SDK use remains independent of this optional native extension. Return to M7 PHP Crypto.