Back to Guides
Edit this Page

TLS registry reference

The TLS registry is a Quarkus extension centralizing the TLS configuration for the application. It allows to define the TLS configuration in a single place and to reference it from multiple places in the application.

The TLS extension should be automatically added to your project as soon as you use a compatible extension. For example, if your application uses Quarkus REST, gRPC or reactive routes, the TLS registry is automatically added to your project.

1. Examples

To configure a TLS connection, and more specifically the key stores and trust stores, you use the quarkus.tls.* properties.

Configuration directly under quarkus.tls is the default configuration that will be used by all the TLS connections in the application. However, you can also have specific configurations for specific connections by using the quarkus.tls.<name>.* properties.

1.1. Configure the HTTP server to use https://

To configure the HTTP server to use HTTPS, you can use the following configuration:

quarkus.tls.key-store.pem.0.cert=server.crt
quarkus.tls.key-store.pem.0.key=server.key
quarkus.http.insecure-requests=disabled # Reject HTTP requests

So you a p12 (PKCS12) key store, use the following configuration:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled # Reject HTTP requests

Instead of the default configuration, you can use a named configuration:

quarkus.tls.https.key-store.p12.path=server-keystore.p12
quarkus.tls.https.key-store.p12.password=secret
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=https

1.2. Configure a client to use https://

As an example to illustrate client configuration, we will use a gRPC client:

quarkus.tls.trust-store.jks.path=grpc-client-truststore.jks
quarkus.tls.trust-store.jks.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

1.3. Configuring mTLS

To configure mTLS, you need to configure both the server and the client. Both will receive a key store and a trust store:

  • the server key store contains the server certificate and private key

  • the client key store contains the client certificate and private key

  • the server trust store contains the client certificate (to authenticate the client)

  • the client trust store contains the server certificate (to authenticate the server)

quarkus.tls.my-server.key-store.p12.path=target/certs/grpc-keystore.p12
quarkus.tls.my-server.key-store.p12.password=password
quarkus.tls.my-server.trust-store.p12.path=target/certs/grpc-server-truststore.p12
quarkus.tls.my-server.trust-store.p12.password=password

quarkus.tls.my-client.trust-store.p12.path=target/certs/grpc-client-truststore.p12
quarkus.tls.my-client.trust-store.p12.password=password
quarkus.tls.my-client.key-store.p12.path=target/certs/grpc-client-keystore.p12
quarkus.tls.my-client.key-store.p12.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls-configuration-name=my-client
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

quarkus.http.ssl.client-auth=REQUIRED # Enable mTLS
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=my-server
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false

2. Referencing a TLS configuration

Once you have configured a named configuration using quarkus.tls.<name>, you need to reference it. This is done using the tls-configuration-name property:

quarkus.tls.https.key-store.p12.path=server-keystore.p12
quarkus.tls.https.key-store.p12.password=secret

quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=https # Reference the named configuration

3. Configuring TLS

Configuring TLS is mainly about key stores and trust stores. The configuration depends on the format (pem, p12, jks…​). There are other important properties too. This section details the various properties you can use to configure TLS.

3.1. Key stores

Key stores are used to store the private key and the certificate. They are mainly used on the server-side, but can also be used on the client-side when mTLS is used.

3.1.1. PEM key stores

PEM key stores are composed of a list of pair of two files: the certificate and the private key. The certificate file is a .crt or .pem file, and the private key file is often a .key file.

To configure a PEM key store, use the following properties:

quarkus.tls.key-store.pem.a.cert=server.crt
quarkus.tls.key-store.pem.a.key=server.key
quarkus.tls.key-store.pem.b.cert=my-second-cert.crt
quarkus.tls.key-store.pem.b.key=my-second-key.key

In general, you will only need one pair of certificate and private key. The certificate may contain multiple certificates (a chain), but there should be one private key.

When multiple pairs are configured, the selection is done using SNI (Server Name Indication). The client will send the server name it wants to connect to, and the server will select the appropriate pair of certificate and private key. Make sure SNI is enabled on both the client and server to use this feature.

When configuring multiple key/cert pairs, the order is following the lexicographical order of the name (a and b in the previous snippet). So, the first pair is the one with the lowest lexicographical order. You can define the order by using the quarkus.tls.key-store.pem.order property, for example: quarkus.tls.key-store.pem.order=b,c,a. This is important when using SNI, as the first pair is the default one.

3.1.2. PKCS12 key stores

PKCS12 key stores are a single file containing the certificate and the private key. To configure a PKCS12 key store, use the following properties:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret

.p12 files are password-protected, so you need to provide the password to open the key store. Also, they can include more than one certificate and private key. In this case, you can:

  • either provide the alias of the certificate and private key you want to use

  • or use SNI to select the appropriate certificate and private key (all keys must use the same password)

To configure the alias, use the following properties:

quarkus.tls.key-store.p12.path=server-keystore.p12
quarkus.tls.key-store.p12.password=secret
quarkus.tls.key-store.p12.alias=my-alias
quarkus.tls.key-store.p12.alias-password=my-alias-password

3.1.3. JKS key stores

JKS key stores are a single file containing the certificate and the private key. Note that the JKS format should be avoided as it is less secure than PKCS12. To configure a JKS key store, use the following properties:

quarkus.tls.key-store.jks.path=server-keystore.jks
quarkus.tls.key-store.jks.password=secret

.jks files are password-protected, so you need to provide the password to open the key store. Also, they can include more than one certificate and private key. In this case, you can:

  • either provide the alias of the certificate and private key you want to use

  • or use SNI to select the appropriate certificate and private key (all keys must use the same password)

To configure the alias, use the following properties:

quarkus.tls.key-store.jks.path=server-keystore.jks
quarkus.tls.key-store.jks.password=secret
quarkus.tls.key-store.jks.alias=my-alias
quarkus.tls.key-store.jks.alias-password=my-alias-password

3.1.4. SNI

Server Name Indication (SNI) is a TLS extension that allows a client to specify the hostname it is attempting to connect to during the TLS handshake. It enables a server to present different TLS certificates for multiple domains on a single IP address, facilitating secure communication for virtual hosting scenarios.

To enable SNI, use the following property:

quarkus.tls.key-store.sni=true # Disabled by default

With this setting enabled, the client indicate the server name during the TLS handshake, allowing the server to select the right certificate:

  • When configuring the keystore with PEM files, multiple CRT/Key must be given.

  • When configuring the keystore with a JKS or a P12 file, it selects one alias based on the SNI hostname. In this case, all the keystore password and alias password must be the same. Do not set the alias property in this case.

3.1.5. Credential providers

Instead of passing the key store password and alias password in the configuration, you can use a credential provider.

A credential provider offers a way to retrieve the key store password and alias password. Note that the credential provider is only used if the password / alias password are not set in the configuration.

To configure a credential provider, use the following properties:

# The name of the credential bucket in the credentials provider
quarkus.tls.key-store.credentials-provider.name=my-credentials

# The name of the bean providing the credential provider (optional, using the default credential provider if not set)
quarkus.tls.key-store.credentials-provider.bean-name=my-credentials-provider

# The key used to retrieve the key store password, `password` by default
quarkus.tls.key-store.credentials-provider.password-key=password

# The key used to retrieve the alias password, `alias-password` by default
quarkus.tls.key-store.credentials-provider.alias-password-key=alias-password
The credential provider can only be used with PKCS12 and JKS key stores.

3.2. Trust stores

Trust stores are used to store the certificates of the trusted parties. They are generally used on the client-side, and on the server-side when mTLS is used.

3.2.1. PEM trust stores

PEM trust stores are composed of a list of .crt or .pem files. Each of them contains a certificate.

To configure a PEM trust store, use the following properties:

quarkus.tls.trust-store.pem.certs=ca.crt,ca2.pem

3.2.2. PKCS12 trust stores

PKCS12 trust stores are a single file containing the certificates. When multiple certificates are included, you can use the alias to select the appropriate certificate.

To configure a PKCS12 trust store, use the following properties:

quarkus.tls.trust-store.p12.path=client-truststore.p12
quarkus.tls.trust-store.p12.password=password
quarkus.tls.trust-store.p12.alias=my-alias

.p12 files are password-protected, so you need to provide the password to open the trust store. However, unlike for key stores, the alias does not require a password (because it’s the public certificate and not a private key).

3.2.3. JKS trust stores

JKS trust stores are a single file containing the certificates. When multiple certificates are included, you can use the alias to select the appropriate certificate. Note that the JKS format should be avoided as it is less secure than PKCS12.

To configure a JKS trust store, use the following properties:

quarkus.tls.trust-store.jks.path=client-truststore.jks
quarkus.tls.trust-store.jks.password=password
quarkus.tls.trust-store.jks.alias=my-alias

.jks files are password-protected, so you need to provide the password to open the trust store. However, unlike for key stores, the alias does not require a password (because it’s the public certificate and not a private key).

3.2.4. Credential providers

Instead of passing the trust store password in the configuration, you can use a credential provider.

A credential provider offers a way to retrieve passwords and other credentials. Note that the credential provider is only used if the password is not set in the configuration.

To configure a credential provider, use the following properties:

# The name of the credential bucket in the credentials provider
quarkus.tls.trust-store.credentials-provider.name=my-credentials

# The name of the bean providing the credential provider (optional, using the default credential provider if not set)
quarkus.tls.trust-store.credentials-provider.bean-name=my-credentials-provider

# The key used to retrieve the trust store password, `password` by default
quarkus.tls.trust-store.credentials-provider.password-key=password
The credential provider can only be used with PKCS12 and JKS trust stores.

3.3. Other properties

While key stores and trust stores are the most important properties, there are other properties you can use to configure TLS.

while the following examples use the default configuration, you can use the named configuration by prefixing the properties with the name of the configuration.

3.3.1. Cipher suites

The cipher suites are the list of ciphers that can be used during the TLS handshake. You can configure the ordered list of enabled cipher suites. If not configured, a reasonable default is selected from the built-in ciphers. However, when configured, it takes precedence over the default suite defined by the SSL engine in use.

To configure the cipher suites, use the following property:

quarkus.tls.cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384

3.3.2. TLS Protocol versions

The TLS protocol versions are the list of protocols that can be used during the TLS handshake. You can configure the ordered list of enabled TLS protocols. If not configured , it defaults to TLSv1.3, TLSv1.2.

Are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3.

To only enable TLSv1.3, configure the following property:

quarkus.tls.protocols=TLSv1.3

3.3.3. Handshake timeout

When a TLS connection is established, the handshake phase is the first step. During this phase, the client and server exchange information to establish the connection, typically the cipher suite, the TLS protocol version, the certification validation and so on.

To configure the timeout for the handshake phase, use the following property:

quarkus.tls.handshake-timeout=10S # Default.

3.3.4. ALPN

Application-Layer Protocol Negotiation (ALPN) is a TLS extension that allows the client and server during the TLS handshake to negotiate which protocol they will use for communication. ALPN enables more efficient communication by allowing the client to indicate its preferred application protocol to the server before the TLS connection is established.

This helps in scenarios such as HTTP/2 where multiple protocols may be available, allowing for faster protocol selection.

ALPN is enabled by default. To disable it, use the following property:

quarkus.tls.alpn=false

3.3.5. Certificate Revocation List (CRL)

A Certificate Revocation List (CRL) is a list of certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date. When a certificate is compromised, no longer needed, or deemed invalid for any reason, the CA adds it to the CRL to inform relying parties not to trust the certificate anymore.

You can configure the CRL with the list of certificate files you do not trust anymore. Two formats are allowed: DER and PKCS#7 (also known as P7B).

  • When using the DER format, you must pass DER-encoded CRLs.

  • When using the PKCS#7 format, you must pass PKCS#7 SignedData object, with the only significant field being crls.

To configure the CRL, use the following property:

quarkus.tls.certificate-revocation-list=ca.crl, ca2.crl

3.3.6. Trusting all certificates and hostname verification

These two properties should not be used in production.

You can configure your TLS connection to trust all certificates and to disable the hostname verification. These are two different steps:

  • trusting all certificates ignores the certificate validation, so all certificates are trusted. It is useful for testing with self-signed certificates, but should not be used in production.

  • hostname verification is the process of verifying the server’s identity. It is useful to prevent man-in-the-middle attacks. It often defaults to HTTPS or LDAPS.

To trust all certificates, use the following property:

quarkus.tls.trust-all=true

To disable the hostname verification, use the following property:

quarkus.tls.hostname-verification-algorithm=NONE

3.4. Configuration reference

The following table lists the supported properties:

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

Configuration property

Type

Default

quarkus.tls."tls-bucket-name".cipher-suites

Sets the ordered list of enabled cipher suites. If none is given, a reasonable default is selected from the built-in ciphers.

When suites are set, it takes precedence over the default suite defined by the SSLEngineOptions in use.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__CIPHER_SUITES

Show more

list of string

quarkus.tls."tls-bucket-name".protocols

Sets the ordered list of enabled TLS protocols.

If not set, it defaults to "TLSv1.3, TLSv1.2". The following list of protocols are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. To only enable TLSv1.3, set the value to to "TLSv1.3".

Note that setting an empty list, and enabling TLS is invalid. You must at least have one protocol.

Also, setting this replaces the default list of protocols.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__PROTOCOLS

Show more

list of string

TLSv1.3,TLSv1.2

quarkus.tls."tls-bucket-name".handshake-timeout

The timeout for the TLS handshake phase.

If not set, it defaults to 10 seconds.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__HANDSHAKE_TIMEOUT

Show more

Duration

10S

quarkus.tls."tls-bucket-name".alpn

Enables the Application-Layer Protocol Negotiation (ALPN).

Application-Layer Protocol Negotiation is a TLS extension that allows the client and server during the TLS handshake to negotiate which protocol they will use for communication. ALPN enables more efficient communication by allowing the client to indicate its preferred application protocol to the server before the TLS connection is established. This helps in scenarios such as HTTP/2 where multiple protocols may be available, allowing for faster protocol selection.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__ALPN

Show more

boolean

true

quarkus.tls."tls-bucket-name".certificate-revocation-list

Sets the list of revoked certificates (paths to files).

A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date. When a certificate is compromised, no longer needed, or deemed invalid for any reason, the CA adds it to the CRL to inform relying parties not to trust the certificate anymore.

Two formats are allowed: DER and PKCS#7 (also known as P7B). When using the DER format, you must pass DER-encoded CRLs. When using the PKCS#7 format, you must pass PKCS#7 SignedData object, with the only significant field being crls.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__CERTIFICATE_REVOCATION_LIST

Show more

list of path

quarkus.tls."tls-bucket-name".trust-all

If set to true, the server trusts all certificates.

This is useful for testing, but should not be used in production.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_ALL

Show more

boolean

false

quarkus.tls."tls-bucket-name".hostname-verification-algorithm

The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS (default), LDAPS or an NONE.

If set to NONE, it does not verify the hostname.

If not set, the configured extension decides the default algorithm to use. For example, for HTTP, it will be "HTTPS". For TCP, it can depend on the protocol. Nevertheless, it is recommended to set it to "HTTPS" or "LDAPS".

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__HOSTNAME_VERIFICATION_ALGORITHM

Show more

string

The default TLS bucket configuration This configuration section is optional

Type

Default

quarkus.tls.cipher-suites

Sets the ordered list of enabled cipher suites. If none is given, a reasonable default is selected from the built-in ciphers.

When suites are set, it takes precedence over the default suite defined by the SSLEngineOptions in use.

Environment variable: QUARKUS_TLS_CIPHER_SUITES

Show more

list of string

quarkus.tls.protocols

Sets the ordered list of enabled TLS protocols.

If not set, it defaults to "TLSv1.3, TLSv1.2". The following list of protocols are supported: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. To only enable TLSv1.3, set the value to to "TLSv1.3".

Note that setting an empty list, and enabling TLS is invalid. You must at least have one protocol.

Also, setting this replaces the default list of protocols.

Environment variable: QUARKUS_TLS_PROTOCOLS

Show more

list of string

TLSv1.3,TLSv1.2

quarkus.tls.handshake-timeout

The timeout for the TLS handshake phase.

If not set, it defaults to 10 seconds.

Environment variable: QUARKUS_TLS_HANDSHAKE_TIMEOUT

Show more

Duration

10S

quarkus.tls.alpn

Enables the Application-Layer Protocol Negotiation (ALPN).

Application-Layer Protocol Negotiation is a TLS extension that allows the client and server during the TLS handshake to negotiate which protocol they will use for communication. ALPN enables more efficient communication by allowing the client to indicate its preferred application protocol to the server before the TLS connection is established. This helps in scenarios such as HTTP/2 where multiple protocols may be available, allowing for faster protocol selection.

Environment variable: QUARKUS_TLS_ALPN

Show more

boolean

true

quarkus.tls.certificate-revocation-list

Sets the list of revoked certificates (paths to files).

A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date. When a certificate is compromised, no longer needed, or deemed invalid for any reason, the CA adds it to the CRL to inform relying parties not to trust the certificate anymore.

Two formats are allowed: DER and PKCS#7 (also known as P7B). When using the DER format, you must pass DER-encoded CRLs. When using the PKCS#7 format, you must pass PKCS#7 SignedData object, with the only significant field being crls.

Environment variable: QUARKUS_TLS_CERTIFICATE_REVOCATION_LIST

Show more

list of path

quarkus.tls.trust-all

If set to true, the server trusts all certificates.

This is useful for testing, but should not be used in production.

Environment variable: QUARKUS_TLS_TRUST_ALL

Show more

boolean

false

quarkus.tls.hostname-verification-algorithm

The hostname verification algorithm to use in case the server’s identity should be checked. Should be HTTPS (default), LDAPS or an NONE.

If set to NONE, it does not verify the hostname.

If not set, the configured extension decides the default algorithm to use. For example, for HTTP, it will be "HTTPS". For TCP, it can depend on the protocol. Nevertheless, it is recommended to set it to "HTTPS" or "LDAPS".

Environment variable: QUARKUS_TLS_HOSTNAME_VERIFICATION_ALGORITHM

Show more

string

The key store configuration This configuration section is optional

Type

Default

quarkus.tls.key-store.sni

Enables Server Name Indication (SNI).

Server Name Indication (SNI) is a TLS extension that allows a client to specify the hostname it is attempting to connect to during the TLS handshake. This enables a server to present different SSL certificates for multiple domains on a single IP address, facilitating secure communication for virtual hosting scenarios.

With this setting enabled, the client indicate the server name during the TLS handshake, allowing the server to select the right certificate.

When configuring the keystore with PEM files, multiple CRT/Key must be given. When configuring the keystore with a JKS or a P12 file, it selects one alias based on the SNI hostname. In this case, all the keystore password and alias password must be the same (configured with the password and alias-password properties. Do not set the alias property.

Environment variable: QUARKUS_TLS_KEY_STORE_SNI

Show more

boolean

false

quarkus.tls.key-store.credentials-provider.name

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration.

Environment variable: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

quarkus.tls.key-store.credentials-provider.bean-name

The name of the bean providing the credential provider.

The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

quarkus.tls.key-store.credentials-provider.password-key

The key used to retrieve the key store password.

If the selected credential provider does not support the key, the password is not retrieved. Otherwise, the retrieved value is used to open the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

quarkus.tls.key-store.credentials-provider.alias-password-key

The key used to retrieve the key store alias password.

If the selected credential provider does not contain the key, the alias password is not retrieved. Otherwise, the retrieved value is used to access the alias private key from the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_CREDENTIALS_PROVIDER_ALIAS_PASSWORD_KEY

Show more

string

alias-password

quarkus.tls."tls-bucket-name".key-store.sni

Enables Server Name Indication (SNI).

Server Name Indication (SNI) is a TLS extension that allows a client to specify the hostname it is attempting to connect to during the TLS handshake. This enables a server to present different SSL certificates for multiple domains on a single IP address, facilitating secure communication for virtual hosting scenarios.

With this setting enabled, the client indicate the server name during the TLS handshake, allowing the server to select the right certificate.

When configuring the keystore with PEM files, multiple CRT/Key must be given. When configuring the keystore with a JKS or a P12 file, it selects one alias based on the SNI hostname. In this case, all the keystore password and alias password must be the same (configured with the password and alias-password properties. Do not set the alias property.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_SNI

Show more

boolean

false

quarkus.tls."tls-bucket-name".key-store.credentials-provider.name

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

quarkus.tls."tls-bucket-name".key-store.credentials-provider.bean-name

The name of the bean providing the credential provider.

The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

quarkus.tls."tls-bucket-name".key-store.credentials-provider.password-key

The key used to retrieve the key store password.

If the selected credential provider does not support the key, the password is not retrieved. Otherwise, the retrieved value is used to open the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

quarkus.tls."tls-bucket-name".key-store.credentials-provider.alias-password-key

The key used to retrieve the key store alias password.

If the selected credential provider does not contain the key, the alias password is not retrieved. Otherwise, the retrieved value is used to access the alias private key from the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_CREDENTIALS_PROVIDER_ALIAS_PASSWORD_KEY

Show more

string

alias-password

Configures the PEM key/certificate pair This configuration section is optional

Type

Default

quarkus.tls.key-store.pem.order

The order of the key/cert files, based on the names in the keyCerts map.

By default, Quarkus sorts the key using a lexicographical order. This property allows you to specify the order of the key/cert files.

Environment variable: QUARKUS_TLS_KEY_STORE_PEM_ORDER

Show more

list of string

quarkus.tls.key-store.pem."key-certs".key

The path to the key file (in PEM format).

Environment variable: QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS__KEY

Show more

path

required

quarkus.tls.key-store.pem."key-certs".cert

The path to the certificate file (in PEM format).

Environment variable: QUARKUS_TLS_KEY_STORE_PEM__KEY_CERTS__CERT

Show more

path

required

quarkus.tls."tls-bucket-name".key-store.pem."key-certs".key

The path to the key file (in PEM format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS__KEY

Show more

path

required

quarkus.tls."tls-bucket-name".key-store.pem."key-certs".cert

The path to the certificate file (in PEM format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM__KEY_CERTS__CERT

Show more

path

required

quarkus.tls."tls-bucket-name".key-store.pem.order

The order of the key/cert files, based on the names in the keyCerts map.

By default, Quarkus sorts the key using a lexicographical order. This property allows you to specify the order of the key/cert files.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_PEM_ORDER

Show more

list of string

Configure the PKCS12 key store This configuration section is optional

Type

Default

quarkus.tls.key-store.p12.path

Path to the key store file (P12 / PFX format).

Environment variable: QUARKUS_TLS_KEY_STORE_P12_PATH

Show more

path

required

quarkus.tls.key-store.p12.password

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_PASSWORD

Show more

string

quarkus.tls.key-store.p12.alias

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_ALIAS

Show more

string

quarkus.tls.key-store.p12.alias-password

Password of the alias in the key store. If not set, the password will be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_ALIAS_PASSWORD

Show more

string

quarkus.tls.key-store.p12.provider

Provider of the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_P12_PROVIDER

Show more

string

quarkus.tls."tls-bucket-name".key-store.p12.path

Path to the key store file (P12 / PFX format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PATH

Show more

path

required

quarkus.tls."tls-bucket-name".key-store.p12.password

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PASSWORD

Show more

string

quarkus.tls."tls-bucket-name".key-store.p12.alias

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_ALIAS

Show more

string

quarkus.tls."tls-bucket-name".key-store.p12.alias-password

Password of the alias in the key store. If not set, the password will be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_ALIAS_PASSWORD

Show more

string

quarkus.tls."tls-bucket-name".key-store.p12.provider

Provider of the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_P12_PROVIDER

Show more

string

Configure the JKS key store This configuration section is optional

Type

Default

quarkus.tls.key-store.jks.path

Path to the keystore file (JKS format).

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_PATH

Show more

path

required

quarkus.tls.key-store.jks.password

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_PASSWORD

Show more

string

quarkus.tls.key-store.jks.alias

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_ALIAS

Show more

string

quarkus.tls.key-store.jks.alias-password

Password of the alias in the key store. When not set, the password may be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_ALIAS_PASSWORD

Show more

string

quarkus.tls.key-store.jks.provider

Provider of the key store.

Environment variable: QUARKUS_TLS_KEY_STORE_JKS_PROVIDER

Show more

string

quarkus.tls."tls-bucket-name".key-store.jks.path

Path to the keystore file (JKS format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PATH

Show more

path

required

quarkus.tls."tls-bucket-name".key-store.jks.password

Password of the key store. When not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PASSWORD

Show more

string

quarkus.tls."tls-bucket-name".key-store.jks.alias

Alias of the private key and certificate in the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_ALIAS

Show more

string

quarkus.tls."tls-bucket-name".key-store.jks.alias-password

Password of the alias in the key store. When not set, the password may be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_ALIAS_PASSWORD

Show more

string

quarkus.tls."tls-bucket-name".key-store.jks.provider

Provider of the key store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__KEY_STORE_JKS_PROVIDER

Show more

string

The trust store configuration This configuration section is optional

Type

Default

quarkus.tls.trust-store.credentials-provider.name

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration.

Environment variable: QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

quarkus.tls.trust-store.credentials-provider.bean-name

The name of the bean providing the credential provider.

The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

quarkus.tls.trust-store.credentials-provider.password-key

The key used to retrieve the trust store password.

If the selected credential provider does not contain the configured key, the password is not retrieved. Otherwise, the retrieved value is used to open the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

quarkus.tls."tls-bucket-name".trust-store.credentials-provider.name

The name of the "credential" bucket (map key → passwords) to retrieve from the io.quarkus.credentials.CredentialsProvider. If not set, the credential provider will not be used.

A credential provider offers a way to retrieve the key store password as well as alias password. Note that the credential provider is only used if the passwords are not set in the configuration.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_NAME

Show more

string

quarkus.tls."tls-bucket-name".trust-store.credentials-provider.bean-name

The name of the bean providing the credential provider.

The name is used to select the credential provider to use. The credential provider must be exposed as a CDI bean and with the @Named annotation set to the configured name to be selected.

If not set, the default credential provider is used.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_BEAN_NAME

Show more

string

quarkus.tls."tls-bucket-name".trust-store.credentials-provider.password-key

The key used to retrieve the trust store password.

If the selected credential provider does not contain the configured key, the password is not retrieved. Otherwise, the retrieved value is used to open the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_CREDENTIALS_PROVIDER_PASSWORD_KEY

Show more

string

password

Configures the list of trusted certificates This configuration section is optional

Type

Default

quarkus.tls.trust-store.pem.certs

List of the trusted cert paths (Pem format).

Environment variable: QUARKUS_TLS_TRUST_STORE_PEM_CERTS

Show more

list of path

quarkus.tls."tls-bucket-name".trust-store.pem.certs

List of the trusted cert paths (Pem format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_PEM_CERTS

Show more

list of path

Configure the PKCS12 trust store This configuration section is optional

Type

Default

quarkus.tls.trust-store.p12.path

Path to the trust store file (P12 / PFX format).

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_PATH

Show more

path

required

quarkus.tls.trust-store.p12.password

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_PASSWORD

Show more

string

quarkus.tls.trust-store.p12.alias

Alias of the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_ALIAS

Show more

string

quarkus.tls.trust-store.p12.provider

Provider of the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_P12_PROVIDER

Show more

string

quarkus.tls."tls-bucket-name".trust-store.p12.path

Path to the trust store file (P12 / PFX format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PATH

Show more

path

required

quarkus.tls."tls-bucket-name".trust-store.p12.password

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PASSWORD

Show more

string

quarkus.tls."tls-bucket-name".trust-store.p12.alias

Alias of the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_ALIAS

Show more

string

quarkus.tls."tls-bucket-name".trust-store.p12.provider

Provider of the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_P12_PROVIDER

Show more

string

Configure the JKS trust store This configuration section is optional

Type

Default

quarkus.tls.trust-store.jks.path

Path to the trust store file (JKS format).

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_PATH

Show more

path

required

quarkus.tls.trust-store.jks.password

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_PASSWORD

Show more

string

quarkus.tls.trust-store.jks.alias

Alias of the key in the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_ALIAS

Show more

string

quarkus.tls.trust-store.jks.provider

Provider of the trust store.

Environment variable: QUARKUS_TLS_TRUST_STORE_JKS_PROVIDER

Show more

string

quarkus.tls."tls-bucket-name".trust-store.jks.path

Path to the trust store file (JKS format).

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PATH

Show more

path

required

quarkus.tls."tls-bucket-name".trust-store.jks.password

Password of the trust store. If not set, the password must be retrieved from the credential provider.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PASSWORD

Show more

string

quarkus.tls."tls-bucket-name".trust-store.jks.alias

Alias of the key in the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_ALIAS

Show more

string

quarkus.tls."tls-bucket-name".trust-store.jks.provider

Provider of the trust store.

Environment variable: QUARKUS_TLS__TLS_BUCKET_NAME__TRUST_STORE_JKS_PROVIDER

Show more

string
About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

4. The registry API

While extensions will automatically use the TLS registry, you can also use the registry API to access the TLS configuration programmatically.

To access the TLS configuration, inject the TlsConfigurationRegistry bean and gets the TLS configuration by name (or the default one):

 @Inject
 TlsConfigurationRegistry certificates;
// ...
TlsConfiguration def = certificates.getDefault().orElseThrow();
TlsConfiguration named = certificates.get("name").orElseThrow();
//...

The TlsConfiguration object contains the key stores, trust stores, cipher suites, protocols, and other properties. It also provides a way to create an SSLContext from the configuration.

As Vert.x is omnipresent in Quarkus, you can also use the TlsConfiguration object to configure the Vert.x client or server such as KeyCertOptions, TrustOptions, and so on.

5. Registering a certificate from an extension

This section is only for extension developers. An extension can register a certificate in the TLS registry. This is useful when an extension needs to provide a certificate to the application or provides a different format.

To achieve this, the extension processor must produce a TlsCertificateBuildItem. A TlsCertificateBuildItem is composed of a name and a CertificateSupplier.

TlsCertificateBuildItem item = new TlsCertificateBuildItem("named",
    new MyCertificateSupplier());

The certificate supplier is a runtime object that is generally retrieved using a recorder method. Here is an example of a certificate supplier:

public class MyCertificateSupplier implements Supplier<TlsConfiguration> {

        @Override
        public TlsConfiguration get() {
            try {
                KeyStore ks = KeyStore.getInstance("PKCS12");
                ks.load(getClass().getResourceAsStream("target/certs/test-registration-keystore.p12"),
                        "password".toCharArray());
                KeyStore ts = KeyStore.getInstance("PKCS12");
                ts.load(getClass().getResourceAsStream("target/certs/test-registration-truststore.p12"),
                        "password".toCharArray());
                return new BaseTlsConfiguration() {
                    @Override
                    public KeyStore getKeyStore() {
                        return ks;
                    }

                    @Override
                    public KeyStore getTrustStore() {
                        return ts;
                    }
                };
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }
    }

6. Startup checks

When the application starts, the TLS registry performs some checks to ensure the configuration is correct:

  • the key stores and trust stores are accessible

  • the aliases are available and accessible in the key stores and trust stores

  • the certificates are valid

  • the cipher suites and protocols are valid

  • the CRLs are valid

If any of these checks fail, the application will fail to start.

Related content

On the same topics

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license.

This website was built with Jekyll, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Follow Us
Get Help
Languages
Quarkus is made of community projects
CC by 3.0 | Privacy Policy Sponsored by