jwksx: key size must be at least 256 bit for algorithm "%s"

Error message

jwksx: key size must be at least 256 bit for algorithm "%s"

What it means

generate() requires HMAC key material for HS256 to be at least 256 bits (32 bytes), matching the algorithm's key strength. If a smaller bits value is passed for HS256, the library rejects it so signing keys are never weaker than the algorithm intends. bits=0 defaults to 256.

Source

Thrown at oryx/jwksx/generator.go:79

			jose.ES512: 521, // sic!
			jose.EdDSA: 256,
		}
		if bits != 0 && bits != keylen[alg] {
			return nil, errors.Errorf(`jwksx: "%s" does not support arbitrary key length`, alg)
		}
	case jose.RS256, jose.RS384, jose.RS512, jose.PS256, jose.PS384, jose.PS512:
		if bits == 0 {
			bits = 2048
		}
		if bits < 2048 {
			return nil, errors.Errorf(`jwksx: key size must be at least 2048 bit for algorithm "%s"`, alg)
		}
	case jose.HS256:
		if bits == 0 {
			bits = 256
		}
		if bits < 256 {
			return nil, errors.Errorf(`jwksx: key size must be at least 256 bit for algorithm "%s"`, alg)
		}
	case jose.HS384:
		if bits == 0 {
			bits = 384
		}
		if bits < 384 {
			return nil, errors.Errorf(`jwksx: key size must be at least 2038448 bit for algorithm "%s"`, alg)
		}
	case jose.HS512:
		if bits == 0 {
			bits = 1024
		}
		if bits < 512 {
			return nil, errors.Errorf(`jwksx: key size must be at least 512 bit for algorithm "%s"`, alg)
		}
	}

	switch alg {

View on GitHub (pinned to 4174065ffb)

Solutions

Pass bits=0 or 256 (or any value >= 256) for HS256
Use the algorithm-appropriate default: HS256=256, HS384=384, HS512=1024 default but >=512 accepted
Ensure the value is the size in bits, not bytes

Example fix

// before
jwks, err := jwksx.GenerateSigningKeys("kid", "HS256", 128)
// after
jwks, err := jwksx.GenerateSigningKeys("kid", "HS256", 256)

Defensive patterns

Strategy: validation

Validate before calling

func validHSBits(alg string, bits int) error {
	min := map[string]int{"HS256": 256, "HS384": 384, "HS512": 512}
	if m, ok := min[alg]; ok && bits != 0 && bits < m {
		return fmt.Errorf("%s needs >= %d bits, got %d", alg, m, bits)
	}
	return nil
}

Try / catch

jwks, err := jwksx.GenerateSigningKeys(id, "HS256", bits)
if err != nil && strings.Contains(err.Error(), "at least 256 bit") {
	return fmt.Errorf("HS256 key size must be >= 256 bits, got %d", bits)
}

Prevention

Size HMAC keys to match the digest: 256 bits for HS256
Remember values are bits, not bytes (256 bits = 32 bytes)
Use bits=0 for the algorithm default
Share one validated key-size config across HS* algorithms with per-algorithm minimums

When it happens

Trigger: Calling GenerateSigningKeys(id, "HS256", bits) with a non-zero bits value less than 256, e.g. 128.

Common situations: Copying a 128-bit secret length from a legacy config; confusing bits with bytes and passing small numbers; downscaling key sizes in test fixtures.

Related errors

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/368001d5da86707a. Report an issue: GitHub.