You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2026/03/13 09:36:28 UTC

(camel) 01/01: Document PQC TLS configuration for end users

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

acosentino pushed a commit to branch tls-docs
in repository https://gitbox.apache.org/repos/asf/camel.git

commit a2a025692d6c0178d7fdee0dbef06507a4e818ec
Author: Andrea Cosentino <an...@gmail.com>
AuthorDate: Fri Mar 13 10:31:31 2026 +0100

    Document PQC TLS configuration for end users
    
    Add comprehensive PQC TLS documentation covering auto-configuration,
    explicit configuration via properties and Java DSL, JDK requirements,
    migration guidance, and the distinction between TLS-layer and
    application-layer PQC.
---
 .../ROOT/pages/camel-4x-upgrade-guide-4_19.adoc    |  13 ++
 .../ROOT/pages/camel-configuration-utilities.adoc  | 194 +++++++++++++++++++++
 docs/user-manual/modules/ROOT/pages/security.adoc  |   7 +
 3 files changed, 214 insertions(+)

diff --git a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_19.adoc b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_19.adoc
index 63aac1a1808a..ec451b9fbc2c 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_19.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_19.adoc
@@ -27,6 +27,19 @@ The cloud integration from the following components has been removed: `camel-con
 
 === camel-core
 
+==== PQC TLS Auto-Configuration
+
+When running on a JDK that supports `X25519MLKEM768` (typically JDK 25+), Camel now automatically
+configures post-quantum hybrid named groups on all `SSLContextParameters` instances. The preferred
+group ordering is: `X25519MLKEM768`, `x25519`, `secp256r1`, `secp384r1`, followed by the remaining
+JVM defaults.
+
+This auto-configuration activates only when the user has not explicitly set `namedGroups` or
+`namedGroupsFilter`. No changes are required for existing applications — the hybrid key exchange
+is backward-compatible with peers that do not support PQC.
+
+See xref:camel-configuration-utilities.adoc[JSSE Utility] for full details on PQC TLS configuration.
+
 The WireTap EIP has removed the `pattern` option from its model (not in use) as wiretap always
 uses `InOnly` pattern.
 
diff --git a/docs/user-manual/modules/ROOT/pages/camel-configuration-utilities.adoc b/docs/user-manual/modules/ROOT/pages/camel-configuration-utilities.adoc
index 2db76abada0a..476671a0b76c 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-configuration-utilities.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-configuration-utilities.adoc
@@ -361,6 +361,200 @@ See above
 namedGroupsFilter::
 See above
 
+signatureSchemes::
+This optional property represents a collection of explicitly named
+TLS signature schemes to enable on both the client and server side
+as well as in the SSLEngine. Signature schemes control which signature
+algorithms are available during the TLS handshake, including post-quantum
+signature algorithms such as `ML-DSA`. These values take precedence over
+filters supplied in signatureSchemesFilter. The utility attempts to
+enable the listed signature schemes regardless of whether the JSSE
+provider actually supports them or not. No default filtering is applied
+to signature schemes.
+signatureSchemesFilter::
+This optional property represents a collection of include and exclude
+patterns for signature schemes to enable on both the client and server
+side as well as in the SSLEngine. The patterns are applied over only the
+available signature schemes. The excludes patterns have precedence over
+the includes patterns. No default filtering is applied to signature
+schemes.
+
+== Post-Quantum Cryptography (PQC) TLS Configuration
+
+Starting with Camel 4.19, Apache Camel supports Post-Quantum Cryptography (PQC) at the TLS transport layer.
+This protects connections against _harvest-now-decrypt-later_ attacks, where an adversary captures
+encrypted traffic today with the intent to decrypt it once a cryptographically relevant quantum computer
+becomes available.
+
+=== JDK Requirements
+
+PQC TLS support requires a JDK that implements post-quantum key exchange algorithms.
+JDK 25+ is expected to include support for `X25519MLKEM768`, a hybrid key exchange
+that combines the classical X25519 algorithm with the ML-KEM-768 post-quantum algorithm
+(NIST FIPS 203).
+
+To verify whether your JDK supports PQC named groups, you can inspect the available groups:
+
+[source,java]
+----
+SSLContext ctx = SSLContext.getDefault();
+SSLEngine engine = ctx.createSSLEngine();
+String[] groups = engine.getSSLParameters().getNamedGroups();
+System.out.println(Arrays.toString(groups));
+// Look for X25519MLKEM768 in the output
+----
+
+=== Auto-Configuration (Zero-Config PQC)
+
+When running on a JDK that supports `X25519MLKEM768`, Camel *automatically* configures
+PQC-preferred named groups on all `SSLContextParameters` instances — no configuration is required.
+
+The auto-configuration activates only when:
+
+* The user has *not* explicitly set `namedGroups` or `namedGroupsFilter`
+* The JVM's TLS provider reports `X25519MLKEM768` as an available named group
+
+When activated, Camel sets the following named group ordering:
+
+[source,text]
+----
+X25519MLKEM768, x25519, secp256r1, secp384r1, [remaining JVM defaults...]
+----
+
+This ensures post-quantum key exchange is preferred while maintaining backward compatibility
+with servers that do not yet support PQC. A log message confirms activation:
+
+[source,text]
+----
+INFO  o.a.c.s.j.SSLContextParameters - Auto-configured PQC named groups: [X25519MLKEM768, x25519, secp256r1, secp384r1, ...]
+----
+
+=== Explicit Configuration via application.properties
+
+You can explicitly control PQC TLS settings in `application.properties`:
+
+[source,properties]
+----
+# Enable SSL
+camel.ssl.enabled = true
+
+# Explicit named groups ordering (PQC-first)
+camel.ssl.namedGroups = X25519MLKEM768,x25519,secp256r1,secp384r1
+
+# Explicit signature schemes (if your JDK supports PQC signatures)
+camel.ssl.signatureSchemes = ML-DSA,ECDSA,RSA
+----
+
+You can also use include/exclude filters instead of explicit lists:
+
+[source,properties]
+----
+# Include only PQC and ECDH groups
+camel.ssl.namedGroupsInclude = X25519MLKEM768,x25519,secp256r1
+
+# Exclude specific groups
+camel.ssl.namedGroupsExclude = ffdhe2048
+----
+
+NOTE: When `namedGroups` is set explicitly, include/exclude filters are ignored.
+When neither `namedGroups` nor filters are set, auto-configuration applies.
+
+=== Explicit Configuration via Java DSL
+
+You can also configure PQC TLS programmatically using `SSLContextParameters`:
+
+[source,java]
+----
+KeyStoreParameters ksp = new KeyStoreParameters();
+ksp.setResource("file:/path/to/keystore.jks");
+ksp.setPassword("keystorePassword");
+
+KeyManagersParameters kmp = new KeyManagersParameters();
+kmp.setKeyStore(ksp);
+kmp.setKeyPassword("keyPassword");
+
+// Configure named groups with PQC preference
+NamedGroupsParameters ngp = new NamedGroupsParameters();
+ngp.setNamedGroup(List.of("X25519MLKEM768", "x25519", "secp256r1", "secp384r1"));
+
+SSLContextParameters scp = new SSLContextParameters();
+scp.setKeyManagers(kmp);
+scp.setNamedGroups(ngp);
+
+SSLContext context = scp.createSSLContext();
+----
+
+=== Disabling PQC Auto-Configuration
+
+If you need to disable PQC auto-configuration (for example, for compatibility testing),
+set the named groups explicitly to classical-only values:
+
+[source,properties]
+----
+camel.ssl.namedGroups = x25519,secp256r1,secp384r1
+----
+
+Or use a named groups filter:
+
+[source,properties]
+----
+camel.ssl.namedGroupsExclude = X25519MLKEM768
+----
+
+=== TLS-Layer PQC vs. Application-Layer PQC
+
+Camel provides PQC protection at two distinct layers:
+
+[cols="1,1,1",options="header"]
+|===
+| Aspect | TLS-Layer PQC | Application-Layer PQC (camel-pqc)
+
+| *Scope*
+| Transport security (TLS handshake)
+| Message payload encryption and signing
+
+| *Configuration*
+| `camel.ssl.*` properties or `SSLContextParameters`
+| `camel-pqc` component and `pqc` data format
+
+| *Protects*
+| Data in transit between endpoints
+| Data at rest and message payloads
+
+| *Algorithms*
+| X25519MLKEM768 (hybrid KEM)
+| ML-KEM, ML-DSA, SLH-DSA, LMS, XMSS, Falcon, and more
+
+| *JDK requirement*
+| JDK 25+ (for built-in PQC named groups)
+| JDK 21+ with Bouncy Castle provider
+
+| *User action*
+| Zero-config on JDK 25+ (auto-configured)
+| Requires explicit component configuration
+|===
+
+Both layers are complementary and can be used together for defense in depth:
+
+* *TLS-layer PQC* secures the connection between Camel and external services (brokers, APIs, databases)
+* *Application-layer PQC* (`camel-pqc`) secures the message content itself, independent of transport
+
+For full application-layer PQC documentation, see xref:components::pqc-component.adoc[PQC Component]
+and xref:components:dataformats:pqc-dataformat.adoc[PQC Data Format].
+
+=== Migration from Classical TLS
+
+For users currently running classical TLS, migration to PQC TLS is straightforward:
+
+1. **Upgrade your JDK** to JDK 25+ (or a JDK that supports `X25519MLKEM768`)
+2. **Upgrade Camel** to 4.19 or later
+3. **No configuration changes needed** — PQC named groups are auto-configured
+4. **Verify** that your TLS peers (servers, brokers, load balancers) support PQC key exchange or
+at least accept the classical fallback groups (`x25519`, `secp256r1`)
+
+The hybrid nature of `X25519MLKEM768` ensures that even if the remote peer does not support
+PQC, the handshake gracefully falls back to classical key exchange using the next available group.
+
 == Examples
 
 === Setting Client Authentication on the Server Side
diff --git a/docs/user-manual/modules/ROOT/pages/security.adoc b/docs/user-manual/modules/ROOT/pages/security.adoc
index 6bf4ee7311ee..d5e66b29795a 100644
--- a/docs/user-manual/modules/ROOT/pages/security.adoc
+++ b/docs/user-manual/modules/ROOT/pages/security.adoc
@@ -55,6 +55,13 @@ ability to secure payloads as well as provide
 authentication/authorization capabilities at endpoints created using the
 components.
 
+=== Post-Quantum TLS
+
+Camel supports Post-Quantum Cryptography (PQC) at the TLS transport layer.
+On JDK 25+, Camel automatically configures hybrid post-quantum key exchange
+(`X25519MLKEM768`) to protect connections against harvest-now-decrypt-later attacks.
+See xref:camel-configuration-utilities.adoc[JSSE Utility] for configuration details.
+
 == Configuration Security
 
 Camel offers the xref:components::properties-component.adoc[Properties] component to