{"record":{"id":"8ae196afa1a6f81f","repo":"spring-projects/spring-security","slug":"unable-to-initialize-due-to-invalid-secret-key","errorCode":null,"errorMessage":"Unable to initialize due to invalid secret key","messagePattern":"Unable to initialize due to invalid secret key","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"crypto/src/main/java/org/springframework/security/crypto/encrypt/CipherUtils.java","lineNumber":125,"sourceCode":"\tstatic void initCipher(Cipher cipher, int mode, SecretKey secretKey, byte[] salt, int iterationCount) {\n\t\tinitCipher(cipher, mode, secretKey, new PBEParameterSpec(salt, iterationCount));\n\t}\n\n\t/**\n\t * Initializes the Cipher for use.\n\t */\n\tstatic void initCipher(Cipher cipher, int mode, SecretKey secretKey,\n\t\t\t@Nullable AlgorithmParameterSpec parameterSpec) {\n\t\ttry {\n\t\t\tif (parameterSpec != null) {\n\t\t\t\tcipher.init(mode, secretKey, parameterSpec);\n\t\t\t}\n\t\t\telse {\n\t\t\t\tcipher.init(mode, secretKey);\n\t\t\t}\n\t\t}\n\t\tcatch (InvalidKeyException ex) {\n\t\t\tthrow new IllegalArgumentException(\"Unable to initialize due to invalid secret key\", ex);\n\t\t}\n\t\tcatch (InvalidAlgorithmParameterException ex) {\n\t\t\tthrow new IllegalStateException(\"Unable to initialize due to invalid decryption parameter spec\", ex);\n\t\t}\n\t}\n\n\t/**\n\t * Invokes the Cipher to perform encryption or decryption (depending on the\n\t * initialized mode).\n\t */\n\tstatic byte[] doFinal(Cipher cipher, byte[] input) {\n\t\ttry {\n\t\t\treturn cipher.doFinal(input);\n\t\t}\n\t\tcatch (IllegalBlockSizeException ex) {\n\t\t\tthrow new IllegalStateException(\"Unable to invoke Cipher due to illegal block size\", ex);\n\t\t}\n\t\tcatch (BadPaddingException ex) {","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/crypto/src/main/java/org/springframework/security/crypto/encrypt/CipherUtils.java#L107-L143","documentation":"Thrown by CipherUtils.initCipher when cipher.init(mode, key, params) throws InvalidKeyException. The SecretKey supplied is not acceptable for the cipher: wrong algorithm type, wrong length, or otherwise unusable key material.","triggerScenarios":"Calling an AesBytesEncryptor built with a non-AES SecretKey or a key of the wrong length (not 128/192/256 bits); passing a password-derived key whose keyLength exceeds the JVM's policy limit; passing null or a DES key to an AES cipher.","commonSituations":"Constructing encryptors with hand-built SecretKeySpec of incorrect length; older Java 8 without unlimited-strength JCE policy when using AES-256; key material from config that was mis-decoded (e.g. hex string not decoded to raw bytes, yielding wrong key length).","solutions":["Ensure the key is an AES key of valid length (16, 24, or 32 bytes) — decode hex/base64 config values to raw bytes before building SecretKeySpec.","On Java 8 before 8u161, install JCE Unlimited Strength policy files or upgrade to get AES-256 support.","Use Spring Security's factory methods (new AesBytesEncryptor(password, salt)) so key derivation is done correctly.","Log key length (secretKey.getEncoded().length) and algorithm at debug level to diagnose mismatches."],"exampleFix":"// before\nSecretKey key = new SecretKeySpec(passphrase.getBytes(), \"AES\"); // length not 16/24/32\n// after\nbyte[] keyBytes = Hex.decode(hexKey); // must decode to exactly 16/24/32 bytes\nSecretKey key = new SecretKeySpec(keyBytes, \"AES\");","handlingStrategy":"validation","validationCode":"if (secretKey.getEncoded() == null ||\n    !(secretKey.getEncoded().length == 16 || secretKey.getEncoded().length == 24 || secretKey.getEncoded().length == 32)) {\n    throw new IllegalArgumentException(\"AES key must be 16/24/32 bytes, got \" +\n        (secretKey.getEncoded() == null ? \"null\" : secretKey.getEncoded().length));\n}","typeGuard":null,"tryCatchPattern":"try {\n    CipherUtils.initCipher(cipher, Cipher.ENCRYPT_MODE, key, spec);\n} catch (IllegalArgumentException ex) {\n    throw new ConfigurationException(\"Key rejected by cipher (wrong type/length or JCE policy)\", ex);\n}","preventionTips":["Decode hex/base64 config keys to raw bytes; verify length before building SecretKeySpec.","Prefer Spring Security encryptor constructors that derive keys internally.","Ensure JDK >= 8u161 for AES-256 without policy files.","Log key algorithm/length (never the key) in debug diagnostics."],"tags":["crypto","invalid-key","cipher-init","key-length","spring-security"],"backgroundTag":"invalid-argument-value","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}