{"record":{"id":"65426dd9135387b1","repo":"apache/pulsar","slug":"failed-to-set-the-private-key","errorCode":null,"errorMessage":"Failed to set the private key","messagePattern":"Failed to set the private key","errorType":"exception","errorClass":"KeyStoreException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/util/KeyStoreHolder.java","lineNumber":107,"sourceCode":"     *         reachable.\n     */\n    public char[] getEntryPassword() {\n        return Arrays.copyOf(entryPassword, entryPassword.length);\n    }\n\n    public void setCertificate(String alias, Certificate certificate) throws KeyStoreException {\n        try {\n            keyStore.setCertificateEntry(alias, certificate);\n        } catch (GeneralSecurityException e) {\n            throw new KeyStoreException(\"Failed to set the certificate\", e);\n        }\n    }\n\n    public void setPrivateKey(String alias, PrivateKey privateKey, Certificate[] certChain) throws KeyStoreException {\n        try {\n            keyStore.setKeyEntry(alias, privateKey, entryPassword, certChain);\n        } catch (GeneralSecurityException e) {\n            throw new KeyStoreException(\"Failed to set the private key\", e);\n        }\n    }\n\n}\n","sourceCodeStart":89,"sourceCodeEnd":112,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/util/KeyStoreHolder.java#L89-L112","documentation":"KeyStoreHolder.setPrivateKey() wraps any GeneralSecurityException thrown by KeyStore.setKeyEntry() in a KeyStoreException with the message \"Failed to set the private key\", with the original exception as cause. The entry is protected with the holder's internal entry password.","triggerScenarios":"Calling setPrivateKey(alias, privateKey, certChain) where the key/chain is rejected: null private key, cert chain mismatched with the key, key algorithm unsupported by the store type/provider (e.g. FIPS store rejecting certain key algorithms), or uninitialized store.","commonSituations":"Loading TLS client certs from PEM files where the private key does not match the certificate chain (wrong key/cert pair from separate files); RSA vs EC key issues under FIPS providers; corrupted PEM-to-PKCS8 conversion; provider-pinned stores enforcing algorithm restrictions.","solutions":["Read the cause to find the real reason (unrecoverable key, algorithm not supported, invalid key format).","Verify the PrivateKey matches the first certificate in the chain (compare public keys) before calling setPrivateKey.","Ensure the key is in a format supported by the store type/provider (PKCS8; convert with openssl if needed).","Confirm the holder was constructed successfully and the store is not in a failed state before adding key entries."],"exampleFix":"// before\nholder.setPrivateKey(\"broker\", wrongKey, brokerChain); // key does not match chain\n// after\nif (!wrongKeyEqualsCert(wrongKey, brokerChain[0])) {\n    throw new IllegalArgumentException(\"private key does not match certificate\");\n}\nholder.setPrivateKey(\"broker\", wrongKey, brokerChain);","handlingStrategy":"validation","validationCode":"static void requireKeyMatchesChain(PrivateKey key, Certificate[] chain) {\n    if (key == null || chain == null || chain.length == 0) {\n        throw new IllegalArgumentException(\"private key and non-empty chain required\");\n    }\n    try {\n        chain[0].verify(key.getPublic() instanceof PublicKey\n                ? (PublicKey) key.getPublic() : chain[0].getPublicKey());\n    } catch (Exception e) {\n        throw new IllegalArgumentException(\"private key does not match certificate chain\", e);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    holder.setPrivateKey(alias, privateKey, certChain);\n} catch (KeyStoreException e) {\n    // cause: key/chain mismatch, unsupported algorithm, provider restriction\n    throw new RuntimeException(\"cannot store key '\" + alias + \"': \" + e.getCause(), e);\n}","preventionTips":["Verify the PrivateKey corresponds to chain[0] before storing","Convert PEM keys to PKCS8 and confirm the algorithm is accepted by the store provider","In FIPS/pinned-provider setups, confirm key algorithms (RSA/EC) are approved","Initialize the holder once at startup so key-entry failures aren't confused with store-creation failures"],"tags":["security","keystore","tls","private-key"],"backgroundTag":"keystore-entry-rejected","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}