# Contributing to FreeHSM C

Thank you for your interest in contributing to FreeHSM C. This project is a FIPS 140-3 candidate cryptographic module ; contributions are welcome but the certification track imposes constraints on what can be merged and how. Please read this guide carefully before submitting a pull request.

Project lead : **Afchine Madjlessi** ([`afchine.mad@gmail.com`](mailto:afchine.mad@gmail.com))

---

## Quick links

- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security policy](SECURITY.md)
- [Architecture overview](docs/ARCHITECTURE.md)
- [Build instructions](README.md#build)
- [Mechanism list](docs/MECHANISMS.md)

---

## 1. Ground rules

1. **License.** All contributions are licensed under the project's [Apache 2.0 LICENSE](LICENSE). By opening a pull request you agree that your contribution is licensed under those terms.
2. **DCO sign-off.** Every commit must carry a `Signed-off-by:` trailer (Developer Certificate of Origin). Use `git commit -s`.
3. **No secrets, no keys.** Do not commit private keys, PINs, audit logs, or `.fhsm_digest` blobs from local builds. The `.gitignore` is meant to catch the obvious cases ; double-check `git status` before pushing.
4. **No `FHSM_INTEGRITY_ALLOW_UNSIGNED` in production paths.** This env var is dev-only ; see [`docs/AGD_PRE.md`](docs/AGD_PRE.md) §7.5.
5. **Be respectful.** See [Code of Conduct](CODE_OF_CONDUCT.md).

---

## 2. Branch model

- `main` is the integration branch.
- Release branches are `release/v<major>.<minor>` and receive backports of security fixes only.
- Feature branches are `feature/<short-name>`.
- Security-sensitive work happens off-tree and lands as a single signed commit after coordinated disclosure (see [SECURITY.md](SECURITY.md)).

---

## 3. Pull-request checklist

Before opening a PR, run :

```bash
# Lint, format, build, test
make clean && make
make tests
bash tests/coverage_matrix.sh          # full PKCS#11 surface
scripts/add_copyright_header.sh --check  # SPDX header coverage

# If you changed an algorithm or a KAT vector :
make integrity                          # re-sign the digest
```

The CI workflow re-runs all of the above on every PR. A PR is mergeable when :

- [ ] All CI checks are green.
- [ ] At least one maintainer has approved.
- [ ] The CHANGELOG has an entry under `## [Unreleased]`.
- [ ] Touched documentation files (`docs/`) are bilingual (`.md` + `.fr.md`) for the audited surface (CC documents).
- [ ] Every new `.c`/`.h` file carries the SPDX header (CI rejects otherwise).
- [ ] No `TODO` / `XXX` / `FIXME` introduced without a tracking issue link.

---

## 4. Coding style

- **Language** : C11 strict (`-std=c11`). No GNU extensions in headers ; minimal in source.
- **Indentation** : 4 spaces. Never tabs.
- **Line width** : 80 columns soft, 100 hard.
- **Naming** : `fhsm_<module>_<verb>` for functions, `FHSM_<MODULE>_<NAME>` for macros, `g_<name>` for module-static globals.
- **Comments** : prefer block comments (`/* ... */`) ; explain the *why*, not the *what*.
- **No silent failures** : every `fhsm_rv_t` returned by a sub-call is checked. CI compiles with `-Werror -Wall -Wextra -Wpedantic` ; `-Wmissing-prototypes` is on.
- **Constant-time discipline** : never branch on secrets. Use `fhsm_ct_memcmp`. See [`docs/SIDE_CHANNEL.md`](docs/SIDE_CHANNEL.md).
- **Memory** : SSPs MUST live in the secure heap (`fhsm_secure_zalloc`). Zeroise via `fhsm_zeroize` (calls `OPENSSL_cleanse`).

---

## 5. Tests

The project ships four kinds of tests :

| Test | When | What |
|---|---|---|
| `tests/test_smoke` | Every build | Token init + AES-GCM round-trip + tag tampering |
| `tests/full_crypto_pkcs11.sh` | PR + nightly | 20 assertions via `pkcs11-tool` |
| `tests/coverage_matrix.sh` | PR + nightly | 27 PASS / 5 SKIP / 0 FAIL on green builds |
| `tests/*_e2e` (mlkem, mldsa, slhdsa) | PR + nightly | PQ algorithms via dlsym harnesses |

Adding a new mechanism implies adding :
1. The dispatch handler in `src/dispatch/`.
2. At least one CAVP-derived KAT vector in `kat/` (cite the source).
3. One assertion in `tests/coverage_matrix.sh`.

---

## 6. Documentation contributions

- The CC documents (`docs/ARCHITECTURE.md`, `AGD_*`, `ALC_*`, `ATE_*`, `AVA_*`, `EAL4_PLUS.md`, `FIPS_140_3.md`) are part of the certification deliverable. Changes MUST be bilingual (add the matching `.fr.md` change).
- `docs/MECHANISMS.md` is auto-generated by `scripts/gen_p11_thunks.py` — don't hand-edit ; modify the generator.
- For new docs that are NOT CC artifacts (e.g. `docs/RNG.md`, `docs/POST_QUANTUM.md`), an English-only file is acceptable.

---

## 7. Security disclosures

Do NOT open a public issue for a security vulnerability. Follow the process in [SECURITY.md](SECURITY.md) :

- Email [`afchine.mad@gmail.com`](mailto:afchine.mad@gmail.com) with subject `[FreeHSM-SECURITY]`.
- GPG-encrypt against the maintainer key published at the bottom of [SECURITY.md](SECURITY.md).
- Expect an acknowledgement within 5 business days.

---

## 8. Maintainer responsibilities

If you become a maintainer :

- Review code with the CC evaluator's eyes : every change to a TSF (Target Security Function) potentially triggers re-evaluation. (The flaw-remediation procedure, ALC_FLR, is not written yet — this line used to cite a `docs/ALC_FLR.md` that does not exist.)
- Never merge a security fix without a coordinated disclosure timeline agreed with the reporter.
- Tag releases with GPG-signed annotated tags (`git tag -s v<x.y.z>`).
- Append every change to `CHANGELOG.md` under Keep-a-Changelog conventions.

---

## 9. Acknowledgements

Contributors will be listed in `AUTHORS.md` (created at the first external contribution). The DCO sign-off is sufficient ; no Contributor License Agreement is required.
