This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new 9c22ca26d8 docs: recommend use of appropriately scoped trust roots
(#4006)
9c22ca26d8 is described below
commit 9c22ca26d817d0b6cde86475db56a3eb504adc43
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Wed Dec 17 23:52:25 2025 +0100
docs: recommend use of appropriately scoped trust roots (#4006)
* 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.
* fix: rename partial
---
.../ROOT/pages/manual/appenders/network.adoc | 2 ++
.../properties-transport-security.adoc | 2 ++
.../partials/manual/trust-store-guideline.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..425f87704e 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-guideline.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..de4d7d0f6b 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-guideline.adoc[]
+
[id=log4j2.trustStorePassword]
== `log4j2.trustStorePassword`
diff --git
a/src/site/antora/modules/ROOT/partials/manual/trust-store-guideline.adoc
b/src/site/antora/modules/ROOT/partials/manual/trust-store-guideline.adoc
new file mode 100644
index 0000000000..cc375589db
--- /dev/null
+++ b/src/site/antora/modules/ROOT/partials/manual/trust-store-guideline.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 communicate with external organizations;
therefore, the default trust store provided by the Java Runtime Environment is
often 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
reduces exposure to unintended or compromised CA certificates included in the
default trust store.
+====
