# 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.