basicauth: Implement argon2id (#7186)

* feat: add argon2id hash-password command

* feat: ardon2id owasp safe value

* feat: add argon2id compare method

* chore: fmt argon2id

* docs: more argon2id docs

* chore: upgrade x/crypto dep

* revert: remove golangci

* refactor: argon2id decode

* chore: update deps

* refactor: simplify argon2id compare return

* chore: upgrade dependencies

* chore: upgrade dependencies

modules/caddyhttp/caddyauth/argon2id.go

@@ -0,0 +1,188 @@
+// Copyright 2015 Matthew Holt and The Caddy Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package caddyauth
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/crypto/argon2"
+
+	"github.com/caddyserver/caddy/v2"
+)
+
+func init() {
+	caddy.RegisterModule(Argon2idHash{})
+}
+
+const (
+	argon2idName           = "argon2id"
+	defaultArgon2idTime    = 1
+	defaultArgon2idMemory  = 46 * 1024
+	defaultArgon2idThreads = 1
+	defaultArgon2idKeylen  = 32
+	defaultSaltLength      = 16
+)
+
+// Argon2idHash implements the Argon2id password hashing.
+type Argon2idHash struct {
+	salt    []byte
+	time    uint32
+	memory  uint32
+	threads uint8
+	keyLen  uint32
+}
+
+// CaddyModule returns the Caddy module information.
+func (Argon2idHash) CaddyModule() caddy.ModuleInfo {
+	return caddy.ModuleInfo{
+		ID:  "http.authentication.hashes.argon2id",
+		New: func() caddy.Module { return new(Argon2idHash) },
+	}
+}
+
+// Compare checks if the plaintext password matches the given Argon2id hash.
+func (Argon2idHash) Compare(hashed, plaintext []byte) (bool, error) {
+	argHash, storedKey, err := DecodeHash(hashed)
+	if err != nil {
+		return false, err
+	}
+
+	computedKey := argon2.IDKey(
+		plaintext,
+		argHash.salt,
+		argHash.time,
+		argHash.memory,
+		argHash.threads,
+		argHash.keyLen,
+	)
+
+	return subtle.ConstantTimeCompare(storedKey, computedKey) == 1, nil
+}
+
+// Hash generates an Argon2id hash of the given plaintext using the configured parameters and salt.
+func (b Argon2idHash) Hash(plaintext []byte) ([]byte, error) {
+	if b.salt == nil {
+		s, err := generateSalt(defaultSaltLength)
+		if err != nil {
+			return nil, err
+		}
+		b.salt = s
+	}
+
+	key := argon2.IDKey(
+		plaintext,
+		b.salt,
+		b.time,
+		b.memory,
+		b.threads,
+		b.keyLen,
+	)
+
+	hash := fmt.Sprintf(
+		"$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
+		argon2.Version,
+		b.memory,
+		b.time,
+		b.threads,
+		base64.RawStdEncoding.EncodeToString(b.salt),
+		base64.RawStdEncoding.EncodeToString(key),
+	)
+
+	return []byte(hash), nil
+}
+
+// DecodeHash parses an Argon2id PHC string into an Argon2idHash struct and returns the struct along with the derived key.
+func DecodeHash(hash []byte) (*Argon2idHash, []byte, error) {
+	parts := strings.Split(string(hash), "$")
+	if len(parts) != 6 {
+		return nil, nil, fmt.Errorf("invalid hash format")
+	}
+
+	if parts[1] != argon2idName {
+		return nil, nil, fmt.Errorf("unsupported variant: %s", parts[1])
+	}
+
+	version, err := strconv.Atoi(strings.TrimPrefix(parts[2], "v="))
+	if err != nil {
+		return nil, nil, fmt.Errorf("invalid version: %w", err)
+	}
+	if version != argon2.Version {
+		return nil, nil, fmt.Errorf("incompatible version: %d", version)
+	}
+
+	params := strings.Split(parts[3], ",")
+	if len(params) != 3 {
+		return nil, nil, fmt.Errorf("invalid parameters")
+	}
+
+	mem, err := strconv.ParseUint(strings.TrimPrefix(params[0], "m="), 10, 32)
+	if err != nil {
+		return nil, nil, fmt.Errorf("invalid memory parameter: %w", err)
+	}
+
+	iter, err := strconv.ParseUint(strings.TrimPrefix(params[1], "t="), 10, 32)
+	if err != nil {
+		return nil, nil, fmt.Errorf("invalid iterations parameter: %w", err)
+	}
+
+	threads, err := strconv.ParseUint(strings.TrimPrefix(params[2], "p="), 10, 8)
+	if err != nil {
+		return nil, nil, fmt.Errorf("invalid parallelism parameter: %w", err)
+	}
+
+	salt, err := base64.RawStdEncoding.Strict().DecodeString(parts[4])
+	if err != nil {
+		return nil, nil, fmt.Errorf("decode salt: %w", err)
+	}
+
+	key, err := base64.RawStdEncoding.Strict().DecodeString(parts[5])
+	if err != nil {
+		return nil, nil, fmt.Errorf("decode key: %w", err)
+	}
+
+	return &Argon2idHash{
+		salt:    salt,
+		time:    uint32(iter),
+		memory:  uint32(mem),
+		threads: uint8(threads),
+		keyLen:  uint32(len(key)),
+	}, key, nil
+}
+
+// FakeHash returns a constant fake hash for timing attacks mitigation.
+func (Argon2idHash) FakeHash() []byte {
+	// hashed with the following command:
+	// caddy hash-password --plaintext "antitiming" --algorithm "argon2id"
+	return []byte("$argon2id$v=19$m=47104,t=1,p=1$P2nzckEdTZ3bxCiBCkRTyA$xQL3Z32eo5jKl7u5tcIsnEKObYiyNZQQf5/4sAau6Pg")
+}
+
+// Interface guards
+var (
+	_ Comparer = (*Argon2idHash)(nil)
+	_ Hasher   = (*Argon2idHash)(nil)
+)
+
+func generateSalt(length int) ([]byte, error) {
+	salt := make([]byte, length)
+	if _, err := rand.Read(salt); err != nil {
+		return nil, fmt.Errorf("failed to generate salt: %w", err)
+	}
+	return salt, nil
+}

modules/caddyhttp/caddyauth/bcrypt.go

@@ -27,7 +27,10 @@ func init() {
 }
 
 // defaultBcryptCost cost 14 strikes a solid balance between security, usability, and hardware performance
-const defaultBcryptCost = 14
+const (
+	bcryptName        = "bcrypt"
+	defaultBcryptCost = 14
+)
 
 // BcryptHash implements the bcrypt hash.
 type BcryptHash struct {

modules/caddyhttp/caddyauth/caddyfile.go

@@ -51,7 +51,7 @@ func parseCaddyfile(h httpcaddyfile.Helper) (caddyhttp.MiddlewareHandler, error)
 	var hashName string
 	switch len(args) {
 	case 0:
-		hashName = "bcrypt"
+		hashName = bcryptName
 	case 1:
 		hashName = args[0]
 	case 2:
@@ -62,8 +62,10 @@ func parseCaddyfile(h httpcaddyfile.Helper) (caddyhttp.MiddlewareHandler, error)
 	}
 
 	switch hashName {
-	case "bcrypt":
+	case bcryptName:
 		cmp = BcryptHash{}
+	case argon2idName:
+		cmp = Argon2idHash{}
 	default:
 		return nil, h.Errf("unrecognized hash algorithm: %s", hashName)
 	}

modules/caddyhttp/caddyauth/command.go

@@ -32,28 +32,55 @@ import (
 func init() {
 	caddycmd.RegisterCommand(caddycmd.Command{
 		Name:  "hash-password",
-		Usage: "[--plaintext <password>] [--algorithm <name>] [--bcrypt-cost <difficulty>]",
+		Usage: "[--plaintext <password>] [--algorithm <argon2id|bcrypt>] [--bcrypt-cost <difficulty>] [--argon2id-time <iterations>] [--argon2id-memory <KiB>] [--argon2id-threads <n>] [--argon2id-keylen <bytes>]",
 		Short: "Hashes a password and writes base64",
 		Long: `
 Convenient way to hash a plaintext password. The resulting
 hash is written to stdout as a base64 string.
 
---plaintext, when omitted, will be read from stdin. If
-Caddy is attached to a controlling tty, the plaintext will
-not be echoed.
+--plaintext
+    The password to hash. If omitted, it will be read from stdin.
+    If Caddy is attached to a controlling TTY, the input will not be echoed.
 
---algorithm currently only supports 'bcrypt', and is the default.
+--algorithm
+    Selects the hashing algorithm. Valid options are:
+      * 'argon2id' (recommended for modern security)
+      * 'bcrypt'  (legacy, slower, configurable cost)
 
---bcrypt-cost sets the bcrypt hashing difficulty.
-Higher values increase security by making the hash computation slower and more CPU-intensive.
-If the provided cost is not within the valid range [bcrypt.MinCost, bcrypt.MaxCost],
-the default value (defaultBcryptCost) will be used instead.
-Note: Higher cost values can significantly degrade performance on slower systems.
+bcrypt-specific parameters:
+
+--bcrypt-cost
+    Sets the bcrypt hashing difficulty. Higher values increase security by
+    making the hash computation slower and more CPU-intensive.
+    Must be within the valid range [bcrypt.MinCost, bcrypt.MaxCost]. 
+    If omitted or invalid, the default cost is used.
+
+Argon2id-specific parameters:
+
+--argon2id-time
+    Number of iterations to perform. Increasing this makes
+    hashing slower and more resistant to brute-force attacks.
+
+--argon2id-memory
+    Amount of memory to use during hashing.
+    Larger values increase resistance to GPU/ASIC attacks.
+
+--argon2id-threads
+    Number of CPU threads to use. Increase for faster hashing
+    on multi-core systems.
+
+--argon2id-keylen
+    Length of the resulting hash in bytes. Longer keys increase
+    security but slightly increase storage size.
 `,
 		CobraFunc: func(cmd *cobra.Command) {
 			cmd.Flags().StringP("plaintext", "p", "", "The plaintext password")
-			cmd.Flags().StringP("algorithm", "a", "bcrypt", "Name of the hash algorithm")
+			cmd.Flags().StringP("algorithm", "a", bcryptName, "Name of the hash algorithm")
 			cmd.Flags().Int("bcrypt-cost", defaultBcryptCost, "Bcrypt hashing cost (only used with 'bcrypt' algorithm)")
+			cmd.Flags().Uint32("argon2id-time", defaultArgon2idTime, "Number of iterations for Argon2id hashing. Increasing this makes the hash slower and more resistant to brute-force attacks.")
+			cmd.Flags().Uint32("argon2id-memory", defaultArgon2idMemory, "Memory to use in KiB for Argon2id hashing. Larger values increase resistance to GPU/ASIC attacks.")
+			cmd.Flags().Uint8("argon2id-threads", defaultArgon2idThreads, "Number of CPU threads to use for Argon2id hashing. Increase for faster hashing on multi-core systems.")
+			cmd.Flags().Uint32("argon2id-keylen", defaultArgon2idKeylen, "Length of the resulting Argon2id hash in bytes. Longer hashes increase security but slightly increase storage size.")
 			cmd.RunE = caddycmd.WrapCommandFuncForCobra(cmdHashPassword)
 		},
 	})
@@ -115,8 +142,34 @@ func cmdHashPassword(fs caddycmd.Flags) (int, error) {
 	var hash []byte
 	var hashString string
 	switch algorithm {
-	case "bcrypt":
+	case bcryptName:
 		hash, err = BcryptHash{cost: bcryptCost}.Hash(plaintext)
+		hashString = string(hash)
+	case argon2idName:
+		time, err := fs.GetUint32("argon2id-time")
+		if err != nil {
+			return caddy.ExitCodeFailedStartup, fmt.Errorf("failed to get argon2id time parameter: %w", err)
+		}
+		memory, err := fs.GetUint32("argon2id-memory")
+		if err != nil {
+			return caddy.ExitCodeFailedStartup, fmt.Errorf("failed to get argon2id memory parameter: %w", err)
+		}
+		threads, err := fs.GetUint8("argon2id-threads")
+		if err != nil {
+			return caddy.ExitCodeFailedStartup, fmt.Errorf("failed to get argon2id threads parameter: %w", err)
+		}
+		keyLen, err := fs.GetUint32("argon2id-keylen")
+		if err != nil {
+			return caddy.ExitCodeFailedStartup, fmt.Errorf("failed to get argon2id keylen parameter: %w", err)
+		}
+
+		hash, _ = Argon2idHash{
+			time:    time,
+			memory:  memory,
+			threads: threads,
+			keyLen:  keyLen,
+		}.Hash(plaintext)
+
 		hashString = string(hash)
 	default:
 		return caddy.ExitCodeFailedStartup, fmt.Errorf("unrecognized hash algorithm: %s", algorithm)