{"record":{"id":"3ba3c6906bb9ceb7","repo":"jwtk/jjwt","slug":"the-id-algorithm-requires-keys-with-a-length","errorCode":null,"errorMessage":"The '${id}' algorithm requires keys with a length of ${bitsMsg(requiredLengthInBits)}.  The provided key has a length of ${bitsMsg(keyBitLength)}.","messagePattern":"The '(.+?)' algorithm requires keys with a length of (.+?)\\.  The provided key has a length of (.+?)\\.","errorType":"validation","errorClass":"WeakKeyException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/security/AesAlgorithm.java","lineNumber":128,"sourceCode":"                Bytes.bitsMsg(requiredLengthInBits) + \".  The provided key has a length of \" +\n                Bytes.bitsMsg(actualLengthInBits) + \".\";\n    }\n\n    protected byte[] validateLength(SecretKey key, int requiredBitLength, boolean propagate) {\n        byte[] keyBytes;\n\n        try {\n            keyBytes = key.getEncoded();\n        } catch (RuntimeException re) {\n            if (propagate) {\n                throw re;\n            }\n            //can't get the bytes to validate, e.g. hardware security module or later Android, so just return:\n            return null;\n        }\n        long keyBitLength = Bytes.bitLength(keyBytes);\n        if (keyBitLength < requiredBitLength) {\n            throw new WeakKeyException(lengthMsg(getId(), \"keys\", requiredBitLength, keyBitLength));\n        }\n\n        return keyBytes;\n    }\n\n    protected byte[] assertBytes(byte[] bytes, String type, int requiredBitLen) {\n        long bitLen = Bytes.bitLength(bytes);\n        if (requiredBitLen != bitLen) {\n            String msg = lengthMsg(getId(), type, requiredBitLen, bitLen);\n            throw new IllegalArgumentException(msg);\n        }\n        return bytes;\n    }\n\n    byte[] assertIvLength(final byte[] iv) {\n        return assertBytes(iv, \"initialization vectors\", this.ivBitLength);\n    }\n","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/security/AesAlgorithm.java#L110-L146","documentation":"Thrown as a WeakKeyException by AesAlgorithm.validateLength (via encoded) when an AES key supplied to a JWE encryption algorithm (A128GCM, A256GCM-KW, etc.) is shorter than the required bit length. The library refuses to use cryptographically weak keys rather than silently producing insecure output.","triggerScenarios":"Calling Jwts.builder().encryptWith(key, alg) or Jwts.parser().decryptWith(key) where key.getEncoded().length*8 < requiredBitLength (e.g. a 128-bit key with A256GCM).","commonSituations":"Generating a key with KeyGenerator without setting the key size (defaults to 128 bits); loading a truncated or Base64-decoded secret that is shorter than expected; hard-coding a short demo secret then switching to a 256-bit algorithm.","solutions":["Generate a correctly sized key: Jwts.SIG.A256GCM.key().build() or SecretKey with 32 bytes for AES-256.","If deriving bytes from a secret string, hash them (e.g. SHA-256) to reach the required length.","Verify the encoded key length before use: Bytes.bitLength or key.getEncoded().length * 8.","Use KeysBridge/password-based derivation (jwe key encryption) to derive a correctly sized content key."],"exampleFix":"// before\nSecretKey key = new SecretKeySpec(new byte[16], \"AES\"); // 128 bits\nJwts.builder().encryptWith(key, Jwts.SIG.A256GCM, alg).compact();\n// after\nSecretKey key = Jwts.SIG.A256GCM.key().build(); // 256 bits\nJwts.builder().encryptWith(key, Jwts.SIG.A256GCM, alg).compact();","handlingStrategy":"validation","validationCode":"static boolean isAesKeyLongEnough(SecretKey key, int requiredBits) {\n    return key != null && key.getEncoded() != null\n        && key.getEncoded().length * 8 >= requiredBits;\n}\nif (!isAesKeyLongEnough(key, 256)) throw new IllegalArgumentException(\"A256GCM needs a 256-bit key\");","typeGuard":"boolean isAesKey(Key k) { return k instanceof SecretKey && \"AES\".equals(((SecretKey) k).getAlgorithm()); }","tryCatchPattern":"try {\n    Jwts.builder().encryptWith(key, Jwts.SIG.A256GCM, alg).compact();\n} catch (WeakKeyException e) {\n    logger.error(\"AES key too small: {}\", e.getMessage());\n    key = Jwts.SIG.A256GCM.key().build();\n}","preventionTips":["Always generate keys with Jwts.SIG.<alg>.key().build() instead of hand-rolling byte arrays","Log key size (never the key) at startup to verify configuration","Store secrets base64-encoded at full required length","Write a unit test asserting encoded key bit length per algorithm"],"tags":["java","jjwt","weak-key","aes","jwe"],"backgroundTag":"invalid-argument-value","analyzedSha":"fb71496164c71442d08adec4571d9616ed5e1b8d","analyzedAt":"2026-09-09T00:33:09.982Z","contentChangedAt":"2026-09-09T00:33:09.982Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}