8

Is there any example/tutorial to build and configure TLS-secured restful service using quarkus.io?

Unfortunately I can not find one neither at quarkus documentation, no here.

Guillaume Smet
  • 9,921
  • 22
  • 29
S. Kadakov
  • 861
  • 1
  • 6
  • 15

3 Answers3

15

Thanks mr. Guillaume Smet, I found the solution. Here is "from zero to hello in 5 minutes with Quarkus and SSL guide". This is done by quarkus undertow plugin. Also you will need text editor, jdk 1.8+ and maven installed.

Frist, create the project.

mkdir restls
cd restls
mvn io.quarkus:quarkus-maven-plugin:create -DprojectGroupId=org.acme -DprojectArtifactId=restls -DclassName="org.acme.HelloResource" -Dpath="/hello" -Dextensions="undertow"

Open your application config file src/main/resources/application.properties with any editor and add lines:

quarkus.http.port=80
quarkus.http.ssl-port=443
quarkus.http.ssl.certificate.key-store-file=keystore.jks

Create keystore containing self-signed certificate (answer all questions and specify password namelly "password"):

keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks -storepass password -validity 365 -keysize 2048

The file keystore.jks must be in the src/main/resources/ folder.

Build the project:

mvnw clean package quarkus:build

Now try it out:

java -jar target/restls-1.0-SNAPSHOT-runner.jar

Navigate to https://localhost/hello and allow your browser to trust certificate. That's all.

You can override options in invocation time like this:

java -Dquarkus.http.ssl.certificate.key-store-file=/path-to-keystore/keystore-name.jks -jar target/restls-1.0-SNAPSHOT-runner.jar

Finally, here is the concerning options list:

quarkus.http.ssl.certificate.file -- The file path to a server certificate or certificate chain in PEM format.

quarkus.http.ssl.certificate.key-file -- The file path to the corresponding certificate private key file in PEM format.

quarkus.http.ssl.certificate.key-store-file -- An optional key store which holds the certificate information instead of specifying separate files.

quarkus.http.ssl.certificate.key-store-file-type -- An optional parameter to specify type of the key store file. If not given, the type is automatically detected based on the file name.

You can specifiy either certificate + key files in PEM format or keystore.

Leandro
  • 376
  • 5
  • 16
S. Kadakov
  • 861
  • 1
  • 6
  • 15
  • Thanks for this. With Quarkus 0.18.0, I had to specify the cert + key files. For some reason, the cert was not being served when keystore was used causing handshake failures. – Ali Cheaito Jun 28 '19 at 17:57
11

It is indeed supported by our Undertow extension but, unfortunately, not documented.

You can define things like the following:

quarkus.http.ssl.certificate.file=...
quarkus.http.ssl.certificate.key-file=...
...

in your application.properties.

The config entry point is ServerSslConfig (see https://github.com/quarkusio/quarkus/blob/master/core/runtime/src/main/java/io/quarkus/runtime/configuration/ssl/ServerSslConfig.java#L41). You then add the nested properties with dots and transform camel-case to dashes.

If you want to build a native executable, there's a good chance you will have to add quarkus.ssl.native=true too.

If you have feedback or if you want to contribute a guide for that, feel free to join us on Zulip or open issues/PRs on GitHub.

Guillaume Smet
  • 9,921
  • 22
  • 29
  • I just opened https://github.com/quarkusio/quarkus/issues/1947 to track further progress on this. – Guillaume Smet Apr 09 '19 at 11:41
  • Fine! Thanks for you reply, I will try that. – S. Kadakov Apr 10 '19 at 06:33
  • Yes, it works, thank you. But you have hardcoded password for keystore at ServerSslConfig.java:158. – S. Kadakov Apr 11 '19 at 08:17
  • Would you be interested to share your findings here: https://quarkus.io/guides/rest-json-guide . A paragraph about how to set up an SSL service would be nice. As for the hardcoded password, I noticed that. Please open a GitHub issue. – Guillaume Smet Apr 11 '19 at 14:27
  • Issue is opened: https://github.com/quarkusio/quarkus/issues/2021 Please tell me how to share my findings? – S. Kadakov Apr 12 '19 at 06:19
  • I think I would add a specific paragraph here just before the conclusion: https://github.com/quarkusio/quarkus/blob/master/docs/src/main/asciidoc/rest-json-guide.adoc . For now it's probably the best place. It's asciidoc, you have plenty of example of how to format it in the file. Feel free to open a PR and ask for advice once you have a draft, I'm here to help! – Guillaume Smet Apr 12 '19 at 07:49
  • I just posted short guide here as an answer. Please feel free to copy it anywhere you need. – S. Kadakov Apr 12 '19 at 08:27
0

adding some notes here for how you would use native quarkus tls (reverse_proxy for example) as things constantly evolve

  1. for extensions defined here tls enabled extensions
  2. generate a CA with SAN for the hostname
  3. using your CA create a openssl x509 and key PEM format
  4. in application.properties define eg hostname = quarkus-dev quarkus.http.ssl.certificate.file=quarkus-dev.pem
    quarkus.http.ssl.certificate.key-file=quarkus-dev-key.pem
    quarkus.ssl.native=true
  5. with this set up the quarkus binary will look for the x509 cert and key in the same directory
    enter image description here

Notes
some open ssl fragments for generation of the certs

CA key
openssl genrsa -out quarkus-dev-key.pem 2048

CA extension shows SAN dns entry

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = quarkus-dev

generate the CA

openssl req -nodes -newkey rsa:2048 -keyout quarkus-dev-key.pem -out quarkus-dev.csr -subj "/C=CA/ST=QUARKUS/L=QUARKUS/O=QUARKUS/OU=QUARKUS/CN=quarkus-dev" -addext "subjectAltName = DNS:quarkus-dev" 

openssl x509 -req -in quarkus-dev.csr -CA quarkus-dev-ca.crt -CAkey quarkus-dev-ca.key -CAcreateserial -out quarkus-dev.pem -outform PEM -days 825 -sha256 -passin file:quarkus-dev-ca.pass -extfile quarkus-dev.ext

with the CA above you can generate the certificates
if using the SAN dns then you would need to update /etc/hosts or alternatively you could use the IP in the SAN like

[alt_names]
IP.1 = 192.168.0.1
Nigel Savage
  • 991
  • 13
  • 26