git.stella-ops.org/docs/security/password-hashing.md

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:

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:

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.