{"record":{"id":"ade45f52ad4b8f71","repo":"ory/hydra","slug":"key-must-be-exactly-d-bytes-long-got-d-bytes","errorCode":null,"errorMessage":"key must be exactly %d bytes long, got %d bytes","messagePattern":"key must be exactly (.+?) bytes long, got (.+?) bytes","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"aead/helpers.go","lineNumber":19,"sourceCode":"// Copyright © 2023 Ory Corp\n// SPDX-License-Identifier: Apache-2.0\n\npackage aead\n\nimport (\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc encryptionKey(ctx context.Context, d Dependencies, keySize int) ([]byte, error) {\n\tkeys, err := allKeys(ctx, d)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tkey := keys[0]\n\tif len(key) != keySize {\n\t\treturn nil, fmt.Errorf(\"key must be exactly %d bytes long, got %d bytes\", keySize, len(key))\n\t}\n\n\treturn key, nil\n}\n\nfunc allKeys(ctx context.Context, d Dependencies) ([][]byte, error) {\n\tglobal, err := d.GetGlobalSecret(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\trotated, err := d.GetRotatedGlobalSecrets(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tkeys := append([][]byte{global}, rotated...)\n\tif len(keys) == 0 {","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/aead/helpers.go#L1-L37","documentation":"The AEAD helper requires the encryption key to be exactly keySize (chacha20poly1305 key length, 32 bytes) long. When the configured AEAD key has any other length, encryptionKey/Encrypt returns this error because the cipher cannot be initialized with an invalid key.","triggerScenarios":"Calling Encrypt (via encryptionKey) when the first key in the AEAD key configuration (AEAD key material, e.g. secrets.system-derived) does not decode to exactly 32 bytes.","commonSituations":"Setting secrets.system to a too-short human-readable password instead of a 32-byte base64 value; rotating to a malformed key; pasting a key truncated or with wrong encoding (hex vs base64); upgrading Hydra where a shorter legacy key is still configured.","solutions":["Set secrets.system (and any rotated keys) to a valid base64-encoded 32-byte (256-bit) value; generate with `openssl rand -base64 32`.","Re-encode an existing key: if you have raw key bytes, base64-encode the full 32 bytes instead of a hex string or ASCII passphrase.","Rotate the AEAD key properly via the aead.RotateKey API so old ciphertexts stay decryptable.","Decrypt-and-reencrypt data with a correct key if old ciphertext was created under a wrong-length key."],"exampleFix":"// before\nSECRETS_SYSTEM=super-secret-password\n\n// after\nSECRETS_SYSTEM=$(openssl rand -base64 32)","handlingStrategy":"validation","validationCode":"// Validate key length before configuring/rotating:\nkey, err := base64.StdEncoding.DecodeString(cfgSecret)\nif err != nil || len(key) != 32 {\n    panic(fmt.Sprintf(\"AEAD key must be 32 bytes, got %d\", len(key)))\n}","typeGuard":null,"tryCatchPattern":"// When calling Encrypt directly:\nenc, err := x.Encrypt(ctx, plaintext)\nif err != nil {\n    var keyErr interface{ error }\n    _ = keyErr\n    return fmt.Errorf(\"encrypt failed (check AEAD key is 32 base64 bytes): %w\", err)\n}","preventionTips":["Generate keys only with `openssl rand -base64 32`.","Never use ASCII passwords or hex strings as secrets.system.","Add a startup config check that decodes and length-checks the key.","Keep current and rotated keys in a secrets manager, not hand-edited env files."],"tags":["encryption","aead","configuration","key-management"],"backgroundTag":"invalid-encryption-key-size","analyzedSha":"4174065ffb052799890f7480f5360a877a67ffc1","analyzedAt":"2026-09-03T14:52:41.581Z","contentChangedAt":"2026-09-03T14:52:41.581Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}