dgraph-io/dgraph · error

ACL key length [%v <= %v] bits for JWT algorithm [%v]

Error message

ACL key length [%v <= %v] bits for JWT algorithm [%v]

What it means

For HS* algorithms, checkAclKeyLength requires the key to be at least as long as the SHA output: key length in bits (len(key)*8) must be >= the algorithm's SHA size. Otherwise it returns this error listing the actual and required bit lengths.

Source

Thrown at x/acl_enc_keys.go:142

	default:
		return nil, nil, errors.Errorf("unsupported signing algorithm: %v", alg.Alg())
	}
}

func checkAclKeyLength(alg jwt.SigningMethod, key Sensitive) error {
	if !strings.HasPrefix(alg.Alg(), "HS") {
		return nil
	}

	sl, err := strconv.Atoi(strings.TrimPrefix(alg.Alg(), "HS"))
	if err != nil {
		return errors.Wrapf(err, "error finding sha length for algo %v", alg.Alg())
	}

	// SHA length has to be smaller or equal to the key length
	if sl > len(key)*8 {
		return errors.Errorf("ACL key length [%v <= %v] bits for JWT algorithm [%v]", len(key)*8, sl, alg.Alg())
	}
	return nil
}

func RegisterAclAndEncFlags(flag *pflag.FlagSet) {
	registerAclFlag(flag)
	registerEncFlag(flag)
	registerVaultFlag(flag, true, true)
}

func RegisterEncFlag(flag *pflag.FlagSet) {
	registerEncFlag(flag)
	registerVaultFlag(flag, false, true)
}

func registerAclFlag(flag *pflag.FlagSet) {
	helpText := z.NewSuperFlagHelp(AclDefaults).
		Head("ACL options").

View on GitHub (pinned to 759e242be6)

Solutions

1. Provide a secret of at least 32 bytes for HS256, 48 for HS384, 64 for HS512 (openssl rand -hex 32)
2. Or downgrade jwt-alg to HS256 (or lower) to match the current key length
3. Avoid trailing newlines/encoding surprises by checking the actual file byte length
4. Store the generated secret in Vault/secret manager and reference it consistently

Example fix

// before
--acl "hmac-secret=short;jwt-alg=HS256" # 5 bytes
// after
KEY=$(openssl rand -hex 32); --acl "hmac-secret=$KEY;jwt-alg=HS256" # 32 bytes

minBits := map[string]int{"HS256":256,"HS384":384,"HS512":512}
if req, ok := minBits[algStr]; ok && len(secret)*8 < req {
    return fmt.Errorf("secret too short: %d bits, need >= %d for %s", len(secret)*8, req, algStr)
}

if _, err := x.GetEncAclKeys(flag, encKey); err != nil {
    if strings.Contains(err.Error(), "ACL key length") {
        log.Fatalf("lengthen the HMAC secret: openssl rand -hex 32 (HS256) / 48 (HS384) / 64 (HS512)")
    }
    return err
}

When it happens

Trigger: GetEncAclKeys with an HS256/384/512 jwt-alg whose HMAC secret is shorter than 32/48/64 bytes respectively (e.g. a 10-byte password used as the secret for HS256).

Common situations: Operators choosing a short human-memorable secret; secrets truncated by config tooling; upgrading jwt-alg from HS256 to HS512 without lengthening the key.

Related errors

• error finding sha length for algo %v
• Authorize guardian of the galaxy, extracting jwt token, erro
• while getting jwt auth token
• Unsupported JWT signing algorithm for ACL: %v
• error parsing ACL key as ECDSA private key

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/5acea3cfb4ca02f0. Report an issue: GitHub.