What causes "invalid key length for AES-256-GCM" in OpenNHP/opennhp?

Ensure the key is exactly 32 bytes before calling Encrypt/Decrypt

invalid key length for AES-256-GCM

Error message

invalid key length for AES-256-GCM

What it means

newCipherBlock validates the key length before constructing the underlying cipher block. AES-256-GCM modes require exactly a 32-byte (256-bit) key; any other length returns this error. Called from Encrypt/Decrypt whenever an AES mode is used with a wrongly sized key.

Solutions

Ensure the key is exactly 32 bytes before calling Encrypt/Decrypt
Decode base64/hex-encoded keys to raw bytes; don't pass the encoded string
Check your key-derivation function's output length (e.g. HKDF expand to 32 bytes)
Verify you selected the correct cipher mode for your key size

Example fix

// before
block, err := mode.newCipherBlock([]byte(base64Key)) // wrong length/encoding
// after
raw, _ := base64.StdEncoding.DecodeString(base64Key) // must be 32 bytes
block, err := mode.newCipherBlock(raw)

Defensive patterns

Strategy: validation

Validate before calling

if len(key) != 32 {
	return fmt.Errorf("AES-256-GCM requires a 32-byte key, got %d", len(key))
}

Try / catch

ct, err := mode.Encrypt(key, nonce, plaintext, ad)
if err != nil {
	if strings.Contains(err.Error(), "invalid key length for AES-256-GCM") {
		// re-derive or decode the key to 32 bytes and retry
	}
	return err
}

Prevention

Always derive AES keys to exactly 32 bytes (HKDF/SHA-256)
Decode base64/hex keys before use
Add key-length assertions in tests for every cipher path

When it happens

Trigger: Encrypt or Decrypt invoked on an AES256GCM* SymmetricCipherMode with len(key) != 32 (nhp/core/ztdo/noise.go:111).

Common situations: Keys derived with the wrong hash output size, base64/hex keys not decoded before use, truncating or padding keys during key derivation, mixing SM4 (16-byte) keys with AES modes.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of OpenNHP/opennhp@6e04ca5ff0 (2026-09-07). Data as JSON: /api/errors/788b029be631845f. Report an issue: GitHub.

Appendix: source

Thrown at nhp/core/ztdo/noise.go:111

		return AES256GCM112Tag, nil
	case "AES-256-GCM-120":
		return AES256GCM120Tag, nil
	case "AES-256-GCM-128":
		return AES256GCM128Tag, nil
	case "SM4-GCM-64":
		return SM4GCM64Tag, nil
	case "SM4-GCM-128":
		return SM4GCM128Tag, nil
	default:
		return 0, fmt.Errorf("unknown symmetric mode name: %s", mode)
	}
}
func (mode SymmetricCipherMode) newCipherBlock(key []byte) (cipher.Block, error) {
	switch mode {
	case AES256GCM64Tag, AES256GCM96Tag, AES256GCM104Tag,
		AES256GCM112Tag, AES256GCM120Tag, AES256GCM128Tag:
		if len(key) != 32 {
			return nil, fmt.Errorf("invalid key length for AES-256-GCM")
		}
		return aes.NewCipher(key)
	case SM4GCM64Tag, SM4GCM128Tag:
		if len(key) < 16 {
			return nil, fmt.Errorf("invalid key length for SM4-GCM")
		} else {
			key = key[:16]
		}
		return sm4.NewCipher(key)
	default:
		return nil, fmt.Errorf("unsupported mode: %v", mode)
	}
}

func (mode SymmetricCipherMode) Encrypt(key, nonce, plaintext, ad []byte) ([]byte, error) {
	tagSize := mode.TagSize()

	cipherBlock, err := mode.newCipherBlock(key)

View on GitHub (pinned to 6e04ca5ff0)