Merge pull request #42572 from rolfedh/update-default-store-mechanisms

Add keystore and truststore default format change

docs/src/main/asciidoc/security-authentication-mechanisms.adoc

@@ -227,29 +227,45 @@ Quarkus provides mutual TLS (mTLS) authentication so that you can authenticate u
 To use this authentication method, you must first enable SSL/TLS for your application.
 For more information, see the xref:http-reference.adoc#ssl[Supporting secure connections with SSL/TLS] section of the Quarkus "HTTP reference" guide.
 
-After your application accepts secure connections, the next step is to configure the `quarkus.http.ssl.certificate.trust-store-file` property with the name of that file that holds all the certificates your application trusts. The specified file also includes information about how your application asks for certificates when a client, such as a browser or other service, tries to access one of its protected resources.
+After your application accepts secure connections, the next step is to configure the `quarkus.http.ssl.certificate.trust-store-file` property with the name of the file that holds all the certificates your application trusts. This file also includes information about how your application requests certificates when a client, such as a browser or another service, tries to access one of its protected resources.
+
+Because JKS is no longer the default keystore and truststore format in Quarkus, the framework makes an educated guess based on the file extension:
+
+* `.pem`, `.crt`, and `.key` are read as PEM certificates and keys.
+* `.jks`, `.keystore`, and `.truststore` are read as JKS keystores and truststores.
+* `.p12`, `.pkcs12`, and `.pfx` are read as PKCS12 keystores and truststores.
+
+If your file does not use one of these extensions, you must set the format by using the following properties:
 
 [source,properties]
 ----
-quarkus.http.ssl.certificate.key-store-file=server-keystore.jks            <1>
+quarkus.http.ssl.certificate.key-store-file-type=JKS  # or P12 or PEM
+quarkus.http.ssl.certificate.trust-store-file-type=JKS  # or P12 or PEM
+----
+
+JKS is becoming less commonly used. Since Java 9, the default keystore format in Java is PKCS12. The most significant difference between JKS and PKCS12 is that JKS is a format specific to Java. In contrast, PKCS12 is a standardized, language-neutral way of storing encrypted private keys and certificates.
+
+Here is an example configuration for enabling mTLS:
+
+[source,properties]
+----
+quarkus.http.ssl.certificate.key-store-file=server-keystore.jks <1>
 quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
-quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks        <2>
+quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks <2>
 quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
-quarkus.http.ssl.client-auth=required                                      <3>
-quarkus.http.auth.permission.default.paths=/*                              <4>
+quarkus.http.ssl.client-auth=required <3>
+quarkus.http.auth.permission.default.paths=/* <4>
 quarkus.http.auth.permission.default.policy=authenticated
-quarkus.http.insecure-requests=disabled                                    <5>
+quarkus.http.insecure-requests=disabled <5>
 ----
+
 <1> The keystore where the server's private key is located.
 <2> The truststore from which the trusted certificates are loaded.
-<3> With the value set to `required`, the server demands client certificates.
-Set the value to `REQUEST` to allow the server to accept requests without a certificate.
-This setting is beneficial when supporting authentication methods besides mTLS.
-<4> Defines a policy where only authenticated users should have access to resources from your application.
-<5> You can explicitly disable the plain HTTP protocol, thus requiring all requests to use HTTPS.
-When you set `quarkus.http.ssl.client-auth` to `required`, the system automatically sets `quarkus.http.insecure-requests` to `disabled`.
+<3> Setting `quarkus.http.ssl.client-auth` to `required` makes the server demand client certificates. You can set it to `REQUEST` if the server should accept requests without a certificate. This setting is useful when supporting multiple authentication methods besides mTLS.
+<4> Defines a policy where only authenticated users can access resources from your application.
+<5> Disables the plain HTTP protocol, requiring all requests to use HTTPS. When you set `quarkus.http.ssl.client-auth` to `required`, `quarkus.http.insecure-requests` is automatically disabled.
 
-When the incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a `SecurityIdentity` as follows:
+When an incoming request matches a valid certificate in the truststore, your application can obtain the subject by injecting a `SecurityIdentity` as follows:
 
 [[x509-subject-example]]
 .Obtaining the subject
@@ -266,6 +282,7 @@ public String hello() {
 ----
 
 You can also get the certificate by using the code outlined in the following example:
+
 [[x509-credential-example]]
 .Obtaining the certificate
 [source,java]
@@ -302,7 +319,7 @@ quarkus.http.auth.permission.certauthenticated.paths=/*   <2>
 quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert <2>
 quarkus.http.auth.policy.role-policy-cert.roles-allowed=user,admin     <2>
 ----
-<1> The `cert-role-mappings.properties` classpath resource contains a map of certificate's CN values to roles in the form `CN=role` or `CN=role1,role2`, etc. Let's assume it contains three entries: `alice=user,admin`, `bob=user` and `jdoe=tester`.
+<1> The `cert-role-mappings.properties` classpath resource contains a map of certificate's CN values to roles in the form `CN=role` or `CN=role1,role2`, etc. Let us assume it contains three entries: `alice=user,admin`, `bob=user` and `jdoe=tester`.
 <2> Use HTTP security policy to require that `SecurityIdentity` must have either `user` or `admin` roles for the requests to be authorized.
 
 Given the preceeding configuration, the request is authorized if the client certificate's CN attribute is equal to `alice` or `bob` and forbidden if it is equal to `jdoe`.
@@ -675,7 +692,7 @@ NOTE: For consistency with various Jakarta EE specifications, it is recommended
 ==== How to combine it with HTTP Security Policy
 
 The easiest way to define roles that are allowed to access individual resources is the `@RolesAllowed` annotation.
-Nevertheless, it's also possible to use the HTTP Security Policy like in the example below:
+Nevertheless, it is also possible to use the HTTP Security Policy like in the example below:
 
 [source,properties]
 ----