# Install M7 C Crypto from source

The initial distribution format is a source `.tar.gz` with a SHA-256 sidecar
and JSON manifest. Version **0.3.0 is a verified development candidate**; a final
public download has not yet been verified. The commands below apply to a
reviewed candidate supplied to you. See [release status](https://m7.org/docs/sdk/m7-c-crypto/releases.md).

For an AlmaLinux server, the shared
[C/PHP installation walkthrough](https://m7.org/docs/sdk/m7-php-crypto/integration/almalinux.md)
starts with dependency packages, builds and tests C first, explains ASan/UBSan,
and installs into a versioned `/opt/m7/crypto/` prefix. C-only consumers can stop
after the C installation; PHP users continue through extension tests, Valgrind,
service activation and rollback. `/home/m7` is its documented build-account home.

## Requirements and compatibility

Use a C11 compiler, make, `pkg-config`, and OpenSSL 3.0+ development headers and
libraries. `pkg-config --modversion libcrypto` must resolve the intended build.
Set `PKG_CONFIG_PATH` to that OpenSSL installation's `lib/pkgconfig` directory
if it is not the default. ML-DSA needs provider support, normally OpenSSL 3.5+.
The complete acceptance run below deliberately fails if ML-DSA is unavailable.

Native 0.3.0 candidate acceptance currently covers macOS arm64 with OpenSSL
3.6.3. Linux build targets exist, but Linux 0.3.0 acceptance remains pending.
There is no portable precompiled binary release established by these checks.
Build for the consumer's OS, CPU and compatible OpenSSL runtime. PHP is not a
C-library dependency; the separate PHP wrapper currently validates PHP 8.4 NTS.

## Check integrity before extraction

Obtain the archive and both sidecars from the same trusted release channel.
Keep them in a new working directory, then run:

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

On systems with `sha256sum`, `sha256sum -c` is equivalent. Stop if the checksum
fails. Confirm one `m7-c-crypto-0.3.0/` root and no absolute paths, parent
traversal, links or unexpected entries before extracting. A checksum detects
mismatched bytes; trusting the publisher still requires a trusted channel.
The JSON sidecar records the package, version, source and payload hashes.

```sh
tar -xzf m7-c-crypto-0.3.0.tar.gz
cmp m7-c-crypto-0.3.0.tar.gz.manifest.json m7-c-crypto-0.3.0/MANIFEST.json
(cd m7-c-crypto-0.3.0 && shasum -a 256 -c CHECKSUMS.sha256)
```

Stop on any mismatch. The release verifier additionally checks complete
inventory, metadata and archive reproducibility; it needs Python 3.10+ as a
verification tool, not as a library runtime dependency:

```sh
python3 m7-c-crypto-0.3.0/scripts/release.py verify \
  m7-c-crypto-0.3.0.tar.gz --integrity-only
```

Integrity-only verification does not establish native runtime acceptance.

## Build into an isolated prefix

From the directory containing the extracted source, choose a fresh prefix that
you own. These commands do not replace a system library:

```sh
m7_crypto_workspace=$(pwd)
m7_crypto_prefix="$m7_crypto_workspace/staging/m7-c-crypto-0.3.0"
cd m7-c-crypto-0.3.0
make -j2
M7CRYPTO_REQUIRE_ML_DSA=1 make test
make install PREFIX="$m7_crypto_prefix"
```

Require every command to succeed before continuing. The tests cover PSS,
signing families, generation/export, RSA-OAEP and provider-failure behavior.
They do not substitute for platform-specific memory checks or the release's
recorded acceptance run.

The prefix contains `include/m7crypto.h` and `lib/libm7crypto.dylib` on macOS
or `lib/libm7crypto.so` on Linux. Compile the [integration example](https://m7.org/docs/sdk/m7-c-crypto/integration/README.md)
against that header and library, retaining its runtime search path. For PHP,
build the wrapper against this exact verified C prefix before enabling it.

## Upgrade and diagnose

Retain the previous library and consumer build while validating an upgrade in
a new prefix. Signing uses the original getter, key generation adds the 0.2
getter, and encryption adds the 0.3 getter. A consumer using a newer getter
needs that API at runtime too; a new header paired with an older library is
not sufficient. Rebuild consumers when their required public ABI changes.

- **Missing headers or libcrypto:** check `pkg-config` and its OpenSSL path.
- **Unsupported algorithm/provider:** inspect the active OpenSSL build and
  provider configuration; do not silently select another algorithm.
- **Missing library or getter at startup:** inspect the consumer's loader
  resolution (`otool -L` on macOS or `ldd` on a trusted Linux binary) and ensure
  the intended C prefix is used.
- **Verification failure:** reject the message and inspect status codes without
  logging secrets. Confirm trusted algorithm policy, key type and byte format.

Changing a loader path or replacing a shared library can affect every consumer
process. Validate each application's actual runtime before a separate deployment
step. Source, installed binary and publicly released artifact are distinct
states; successful installation does not mark a version published.

Return to [M7 C Crypto](https://m7.org/docs/sdk/m7-c-crypto/README.md).