TLS Registry

JVM since3.36.0 Native since3.36.0 🧪Experimental

Configuration bridge for the Quarkus TLS registry and Camel SSLContextParameters

Maven coordinates

Create a new project with this extension on code.quarkus.io

Or add the coordinates to your existing project:

<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-tls-registry</artifactId>
</dependency>

Check the User guide for more information about writing Camel Quarkus applications.

Usage

This extension provides integration between Quarkus TLS Registry and Camel SSLContextParameters. When enabled, TLS configurations defined via quarkus.tls.* properties are automatically converted and registered as SSLContextParameters beans in the Camel registry.

This eliminates the need to configure TLS separately for Quarkus and Camel components - configure it once in Quarkus, and use it everywhere in your Camel routes.

Basic Configuration

Default TLS Configuration

Configure a default TLS configuration using quarkus.tls.* properties:

# Default TLS configuration
quarkus.tls.key-store.p12.path=/etc/ssl/keystore.p12
quarkus.tls.key-store.p12.password=changeit
quarkus.tls.trust-store.p12.path=/etc/ssl/truststore.p12
quarkus.tls.trust-store.p12.password=changeit

This creates an SSLContextParameters bean named defaultSslContextParameters that can be referenced in your routes:

from("timer:tick")
    .to("https://api.example.com?sslContextParameters=#defaultSslContextParameters");
The bean name for the default TLS configuration can be customized using quarkus.camel.tls-registry.default-bean-name.

Named TLS Configurations

Define multiple named TLS configurations for different purposes (e.g., separate client and server certificates):

# Client TLS configuration
quarkus.tls.client.key-store.p12.path=/etc/ssl/client-keystore.p12
quarkus.tls.client.key-store.p12.password=changeit
quarkus.tls.client.trust-all=true

# Server TLS configuration
quarkus.tls.server.key-store.p12.path=/etc/ssl/server-keystore.p12
quarkus.tls.server.key-store.p12.password=changeit
quarkus.tls.server.trust-store.p12.path=/etc/ssl/server-truststore.p12

Named configurations are automatically discovered and registered as beans with their configuration name:

// Use the client certificate
from("timer:tick")
    .to("https://api.example.com?sslContextParameters=#client");

// Use the server certificate
from("netty-http:https://0.0.0.0:8443/secure?sslContextParameters=#server")
    .to("log:requests");

Global SSL Context

You can set the Quarkus default TLS configuration as Camel’s global SSLContextParameters:

quarkus.camel.tls-registry.quarkus-default-as-global=true

# Default TLS configuration becomes global
quarkus.tls.key-store.p12.path=/etc/ssl/keystore.p12
quarkus.tls.key-store.p12.password=changeit

When configured as global, Camel components can opt in to using it automatically:

from("timer:tick")
    // No need to specify sslContextParameters, uses global SSL context
    .to("https://api.example.com?useGlobalSslContextParameters=true");

Protocols And Cipher Suites

The protocols, cipher suites and key exchange groups set on a Quarkus TLS configuration are carried over to the SSLContextParameters bean and enforced on every SSLEngine and socket factory Camel derives from it:

quarkus.tls.protocols=TLSv1.3,TLSv1.2
quarkus.tls.cipher-suites=TLS_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
quarkus.tls.key-exchange-groups=x25519,secp384r1
quarkus.tls.protocols defaults to TLSv1.3. Camel components consuming a bridged bean therefore negotiate TLSv1.3 only unless you widen the property, matching the behaviour of every other consumer of the same Quarkus TLS configuration. Set quarkus.tls.protocols=TLSv1.3,TLSv1.2 if you need to talk to endpoints that do not support TLSv1.3.
Camel applies a configured list verbatim, in preference to its own default exclusion filters. Because quarkus.tls.protocols always carries a value, those filters never exclude the SSLv2 and SSLv3 protocols from a bridged configuration, and they exclude the NULL, anon, EXPORT, DES, MD5 and RC4 cipher suites only while quarkus.tls.cipher-suites is unset. A weak protocol or cipher suite that you configure explicitly is used as configured.

A value that the JVM does not recognise is rejected rather than ignored, failing the creation of the SSL context. This includes OpenSSL style cipher suite names such as ECDHE-RSA-AES128-GCM-SHA256, which Vert.x accepts when quarkus.tls.<name>.ssl-engine is set to openssl. Use the JSSE names, for example TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, for a configuration that Camel components consume.

Options That Cannot Be Bridged

Some quarkus.tls.* options have no equivalent in SSLContextParameters, because they are applied by Vert.x rather than by the JSSE SSLContext:

Option Notes

certificate-revocation-list

Not carried over. Camel components using a bridged bean do not check certificate revocation and accept a revoked certificate that the rest of the application rejects. A warning is logged at startup when this option is set.

hostname-verification-algorithm

Not carried over. Configure hostname verification on the consuming Camel component or endpoint instead. A warning is logged at startup when this option is set.

key-store.sni

Not carried over. Server name indication is a Vert.x transport concern.

alpn

Not carried over. Protocol negotiation is handled by the consuming component.

pqc-enforcement-policy

Not carried over. Use quarkus.tls.<name>.key-exchange-groups, which is, to constrain the groups Camel offers.

These options continue to apply to Quarkus’s own TLS consumers as normal. Only the Camel bridge is affected.

Certificate Reload

The extension automatically observes certificate reload events from Quarkus TLS registry. When certificates are reloaded (e.g., due to file system changes), the corresponding SSLContextParameters beans are updated and Camel routes are restarted to pick up the new certificates.

This feature is enabled by default but can be controlled via configuration:

# Enable certificate reloading
quarkus.tls.reload-period=1h

# Enable/disable certificate reload (default: true)
quarkus.camel.tls-registry.reload-on-certificate-update=true

# Debounce delay in milliseconds to avoid multiple reloads (default: 2000)
quarkus.camel.tls-registry.reload-certificate-delay=2000

The debounce delay ensures that when multiple certificates are updated in quick succession, only a single Camel context reload occurs after all updates have stabilized.

For more information see the Quarkus TLS Registry Reference Guide.

Bean Name Conflicts

If you have an existing SSLContextParameters bean with the same name as a Quarkus TLS configuration, the extension will throw an IllegalStateException at startup with a helpful message.

To resolve this, you can either:

  1. Remove or rename the existing SSLContextParameters bean, or

  2. Rename the Quarkus TLS configuration (e.g., quarkus.tls.my-config.* instead of the conflicting name)

PEM Format Support

Quarkus TLS registry supports both PKCS12 and PEM formats. The extension automatically works with both:

# PEM format
quarkus.tls.key-store.pem.cert=/etc/ssl/cert.pem
quarkus.tls.key-store.pem.key=/etc/ssl/key.pem
quarkus.tls.trust-store.pem.certs=/etc/ssl/ca-bundle.pem

# Or PKCS12 format
quarkus.tls.key-store.p12.path=/etc/ssl/keystore.p12
quarkus.tls.key-store.p12.password=changeit

Additional Resources

Additional Camel Quarkus configuration

Configuration property Type Default

quarkus.camel.tls-registry.enabled

Enable automatic conversion and registration of Quarkus TLS configurations as Camel SSLContextParameters beans.

When enabled, the default TLS configuration and any named configurations will be automatically discovered and registered as beans in the Camel registry.

boolean

true

quarkus.camel.tls-registry.quarkus-default-as-global

Whether to set the Quarkus default TLS configuration as Camel’s global SSLContextParameters.

When true, if a default TLS configuration exists (quarkus.tls.*), it will be converted and set as the global SSL context via CamelContext.setSSLContextParameters(). Components can opt in to this global context using useGlobalSslContextParameters=true.

boolean

false

quarkus.camel.tls-registry.default-bean-name

The name to use when registering the default TLS configuration as a bean.

Only applicable if the default configuration is not set as global (i.e., quarkus-default-as-global=false).

string

defaultSslContextParameters

quarkus.camel.tls-registry.reload-on-certificate-update

Enable automatic Camel Context reload when certificates are updated.

When enabled, if Quarkus reloads a certificate (e.g., file watch detects changes), the corresponding SSLContextParameters bean will be updated in the Camel registry and a context reload will be triggered to restart routes with the new certificates.

This uses Camel’s ContextReloadStrategy to gracefully restart routes without stopping the entire application.

To avoid excessive reloads when multiple certificates are updated in quick succession, the reload is debounced with a configurable delay. If additional certificate updates occur during this delay, the timer is reset, ensuring only one reload happens after all updates have stabilized.

boolean

true

quarkus.camel.tls-registry.reload-certificate-delay

Delay period to avoid excessive Camel Context reloads when multiple certificates are updated in quick succession.

long

2000

Configuration property fixed at build time. All other configuration properties are overridable at runtime.

Back to top