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 ef11d2dead0..425f87704e4 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 3c662698c95..de4d7d0f6be 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 00000000000..cc375589db0 --- /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. +====