Skip to content

Commit

Permalink
Add documentation for the centralized TSL configuration
Browse files Browse the repository at this point in the history 
It covers the TLS registry, HTTP configuration and gRPC.
  • Loading branch information
@cescoffier
cescoffier committed Jun 3, 2024
1 parent f1e99f7 commit bd2d5ef
Show file tree
Hide file tree
Showing 4 changed files with 624 additions and 7 deletions.
67 changes: 66 additions & 1 deletion docs/src/main/asciidoc/grpc-reference.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Check warning on line 114 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 114, "column": 43}}}, "severity": "INFO"}

[source,properties,subs=attributes+]
----
quarkus.grpc.server.use-separate-server=false
Expand Down Expand Up @@ -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.

Check warning on line 158 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 158, "column": 49}}}, "severity": "INFO"}

=== 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:

Check warning on line 162 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 162, "column": 5}}}, "severity": "INFO"}

[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:

Check warning on line 175 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 175, "column": 5}}}, "severity": "INFO"}

[source,properties,subs=attributes+]
----
Expand Down Expand Up @@ -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:

Check warning on line 222 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 222, "column": 5}}}, "severity": "INFO"}

[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

Check warning on line 242 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 242, "column": 15}}}, "severity": "INFO"}

Check warning on line 242 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 242, "column": 19}}}, "severity": "INFO"}
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false
----

=== Direct configuration

Check warning on line 247 in docs/src/main/asciidoc/grpc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/grpc-reference.adoc", "range": {"start": {"line": 247, "column": 15}}}, "severity": "INFO"}

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+]
Expand Down
41 changes: 36 additions & 5 deletions docs/src/main/asciidoc/http-reference.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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].

Check warning on line 129 in docs/src/main/asciidoc/http-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'SSL/TLS' rather than 'SSL'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'SSL/TLS' rather than 'SSL'.", "location": {"path": "docs/src/main/asciidoc/http-reference.adoc", "range": {"start": {"line": 129, "column": 15}}}, "severity": "INFO"}
====

=== 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:

Check warning on line 146 in docs/src/main/asciidoc/http-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'keystore' rather than 'key store'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'keystore' rather than 'key store'.", "location": {"path": "docs/src/main/asciidoc/http-reference.adoc", "range": {"start": {"line": 146, "column": 25}}}, "severity": "INFO"}

[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.
Expand All @@ -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.

Expand All @@ -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:

Expand Down
Loading

0 comments on commit bd2d5ef

Please sign in to comment.