{"record":{"id":"c4f8e4f05f3ee173","repo":"jwtk/jjwt","slug":"passwords-are-intended-for-use-with-key-derivation","errorCode":null,"errorMessage":"Passwords are intended for use with key derivation algorithms only.","messagePattern":"Passwords are intended for use with key derivation algorithms only\\.","errorType":"validation","errorClass":"InvalidKeyException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java","lineNumber":166,"sourceCode":"    }\n\n    @Override\n    protected void validateKey(Key k, boolean signing) {\n\n        final String keyType = keyType(signing);\n        if (k == null) {\n            throw new IllegalArgumentException(\"MAC \" + keyType + \" key cannot be null.\");\n        }\n\n        if (!(k instanceof SecretKey)) {\n            String msg = \"MAC \" + keyType + \" keys must be SecretKey instances.  Specified key is of type \" +\n                    k.getClass().getName();\n            throw new InvalidKeyException(msg);\n        }\n\n        if (k instanceof Password) {\n            String msg = \"Passwords are intended for use with key derivation algorithms only.\";\n            throw new InvalidKeyException(msg);\n        }\n\n        final SecretKey key = (SecretKey) k;\n\n        final String id = getId();\n\n        assertAlgorithmName(key, signing);\n\n        int size = KeysBridge.findBitLength(key);\n\n        // We can only perform length validation if key bit length is available\n        // per https://github.com/jwtk/jjwt/issues/478 and https://github.com/jwtk/jjwt/issues/619\n        // so return early if we can't:\n        if (size < 0) return;\n\n        if (size < this.minKeyBitLength) {\n            String msg = \"The \" + keyType + \" key's size is \" + size + \" bits which \" +\n                    \"is not secure enough for the \" + id + \" algorithm.\";","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java#L148-L184","documentation":"InvalidKeyException from DefaultMacAlgorithm.validateKey when a jjwt Password instance is supplied to a MAC algorithm. Password objects are reserved for password-based key-derivation algorithms (e.g. PBES2) and must not be used directly as MAC keys.","triggerScenarios":"Calling Jwts.builder().signWith(password, HS256) where password = Jwts.password().of(...) or io.jsonwebtoken.security.Password obtained for PBKDF2/PBES2 flows.","commonSituations":"Using the user password object everywhere after setting up PBES2 encryption; confusing 'secret string' keys with jjwt Password wrappers; following an outdated tutorial that wraps passwords as keys.","solutions":["Derive a real SecretKey from the password first, or use the PBES2 family (Jwts.SIG.PS256 with a password, or JWE PBES2 key algorithms).","Convert the raw password bytes to a key: Keys.hmacShaKeyFor(derivedBytes).","Pass a SecretKeySpec instead of a Password if you truly intend HMAC.","Separate password handling (key derivation) from signing key handling in your code."],"exampleFix":"// before\nPassword pw = Jwts.password().of(chars);\nJwts.builder().signWith(pw, Jwts.SIG.HS256);\n// after\nSecretKey key = Keys.hmacShaKeyFor(pw.getBytes()); // derived MAC key\nJwts.builder().signWith(key, Jwts.SIG.HS256);","handlingStrategy":"type-guard","validationCode":"static SecretKey requireNonPassword(Key k) {\n    if (k instanceof io.jsonwebtoken.security.Password)\n        throw new IllegalArgumentException(\"Use Password only with key-derivation algorithms; derive a SecretKey for MAC\");\n    return (SecretKey) k;\n}","typeGuard":"boolean isPasswordKey(Key k) { return k instanceof io.jsonwebtoken.security.Password; }","tryCatchPattern":"try {\n    return Jwts.builder().signWith(key, Jwts.SIG.HS256).compact();\n} catch (InvalidKeyException e) {\n    if (e.getMessage().contains(\"key derivation algorithms only\"))\n        throw new IllegalStateException(\"Password used directly as MAC key\");\n    throw e;\n}","preventionTips":["Keep Password objects confined to PBKDF2/PBES2 code paths","Derive an explicit SecretKey (e.g. via hmacShaKeyFor) before MAC operations","Document the distinction between 'password' and 'key' in your crypto helpers"],"tags":["java","jjwt","password","mac","key-derivation"],"backgroundTag":"incompatible-source-type","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"}