Merge pull request #39825 from cescoffier/tls-registry

Implementation of the internal TLS registry

bom/application/pom.xml

@@ -667,6 +667,17 @@
                 <version>${project.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-tls-registry</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-tls-registry-deployment</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+
             <!-- Quarkus extensions -->
 
             <dependency>

devtools/bom-descriptor-json/pom.xml

@@ -2865,6 +2865,19 @@
                         </exclusion>
                     </exclusions>
                 </dependency>
+                <dependency>
+                    <groupId>io.quarkus</groupId>
+                    <artifactId>quarkus-tls-registry</artifactId>
+                    <version>${project.version}</version>
+                    <type>pom</type>
+                    <scope>test</scope>
+                    <exclusions>
+                        <exclusion>
+                            <groupId>*</groupId>
+                            <artifactId>*</artifactId>
+                        </exclusion>
+                    </exclusions>
+                </dependency>
                 <dependency>
                     <groupId>io.quarkus</groupId>
                     <artifactId>quarkus-undertow</artifactId>

docs/pom.xml

@@ -2881,6 +2881,19 @@
                 </exclusion>
             </exclusions>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-tls-registry-deployment</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-undertow-deployment</artifactId>

docs/src/main/asciidoc/grpc-reference.adoc

@@ -97,6 +97,22 @@ However, it changes the way the client communicates with the server.
 
 If you use the Vert.x based server, you can configure TLS by setting the following properties in your `application.properties` file:
 
+[source,properties,subs=attributes+]
+----
+quarkus.grpc.server.use-separate-server=false
+quarkus.grpc.server.plain-text=false
+
+quarkus.tls.key-store.p12.path=grpc-tls-keystore.p12
+quarkus.tls.key-store.p12.password=*****
+
+quarkus.http.insecure-requests=disabled
+----
+
+The previous configuration uses the xref:./tls-registry-reference.adoc[centralized TLS configuration].
+This is the recommended approach.
+
+You can also configure the server directly using the following properties:
+
 [source,properties,subs=attributes+]
 ----
 quarkus.grpc.server.use-separate-server=false
@@ -139,7 +155,24 @@ This server only supports `PEM` format for the certificate and the key.
 
 == Configuring TLS for gRPC clients
 
-When using the Vert.x based client, you can configure TLS by setting the following properties in your `application.properties` file:
+As for the server, you can configure the clients using the centralized TLS configuration or directly.
+
+=== With the centralized TLS configuration
+
+When using the Quarkus (Vert.x-based) client, you can configure TLS by setting the following properties in your `application.properties` file:
+
+[source,properties,subs=attributes+]
+----
+quarkus.tls.trust-store.p12.path=grpc-client-truststore.p12
+quarkus.tls.trust-store.p12.password=password
+
+quarkus.grpc.clients.hello.plain-text=false
+quarkus.grpc.clients.hello.use-quarkus-grpc-client=true
+----
+
+=== Direct configuration
+
+When using the Quarkus (Vert.x-based) client, you can configure TLS by setting the following properties in your `application.properties` file:
 
 [source,properties,subs=attributes+]
 ----
@@ -182,6 +215,38 @@ gRPC Java client only support the `PEM` format for the trust-store.
 
 == Configuring mTLS
 
+You can configure mutual TLS (mTLS) for gRPC services and clients.
+
+=== Using the centralized TLS configuration
+
+When using the Quarkus HTTP server (`quarkus.grpc.server.use-separate-server=false`) and Quarkus gRPC client (`quarkus.grpc.clients.hello.use-quarkus-grpc-client=true`), you can configure mTLS by setting the following properties in your `application.properties` file:
+
+[source,properties,subs=attributes+]
+----
+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
+----
+
+=== Direct configuration
+
+When using the gRPC Java server, you can configure mTLS by setting the following properties in your `application.properties` file:
 When using the Vert.x based server and Vert.x-based client, you can configure mTLS by setting the following properties in your `application.properties` file:
 
 [source,properties,subs=attributes+]

docs/src/main/asciidoc/http-reference.adoc

@@ -129,7 +129,42 @@ In both cases, a password must be provided. See the designated paragraph for a d
 To enable TLS/SSL support with native executables, please refer to our xref:native-and-ssl.adoc[Using SSL With Native Executables guide].
 ====
 
-=== Providing a certificate and key file
+=== Using the TLS centralized configuration
+
+Quarkus provides a xref:./tls-registry-reference.adoc[TLS centralized configuration] that can be used to configure the server's TLS context.
+It is the recommended approach to configure HTTPS.
+
+To configure the HTTP server to use HTTPS, you can use the following configuration:
+
+[source,properties]
+----
+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:
+
+[source,properties]
+----
+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:
+
+[source,properties]
+----
+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
+----
+
+=== Configuring the HTTP server directly
+
+If you do not want to use the TLS registry, you can configure the HTTP server directly.
 
 If the certificate has not been loaded into a keystore, it can be provided directly using the properties listed below.
 Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback.
@@ -143,8 +178,6 @@ quarkus.http.ssl.certificate.files=/path/to/certificate
 quarkus.http.ssl.certificate.key-files=/path/to/key
 ----
 
-=== Providing a keystore
-
 An alternate solution is to directly provide a keystore which already contains a default entry with a certificate.
  You will need to at least provide the file and a password.
 
@@ -165,8 +198,6 @@ If the type is not provided, Quarkus will try to deduce it from the file extensi
 quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]
 ----
 
-=== Setting the password
-
 In both aforementioned scenarios, a password needs to be provided to create/load the keystore with.
 The password can be set in your `application.properties` (in plain-text) using the following property: