gofiber/fiber · critical · ErrInvalidSHA256PasswordLength

decode SHA256 password: invalid length

Error message

decode SHA256 password: invalid length

What it means

Returned by basicauth.parseHashedPassword when a user's stored password hash prefixed with {SHA256} (or an unprefixed value treated as raw SHA-256) decodes from base64/hex to a byte slice whose length is not exactly 32 (sha256.Size). A wrong-length digest can never match a real SHA-256 sum, so accepting it would silently reject every login for that user; the middleware surfaces the misconfiguration at startup instead. It is wrapped via buildVerifiers and panics from configDefault when the Config.Users map contains an invalid entry.

Source

Thrown at middleware/basicauth/config.go:21

import (
	"crypto/sha256"
	"crypto/sha512"
	"crypto/subtle"
	"encoding/base64"
	"encoding/hex"
	"errors"
	"fmt"
	"sort"
	"strconv"
	"strings"

	"github.com/gofiber/fiber/v3"
	"github.com/gofiber/utils/v2"
	"golang.org/x/crypto/bcrypt"
)

var (
	ErrInvalidSHA256PasswordLength = errors.New("decode SHA256 password: invalid length")
	ErrInvalidSHA512PasswordLength = errors.New("decode SHA512 password: invalid length")
)

// fallbackDummySHA512 is SHA-512("fiber-basicauth-dummy"), used as a
// constant-time comparison target when no users are configured.
var fallbackDummySHA512 = [sha512.Size]byte{
	0x85, 0xc7, 0xd4, 0xbc, 0xec, 0x5f, 0xdf, 0xef, 0xe0, 0x4d, 0xd4, 0x3e, 0xd3, 0xac, 0x45, 0x7c,
	0x5e, 0x48, 0x60, 0x74, 0x12, 0x8e, 0xf8, 0xc0, 0xde, 0x39, 0x89, 0xf9, 0x84, 0x0c, 0x50, 0x24,
	0x1e, 0xa6, 0x1f, 0x2a, 0x11, 0x97, 0xb1, 0xb9, 0x67, 0xa9, 0xf7, 0x3b, 0x82, 0x8f, 0x95, 0xf5,
	0x58, 0xed, 0x3c, 0xab, 0x43, 0x22, 0xf6, 0xfa, 0x84, 0x1d, 0xbc, 0xeb, 0x87, 0xc4, 0x1c, 0x5a,
}

type passwordVerifier func(string) bool

type userVerifiers map[string]passwordVerifier

// Verifier strengths are ordered by expected verification work:
// bcrypt is strongest because it is adaptive and cost-based, SHA-512 follows

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Regenerate the hash as raw 32 bytes and base64-encode it: echo -n 'pass' | openssl dgst -sha256 -binary | base64, then prefix with '{SHA256}'.
2. Verify the decoded length is 32 bytes: base64-decode your value and check len == 32.
3. If you have a hex-encoded digest, convert it to the raw-byte base64 form the library expects, or use the '{SHA256}' prefix with raw bytes.
4. Consider switching to bcrypt ('$2...') hashes which are stronger and have no fixed-length pitfalls.

Example fix

// before
app.Use(basicauth.New(basicauth.Config{
  Users: map[string]string{"admin": "{SHA256}" + hexDigest}, // hexDigest is 64 hex chars
}))
// after — convert hex to raw bytes then base64
raw, _ := hex.DecodeString(hexDigest) // 32 bytes
app.Use(basicauth.New(basicauth.Config{
  Users: map[string]string{"admin": "{SHA256}" + base64.StdEncoding.EncodeToString(raw)},
}))

// Validate all user hashes before constructing the middleware
for user, hash := range users {
    if strings.HasPrefix(hash, "{SHA256}") {
        b, err := base64.StdEncoding.DecodeString(hash[len("{SHA256}"):])
        if err != nil || len(b) != sha256.Size {
            log.Fatalf("user %q has invalid SHA256 hash (decoded len=%d)", user, len(b))
        }
    }
}

When it happens

Trigger: Configuring basicauth.Config.Users with a password value like "{SHA256}<short-base64>" or a bare hex/base64 string that does not decode to exactly 32 bytes. The error triggers during New() because buildVerifiers → parseHashedPassword runs eagerly at middleware construction (config.go:152-156), so it manifests as a startup panic before the server serves traffic.

Common situations: Copy-pasting a truncated hash; storing the hex digest (64 chars) but the library expects raw 32-byte base64; confusing SHA-256 output length with bcrypt; generating the hash with a tool that emits a digest string instead of raw bytes. Migration from another auth library that used a different SHA-256 encoding format.

Related errors

• encryption key must be 16, 24, or 32 bytes
• logger: unknown template tag
• decode SHA512 password: %w
• decode SHA256 password: %w
• failed to decrypt ciphertext: %w

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/c89bd9082f552550.json. Report an issue: GitHub.