Add TLS Command Implementation

This commit introduces two new CLI commands to enhance TLS management: - Generate and install a Quarkus Development CA. - Create certificates, either signed with the generated CA or unsigned.
quarkusio · Jul 1, 2024 · 02e470d · 02e470d
1 parent 1623bc9
commit 02e470d
Show file tree

Hide file tree

Showing 10 changed files with 627 additions and 1 deletion.
diff --git a/build-parent/pom.xml b/build-parent/pom.xml
@@ -369,9 +369,14 @@
             <dependency>
                 <groupId>me.escoffier.certs</groupId>
                 <artifactId>certificate-generator-junit5</artifactId>
-                <version>0.5.0</version>
+                <version>0.7.1</version>
                 <scope>test</scope>
             </dependency>
+            <dependency>
+                <groupId>me.escoffier.certs</groupId>
+                <artifactId>certificate-generator</artifactId>
+                <version>0.7.1</version>
+            </dependency>
 
         </dependencies>
     </dependencyManagement>

diff --git a/docs/src/main/asciidoc/tls-registry-reference.adoc b/docs/src/main/asciidoc/tls-registry-reference.adoc
@@ -693,3 +693,193 @@ To handle the renewal, you can use the periodic reloading mechanism:
 %prod.quarkus.http.insecure-requests=disabled
 ----
 
+== Quarkus CLI commands and development CA (Certificate Authority)
+
+The TLS registry provides CLI commands to generate a development CA and trusted certificates.
+This avoids having to use self-signed certificates locally.
+
+[source, shell]
+----
+> quarkus tls-registry
+Install and Manage TLS development certificates
+Usage: tls-registry [COMMAND]
+Commands:
+  generate-quarkus-ca   Generate Quarkus Dev CA certificate and private key.
+  generate-certificate  Generate a TLS certificate with the Quarkus Dev CA if
+                          available.
+----
+
+In most case, you generate the Quarkus Development CA once, and then generate certificates signed by this CA.
+The Quarkus Development CA is a Certificate Authority that can be used to sign certificates locally.
+It is only valid for development purposes and only trusted on the local machine.
+The generated CA is located in `$HOME/.quarkus/quarkus-dev-root-ca.pem`, and installed in the system trust store.
+
+=== CA, signed vs. self-signed certificates
+
+When developing with TLS, you can use two types of certificates:
+
+- a self-signed certificate: the certificate is signed by the same entity that uses it. It is not trusted by default. It's generally what we uses when we don't have a CA, or don't want to dig too much into TLS. This is not a production setup, just for development.
+- a signed certificate: the certificate is signed by a Certificate Authority (CA). The CA is a trusted entity that signs the certificate. The certificate is trusted by default. This is what we use in production.
+
+We could use self-signed certificate when running application locally, but it's not always convenient.
+Typically, browsers will not trust the certificate, and you will have to import it manually.
+`curl`, `wget`, `httpie` and other tools will also not trust the certificate.
+
+To avoid this, we can use a development CA to sign the certificates, and install it into the system trust store.
+Thus, every certificate signed by this CA will be trusted by the system.
+
+Quarkus makes it easy to generate a development CA and certificates signed by this CA.
+
+=== Generate a development CA
+
+The development CA is a Certificate Authority that can be used to sign certificates locally.
+Note that the generated CA is only valid for development purposes, and only trusted on the local machine.
+
+To generate a development CA, use the following command:
+
+[source, shell]
+----
+quarkus tls-registry generate-ca-certificate --install --renew --trusstore
+----
+
+`--install` installs the CA in the system trust store.
+Windows, Mac and Linux (Fedora and Ubuntu) are supported.
+However, depending on your browser, you may need to import the generated CA manually.
+Refer to the browser documentation for more information.
+The generated CA is located in `$HOME/.quarkus/quarkus-dev-root-ca.pem`.
+
+WARNING: When installing the certificate, your system may ask for your password to install the certificate in the system trust store, or ask for confirmation in a dialog (on Windows).
+
+IMPORTANT: On Windows, makes sure you run from an elevated terminal (run as administrator) to install the CA in the system trust store.
+
+`--renew` renews the CA if it already exists.
+When this option is used, you need to re-generate the certificates that were signed by the CA, as the private key is changed.
+Note that if the CA expires, it will automatically be renewed (without passing `--renew`).
+
+`--truststore` also generates a PKCS12 trust store containing the CA certificate.
+
+=== Generate a trusted (signed) certificate
+
+Once you have installed the Quarkus Development CA, you can generate a trusted certificate.
+It will be signed by the Quarkus Development CA, and so trusted by your system.
+
+[source, shell]
+----
+quarkus tls-registry generate-certificate --name my-cert
+----
+
+This generates a certificate signed by the Quarkus Development CA, and so if properly installed / imported, will be trusted by your system.
+
+The certificate is stored in `./.certs/`.
+Two files are generated:
+
+- `$NAME-keystore.p12` - contains the private key and the certificate. It's password protected.
+- `$NAME-truststore.p12` - contains the CA certificate, that you can used as trust store (for test, for instance).
+
+More options are available:
+
+[source, shell]
+----
+Usage: tls-registry generate-certificate [-hrV] [-c=<cn>] [-d=<directory>]
+       -n=<name> [-p=<password>]
+Generate a TLS certificate with the Quarkus Dev CA if available.
+  -c, --cn=<cn>       The common name of the certificate. Default is 'localhost'
+  -d, --directory=<directory>
+                      The directory in which the certificates will be created.
+                        Default is `.certs`
+  -n, --name=<name>   Name of the certificate. It will be used as file name and
+                        alias in the keystore
+  -p, --password=<password>
+                      The password of the keystore. Default is 'password'
+  -r, --renew         Whether existing certificates will need to be replaced
+----
+
+When generating the certificate, a `.env` file is also generated making the Quarkus Dev mode aware of these certificates.
+So, then, if you run your application in dev mode, it will use these certificates:
+
+[source, shell]
+----
+mvn quarkus:dev
+...
+INFO  [io.quarkus] (Quarkus Main Thread) demo 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.286s. Listening on: http://localhost:8080 and https://localhost:8443
+----
+
+Now, you can open the dev ui using HTTPS: `https://localhost:8443/q/dev`, or issue a request using `curl`:
+
+[source, shell]
+----
+curl https://localhost:8443/hello
+Hello from Quarkus REST%
+----
+
+IMPORTANT: If the Quarkus Development CA is not installed, a self-signed certificate is generated.
+
+
+=== Generating a self-signed certificate
+
+Even if the Quarkus Development CA is installed, you can generate a self-signed certificate:
+
+[source, shell]
+----
+quarkus tls-registry generate-certificate --name my-cert --self-signed
+----
+
+This generates a self-signed certificate, not signed by the Quarkus Development CA.
+
+=== Uninstalling the Quarkus Development CA
+
+Uninstalling the Quarkus Development CA from your system depends on your OS.
+
+==== Deleting the CA certificate on Windows
+
+To delete the CA certificate on Windows, use the following commands from a Powershell terminal with administrator rights:
+
+[source, shell]
+----
+# First, we need to identify the serial number of the CA certificate
+> certutil -store -user Root
+root "Trusted Root Certification Authorities"
+================ Certificate 0 ================
+Serial Number: 019036d564c8
+Issuer: O=Quarkus, CN=quarkus-dev-root-ca # <-That's the CA, copy the Serial Number (the line above)
+NotBefore: 6/19/2024 11:07 AM
+NotAfter: 6/20/2025 11:07 AM
+Subject: C=Cloud, S=world, L=home, OU=Quarkus Dev, O=Quarkus Dev, CN=quarkus-dev-root-ca
+Signature matches Public Key
+Non-root Certificate uses same Public Key as Issuer
+Cert Hash(sha1): 3679bc95b613a2112a3d3256fe8321b6eccce720
+No key provider information
+Cannot find the certificate and private key for decryption.
+CertUtil: -store command completed successfully.
+
+> certutil -delstore -user -v Root $Serial_Number
+----
+
+Replace `$Serial_Number` with the serial number of the CA certificate.
+
+==== Deleting the CA certificate on Linux
+
+On Fedora, you can use the following command:
+
+[source, shell]
+----
+sudo rm /etc/pki/ca-trust/source/anchors/quarkus-dev-root-ca.pem
+sudo update-ca-trust
+----
+
+On Ubuntu, you can use the following command:
+
+[source, shell]
+----
+sudo rm /usr/local/share/ca-certificates/quarkus-dev-root-ca.pem
+sudo update-ca-certificates
+----
+
+==== Deleting the CA certificate on Mac
+
+On Mac, you can use the following command:
+
+[source, shell]
+----
+sudo security -v remove-trusted-cert -d /Users/clement/.quarkus/quarkus-dev-root-ca.pem
+----
diff --git a/extensions/tls-registry/cli/pom.xml b/extensions/tls-registry/cli/pom.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.quarkus</groupId>
+        <artifactId>quarkus-tls-registry-parent</artifactId>
+        <version>999-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>quarkus-tls-registry-cli</artifactId>
+    <name>Quarkus - TLS Registry - CLI</name>
+
+    <properties>
+    <main.class>io.quarkus.tls.cli.TlsCommand</main.class>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>info.picocli</groupId>
+            <artifactId>picocli</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>me.escoffier.certs</groupId>
+            <artifactId>certificate-generator</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <compilerArgs>
+                        <arg>-parameters</arg>
+                    </compilerArgs>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <systemPropertyVariables>
+                        <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
+                        <maven.home>${maven.home}</maven.home>
+                    </systemPropertyVariables>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-assembly-plugin</artifactId>
+
+                <configuration>
+                    <descriptorRefs>
+                        <descriptorRef>jar-with-dependencies</descriptorRef>
+                    </descriptorRefs>
+                    <finalName>${project.artifactId}-${project.version}</finalName>
+                    <appendAssemblyId>false</appendAssemblyId>
+                    <archive>
+                        <manifest>
+                            <addClasspath>true</addClasspath>
+                            <mainClass>${main.class}</mainClass>
+                        </manifest>
+                    </archive>
+                </configuration>
+
+                <executions>
+                    <execution>
+                        <id>make-assembly</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>single</goal>
+                        </goals>
+                    </execution>
+                </executions>
+
+            </plugin>
+        </plugins>
+    </build>
+</project>
diff --git a/extensions/tls-registry/cli/src/main/java/io/quarkus/tls/cli/Constants.java b/extensions/tls-registry/cli/src/main/java/io/quarkus/tls/cli/Constants.java
@@ -0,0 +1,16 @@
+package io.quarkus.tls.cli;
+
+import java.io.File;
+
+public interface Constants {
+
+    String CA_FILE_NAME = "quarkus-dev-root-ca.pem";
+    String PK_FILE_NAME = "quarkus-dev-root-key.pem";
+    String KEYSTORE_FILE_NAME = "quarkus-dev-keystore.p12";
+
+    File BASE_DIR = new File(System.getenv("HOME"), ".quarkus");
+
+    File CA_FILE = new File(BASE_DIR, CA_FILE_NAME);
+    File PK_FILE = new File(BASE_DIR, PK_FILE_NAME);
+    File KEYSTORE_FILE = new File(BASE_DIR, KEYSTORE_FILE_NAME);
+}