up

docs/security/password-hashing.md

@@ -0,0 +1,76 @@
+# Authority Password Hashing Guidance
+
+> **Status:** Drafted 2025-10-11 alongside SEC1.A / SEC1.PLG rollout. Argon2id is now the default hashing algorithm for the Standard plug-in and recommended for all Authority identity providers.
+
+## 1. Overview
+
+StellaOps Authority issues and verifies credentials through the shared `StellaOps.Cryptography` provider abstraction. As of October 2025:
+
+- **Default algorithm:** Argon2id (PHC format `$argon2id$v=19$m=<mem>,t=<time>,p=<parallelism>$<salt>$<hash>`).
+- **Legacy support:** PBKDF2-SHA256 hashes (`PBKDF2.<iterations>.<payload>`) continue to verify, but successful logins are transparently rehashed to Argon2id.
+- **Configuration path:** `authority.security.passwordHashing` in the primary Authority configuration controls system-wide defaults. Individual plug-ins may override via `passwordHashing` in their manifests.
+
+## 2. Recommended Parameters
+
+| Environment | memorySizeInKib | iterations | parallelism | Notes |
+|-------------|-----------------|------------|-------------|-------|
+| Production (default) | 19456 | 2 | 1 | Balances CPU with 19 MiB memory cost; ~175 ms on 4 vCPU host. |
+| High-security enclave | 32768 | 3 | 1 | Increases memory pressure; confirm capacity on shared hosts. |
+| Resource-constrained lab | 8192 | 2 | 1 | Use only for bootstrap/testing; increase once hardware upgraded. |
+| PBKDF2 fallback | — | ≥210000 | — | Set `algorithm: Pbkdf2` only when Argon2 hardware support unavailable. |
+
+> ⚠️ Lowering parameters below these baselines should be a temporary measure. Document any deviations in runbooks and schedule follow-up work to restore defaults.
+
+## 3. Configuring Authority Defaults
+
+`authority.yaml` (or equivalent) accepts the following block:
+
+```yaml
+security:
+  passwordHashing:
+    algorithm: Argon2id      # or Pbkdf2
+    memorySizeInKib: 19456   # ~19 MiB
+    iterations: 2
+    parallelism: 1
+```
+
+These values propagate to plug-ins that do not provide explicit overrides. Runtime validation ensures all numbers are > 0 and the algorithm is recognised.
+
+## 4. Plug-in Overrides
+
+The Standard plug-in inherits the host defaults but can fine-tune parameters per installation:
+
+```yaml
+passwordHashing:
+  algorithm: Argon2id
+  memorySizeInKib: 8192
+  iterations: 2
+  parallelism: 1
+```
+
+- When the plug-in configuration omits `passwordHashing`, the Authority defaults apply.
+- Setting `algorithm: Pbkdf2` keeps PBKDF2 active but still upgrades credentials when the host default switches back to Argon2id.
+- Invalid overrides (e.g., `memorySizeInKib: 0`) cause startup to fail with a descriptive validation error.
+
+## 5. Observability & Migration
+
+- Successful PBKDF2 verification logs a **rehash-needed** event and immediately persists an Argon2id hash.
+- Metrics emitted: `auth.plugins.standard.password_rehash_total{algorithm="pbkdf2"}` (add dashboards to monitor upgrade progress).
+- During migration, expect a gradual decline in PBKDF2 hashes as users authenticate. Use operator scripts to query `authority_users_*` collections for lingering `PBKDF2.` prefixes if you need to track completion.
+
+## 6. Operational Checklist
+
+1. Update Authority configuration with desired defaults; restart the host.
+2. Regenerate plug-in manifests (if overrides required) and redeploy.
+3. Monitor `password_rehash_total` and login success rates; investigate any spike in failures (likely due to mis-sized limits).
+4. Review hardware utilisation; Argon2id increases memory pressure compared to PBKDF2.
+5. Archive this document with the change request and notify SOC of the new baseline.
+
+For additional context on tuning trade-offs, consult OWASP Password Storage Cheat Sheet and the StellaOps Security Guild guidance (to be published in `docs/security/rate-limits.md`).
+
+## 7. Native Argon2 Preview Build Flag
+
+- Set `dotnet build -p:StellaOpsCryptoSodium=true` (or define the MSBuild property in your CI) to enable the `STELLAOPS_CRYPTO_SODIUM` compilation symbol.
+- The symbol switches `StellaOps.Cryptography` to use the native-oriented build pipeline so we can wire libsodium/Core bindings without affecting the managed default.
+- Until the native implementation lands (SEC1.B follow-up), the flag falls back to the managed Konscious implementation while still validating the alternate compilation path.
+- Document any production usage of the flag in your change log so future upgrades can align with the Security Guild rollout plan.