{"record":{"id":"346fbaac64346041","repo":"elastic/elasticsearch","slug":"failed-to-load-the-system-pkcs-11-truststore","errorCode":null,"errorMessage":"failed to load the system PKCS#11 truststore","messagePattern":"failed to load the system PKCS#11 truststore","errorType":"exception","errorClass":"SslConfigException","httpStatus":null,"severity":"critical","filePath":"libs/ssl-config/src/main/java/org/elasticsearch/common/ssl/DefaultJdkTrustConfig.java","lineNumber":86,"sourceCode":"            throw new SslConfigException(\"failed to initialize a TrustManager for the system keystore\", e);\n        }\n    }\n\n    /**\n     * When a PKCS#11 token is used as the system default keystore/truststore, we need to pass the keystore\n     * password when loading, even for reading certificates only ( as opposed to i.e. JKS keystores where\n     * we only need to pass the password for reading Private Key entries ).\n     *\n     * @return the KeyStore used as truststore for PKCS#11 initialized with the password, null otherwise\n     */\n    private KeyStore getSystemTrustStore() {\n        if (isPkcs11Truststore(systemProperties) && trustStorePassword != null) {\n            try {\n                KeyStore keyStore = KeyStore.getInstance(\"PKCS11\");\n                keyStore.load(null, trustStorePassword);\n                return keyStore;\n            } catch (GeneralSecurityException | IOException e) {\n                throw new SslConfigException(\"failed to load the system PKCS#11 truststore\", e);\n            }\n        }\n        return null;\n    }\n\n    private static boolean isPkcs11Truststore(BiFunction<String, String, String> systemProperties) {\n        return systemProperties.apply(\"javax.net.ssl.trustStoreType\", \"\").equalsIgnoreCase(\"PKCS11\");\n    }\n\n    private static char[] getSystemTrustStorePassword(BiFunction<String, String, String> systemProperties) {\n        return systemProperties.apply(\"javax.net.ssl.trustStorePassword\", \"\").toCharArray();\n    }\n\n    @Override\n    public Collection<Path> getDependentFiles() {\n        return List.of();\n    }\n","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/ssl-config/src/main/java/org/elasticsearch/common/ssl/DefaultJdkTrustConfig.java#L68-L104","documentation":"Thrown as SslConfigException by DefaultJdkTrustConfig.getSystemTrustStore when the system is configured to use a PKCS#11 token as its SSL trust store (javax.net.ssl.trustStoreType=PKCS11) and loading the PKCS#11 KeyStore fails. The password for the PKCS#11 token is read from javax.net.ssl.trustStorePassword. The underlying GeneralSecurityException or IOException is the cause.","triggerScenarios":"System property javax.net.ssl.trustStoreType is set to 'PKCS11' (case-insensitive), javax.net.ssl.trustStorePassword is non-null, and KeyStore.getInstance(\"PKCS11\").load(null, password) throws. Causes include: PKCS#11 provider not configured, wrong PIN/password, hardware token not inserted, or provider config file missing.","commonSituations":"Running Elasticsearch with an HSM or smart-card-backed trust store on a host where the SunPKCS11 provider is not properly configured (missing provider config via -Djava.security.properties or security.provider entries). Also when the token PIN is wrong or the token is physically absent. Common in FIPS-compliant or enterprise PKI deployments.","solutions":["Verify the PKCS#11 provider is registered in java.security (e.g. security.provider.N=SunPKCS11 /path/to/config).","Confirm the HSM/token is connected and unlocked with the correct PIN (javax.net.ssl.trustStorePassword)."],"exampleFix":"// before — PKCS11 truststore type set but provider unconfigured\n-Djavax.net.ssl.trustStoreType=PKCS11\n\n// after — configure the SunPKCS11 provider with a valid config file\n-Djavax.net.ssl.trustStoreType=PKCS11\n-Djava.security.properties==pkcs11.properties\n// pkcs11.properties contains:\n//   security.provider.1=SunPKCS11 /etc/pkcs11/sunpkcs11.cfg","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    X509ExtendedTrustManager tm = defaultJdkTrustConfig.createTrustManager();\n} catch (SslConfigException e) {\n    // cause is GeneralSecurityException or IOException from PKCS11 KeyStore.load\n    log.error(\"PKCS11 trust store load failed: {}\", e.getMessage(), e.getCause());\n    // verify SunPKCS11 provider config, token presence, and PIN correctness\n}","preventionTips":["Register the SunPKCS11 provider in java.security with a valid config file before using PKCS11 trust stores.","Confirm the HSM/token is physically present and unlocked.","Verify javax.net.ssl.trustStorePassword is the correct token PIN.","Test PKCS11 connectivity with keytool -list -keystore NONE -storetype PKCS11 before starting Elasticsearch."],"tags":["ssl","tls","pkcs11","hsm","trust-store","security","elasticsearch","fips"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}