This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/trust-root in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit ecff42222843b44618bc832ca15b5ffa19bbfa43 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Wed Dec 17 22:58:21 2025 +0100 docs: recommend use of appropriately scoped trust roots This change adds an important note to the documentation for `log4j2.trustStoreLocation` and the `TrustStore` plugin, advising users to configure trust stores with trust roots that are appropriate for their communication scope. The recommendation is grounded in public guidance from [NIST SP 800-52 Rev. 2: *Guidelines for the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations*](https://csrc.nist.gov/pubs/sp/800/52/r2/final), which advises minimizing trust anchors to those necessary for the intended connections. --- .../ROOT/pages/manual/appenders/network.adoc | 2 ++ .../properties-transport-security.adoc | 2 ++ .../partials/manual/trust-store-admonition.adoc | 24 ++++++++++++++++++++++ 3 files changed, 28 insertions(+) diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc index ef11d2dead..07e013d3ec 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc @@ -167,6 +167,8 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin The trust store is meant to contain the CA certificates you are willing to trust when a remote party presents its certificate. It determines whether the remote authentication credentials (and thus the connection) should be trusted. +include::partial$manual/trust-store-admonition.adoc[] + [#TrustStoreConfiguration-attributes] .`TrustStore` configuration attributes [cols="1m,1,1,5"] diff --git a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-transport-security.adoc b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-transport-security.adoc index 3c662698c9..ca466c69af 100644 --- a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-transport-security.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-transport-security.adoc @@ -130,6 +130,8 @@ The username used in HTTP Basic authentication. The location of the trust store. +include::partial$manual/trust-store-admonition.adoc[] + [id=log4j2.trustStorePassword] == `log4j2.trustStorePassword` diff --git a/src/site/antora/modules/ROOT/partials/manual/trust-store-admonition.adoc b/src/site/antora/modules/ROOT/partials/manual/trust-store-admonition.adoc new file mode 100644 index 0000000000..eb953f042c --- /dev/null +++ b/src/site/antora/modules/ROOT/partials/manual/trust-store-admonition.adoc @@ -0,0 +1,24 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + +[IMPORTANT] +==== +Log4j Core typically does not typically communicate with external organizations; therefore, the default trust store provided by the Java Runtime Environment is usually not appropriate. + +When configuring a trust store for Log4j Core, follow established best practices. For example, +https://csrc.nist.gov/pubs/sp/800/52/r2/final[NIST SP 800-52 Rev. 2] (ยง4.5.2) recommends using a trust store that contains only the CA certificates required for the intended communication scope, such as a private or enterprise CA. This limits exposure to unintended or compromised CA certificates in the default trust store. +====
