[httpcomponents-core] branch master updated: Add security warning to TrustStrategy documentation (#438)

[ol...@apache.org]

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

olegk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/httpcomponents-core.git


The following commit(s) were added to refs/heads/master by this push:
     new 0d4aeb557 Add security warning to TrustStrategy documentation (#438)
0d4aeb557 is described below

commit 0d4aeb557737ac717e62c6375ca0d8a86f5f886b
Author: Marcono1234 <Ma...@users.noreply.github.com>
AuthorDate: Tue Oct 3 22:13:54 2023 +0200

    Add security warning to TrustStrategy documentation (#438)
---
 .../java/org/apache/hc/core5/ssl/SSLContextBuilder.java     |  5 +++++
 .../main/java/org/apache/hc/core5/ssl/TrustStrategy.java    | 13 +++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/httpcore5/src/main/java/org/apache/hc/core5/ssl/SSLContextBuilder.java b/httpcore5/src/main/java/org/apache/hc/core5/ssl/SSLContextBuilder.java
index 97f2b4b1f..710ae8710 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/ssl/SSLContextBuilder.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/ssl/SSLContextBuilder.java
@@ -253,6 +253,11 @@ public class SSLContextBuilder {
         return this;
     }
 
+    /**
+     * @param trustStrategy
+     *            custom trust strategy to use; can be {@code null} in which case
+     *            only the default trust managers will be used
+     */
     public SSLContextBuilder loadTrustMaterial(
             final KeyStore trustStore,
             final TrustStrategy trustStrategy) throws NoSuchAlgorithmException, KeyStoreException {
diff --git a/httpcore5/src/main/java/org/apache/hc/core5/ssl/TrustStrategy.java b/httpcore5/src/main/java/org/apache/hc/core5/ssl/TrustStrategy.java
index 1596d9214..8b5eceab5 100644
--- a/httpcore5/src/main/java/org/apache/hc/core5/ssl/TrustStrategy.java
+++ b/httpcore5/src/main/java/org/apache/hc/core5/ssl/TrustStrategy.java
@@ -34,6 +34,19 @@ import java.security.cert.X509Certificate;
  * configured in the actual SSL context. This interface can be used to override the standard
  * JSSE certificate verification process.
  *
+ * <h2>Security Warning</h2>
+ * If a trust strategy considers a certificate chain to be trusted, then the default trust manager
+ * will not be consulted. Trust strategy implementations should therefore consider properly checking
+ * the complete certificate chain. Checking for example only the subject of a certificate does not
+ * protect against man-in-the-middle attacks. For self-signed certificates prefer specifying a keystore
+ * containing the certificate chain when calling the {@link SSLContextBuilder} {@code loadTrustMaterial}
+ * methods instead of implementing a custom trust strategy.
+ *
+ * <p>A trust strategy alone cannot be used for certificate pinning. When {@code isTrusted} returns
+ * {@code false} the certificate check falls back to the trust manager which might consider
+ * the certificate trusted. See the {@link #isTrusted(X509Certificate[], String)} documentation.
+ *
+ * @see SSLContextBuilder
  * @since 4.4
  */
 public interface TrustStrategy {