master
607e72e2a1
Some checks failed
Build Test Deploy / docs (push) Has been cancelled
Build Test Deploy / deploy (push) Has been cancelled
Build Test Deploy / build-test (push) Has been cancelled
Build Test Deploy / authority-container (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
77 lines
4.3 KiB
Markdown
77 lines
4.3 KiB
Markdown
# 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.
|