You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2025/12/17 21:58:38 UTC

(logging-log4j2) branch doc/2.x/trust-root created (now ecff422228)

This is an automated email from the ASF dual-hosted git repository.

pkarwasz pushed a change to branch doc/2.x/trust-root
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git


      at ecff422228 docs: recommend use of appropriately scoped trust roots

This branch includes the following new commits:

     new ecff422228 docs: recommend use of appropriately scoped trust roots

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



(logging-log4j2) 01/01: docs: recommend use of appropriately scoped trust roots

Posted by pk...@apache.org.
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 <pk...@apache.org>
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.
+====