Procedure

1. Configure a keystore to store certificates.

   You can either provide a path to an existing keystore, for example, the one that contains CA-signed certificates, or provide a path to the keystore to create.

   /subsystem=elytron/key-store=<keystore_name>:add(path=<path_to_keystore>, credential-reference=<credential_reference>, type=<keystore_type>)

   Example

   /subsystem=elytron/key-store=exampleKeyStore:add(path=exampleserver.keystore.pkcs12, relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=PKCS12)

2. If the keystore doesn’t contain any certificates, or you used the step above to create the keystore, you must generate a certificate and store the certificate in a file.

   1. Generate a key pair in the keystore.

      Syntax

      /subsystem=elytron/key-store=<keystore_name>:generate-key-pair(alias=<keystore_alias>,algorithm=<algorithm>,key-size=<key_size>,validity=<validity_in_days>,credential-reference=<credential_reference>,distinguished-name="<distinguished_name>")

      Example

      /subsystem=elytron/key-store=exampleKeyStore:generate-key-pair(alias=localhost,algorithm=RSA,key-size=2048,validity=365,credential-reference={clear-text=secret},distinguished-name="CN=localhost")

   2. Store the certificate in a file.

      Syntax

      /subsystem=elytron/key-store=<keystore_name>:store()

      Example

      /subsystem=elytron/key-store=exampleKeyStore:store()

3. Configure a key-manager referencing the key-store.

   Syntax

   /subsystem=elytron/key-manager=<key-manager_name>:add(key-store=<key-store_name>,credential-reference=<credential_reference>)

   Example

   /subsystem=elytron/key-manager=exampleKeyManager:add(key-store=exampleKeyStore,credential-reference={clear-text=secret})

   Important

   Red Hat did not specify the algorithm attribute because the elytron subsystem uses KeyManagerFactory.getDefaultAlgorithm() to determine an algorithm by default. However, you can specify the algorithm attribute.

   To specify the algorithm attribute, you need to know what key manager algorithms are provided by the Java Development Kit (JDK) you are using. For example, a JDK that uses Java Secure Socket Extension (SunJSSE) provides the PKIX and SunX509 algorithms.

   In the command you could specify SunX509 as the key-manager algorithm attribute.

4. Configure a server-ssl-context referencing the key-manager.

   Syntax

   /subsystem=elytron/server-ssl-context=<server-ssl-context_name>:add(key-manager=<key-manager_name>, protocols=<list_of_protocols>)

   Example

   /subsystem=elytron/server-ssl-context=examplehttpsSSC:add(key-manager=exampleKeyManager, protocols=["TLSv1.2"])

   Important

   You need to determine what SSL/TLS protocols you want to support. The example command uses TLSv1.2.

   • For TLSv1.2 and earlier, use the cipher-suite-filter argument to specify which cipher suites are allowed.
   • For TLSv1.3, use the cipher-suite-names argument to specify which cipher suites are allowed. TLSv1.3 is disabled by default. If you do not specify a protocol with the protocols attribute or the specified set contains TLSv1.3, configuring cipher-suite-names enables TLSv1.3.

   Use the use-cipher-suites-order argument to honor server cipher suite order. The use-cipher-suites-order attribute is set to true by default. This differs from the legacy security subsystem behavior, which defaults to honoring client cipher suite order.

5. Update the management interfaces to use the configured server-ssl-context.

   Syntax

   /core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=<server-ssl-context_name>)
   /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)

   Example

   /core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=examplehttpsSSC)
   /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)

6. Reload the server.

   reload

   If you used self-signed certificates for enabling SSL/TLS, the management CLI prompts you to accept the certificate that the server presents. This is the certificate you configured the keystore with.

   Example output

   Unable to connect due to unrecognised server certificate
   Subject    - CN=localhost
   Issuer     - CN=localhost
   Valid From - Mon Jan 30 23:47:21 IST 2023
   Valid To   - Tue Jan 30 23:47:21 IST 2024
   MD5 : a1:00:84:78:a6:46:a4:78:4d:44:c8:6d:ba:1f:30:6a
   SHA1 : a4:e5:c1:34:ad:e0:91:18:6f:f6:57:09:91:ae:17:8d:70:f0:1a:7d
   
   
   Accept certificate? [N]o, [T]emporarily, [P]ermanently :

   Enter T or P to proceed with the connection.

Verification

1. Compare the certificate JBoss EAP presented to the browser with the certificate in the server log.

   Example server log

   17:50:24,086 WARN  [org.wildfly.extension.elytron] (default task-1) WFLYELY01085: Generated self-signed certificate at /home/user1/Downloads/wildflies/wildfly-27.0.1.Final/standalone/configuration/application.keystore. Please note that self-signed certificates are not secure and should only be used for testing purposes. Do not use this self-signed certificate in production.
   SHA-1 fingerprint of the generated key is 11:2f:e7:8c:18:b7:2c:c1:b0:5a:ad:ea:83:e0:32:59:ba:73:91:e2
   SHA-256 fingerprint of the generated key is b2:a4:ed:b0:5c:c2:a1:4c:ca:39:03:e8:3a:11:e4:c5:c4:81:9d:46:97:7c:e6:6f:0c:45:f6:5d:64:3f:0d:64

   Example certificate presented to the browser

   SHA-256 Fingerprint	B2 A4 ED B0 5C C2 A1 4C CA 39 03 E8 3A 11 E4 C5
   C4 81 9D 46 97 7C E6 6F 0C 45 F6 5D 64 3F 0D 64
   SHA-1 Fingerprint	11 2F E7 8C 18 B7 2C C1 B0 5A AD EA 83 E0 32 59
   BA 73 91 E2

2. If the fingerprints match, like in the example, you can proceed to the page.

Verification

1. Navigate to https://localhost:8443.

   If you used a self-signed certificate, the browser presents a warning that the certificate presented by the server is unknown.

2. Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the certificate in your keystore. You can view the certificate you generated with the following command:

   Syntax

   /subsystem=elytron/key-store=<server_keystore_name>:read-alias(alias=<alias>)

   Example

   /subsystem=elytron/key-store=key-store-4cba6678-c464-4dcc-90ff-9295312ac395:read-alias(alias="localhost")

   You can get the keystore name from the wizard’s output, for example, "key-store is key-store-4cba6678-c464-4dcc-90ff-9295312ac395".

   Example output

   ...
   "sha-1-digest" => "48:e3:6f:16:d1:af:4b:31:8f:9b:0b:7f:33:94:58:af:69:85:c
   0:ea",
   "sha-256-digest" => "8f:3e:6b:b5:56:e0:d1:97:81:bc:f1:8d:c8:66:75:06:db:7d
   :4d:b6:b1:d3:34:dd:f5:6c:85:ca:c7:2b:5b:c7",
   ...

Procedure

1. Configure a keystore to store certificates.

   You can either provide a path to an existing keystore, for example, the one that contains CA-signed certificates, or provide a path to the keystore to create.

   /subsystem=elytron/key-store=<keystore_name>:add(path=<path_to_keystore>, credential-reference=<credential_reference>, type=<keystore_type>)

   Example

   /subsystem=elytron/key-store=exampleKeyStore:add(path=exampleserver.keystore.pkcs12, relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=PKCS12)

2. If the keystore doesn’t contain any certificates, or you used the step above to create the keystore, you must generate a certificate and store the certificate in a file.

   1. Generate a key pair in the keystore.

      Syntax

      /subsystem=elytron/key-store=<keystore_name>:generate-key-pair(alias=<keystore_alias>,algorithm=<algorithm>,key-size=<key_size>,validity=<validity_in_days>,credential-reference=<credential_reference>,distinguished-name="<distinguished_name>")

      Example

      /subsystem=elytron/key-store=exampleKeyStore:generate-key-pair(alias=localhost,algorithm=RSA,key-size=2048,validity=365,credential-reference={clear-text=secret},distinguished-name="CN=localhost")

   2. Store the certificate in a file.

      Syntax

      /subsystem=elytron/key-store=<keystore_name>:store()

      Example

      /subsystem=elytron/key-store=exampleKeyStore:store()

3. Configure a key-manager referencing the key-store.

   Syntax

   /subsystem=elytron/key-manager=<key-manager_name>:add(key-store=<key-store_name>,credential-reference=<credential_reference>)

   Example

   /subsystem=elytron/key-manager=exampleKeyManager:add(key-store=exampleKeyStore,credential-reference={clear-text=secret})

   Important

   Red Hat did not specify the algorithm attribute because the elytron subsystem uses KeyManagerFactory.getDefaultAlgorithm() to determine an algorithm by default. However, you can specify the algorithm attribute.

   To specify the algorithm attribute, you need to know what key manager algorithms are provided by the Java Development Kit (JDK) you are using. For example, a JDK that uses Java Secure Socket Extension (SunJSSE) provides the PKIX and SunX509 algorithms.

   In the command you could specify SunX509 as the key-manager algorithm attribute.

4. Configure a server-ssl-context referencing the key-manager.

   Syntax

   /subsystem=elytron/server-ssl-context=<server-ssl-context_name>:add(key-manager=<key-manager_name>, protocols=<list_of_protocols>)

   Example

   /subsystem=elytron/server-ssl-context=examplehttpsSSC:add(key-manager=exampleKeyManager, protocols=["TLSv1.2"])

   Important

   You need to determine what SSL/TLS protocols you want to support. The example command uses TLSv1.2.

   • For TLSv1.2 and earlier, use the cipher-suite-filter argument to specify which cipher suites are allowed.
   • For TLSv1.3, use the cipher-suite-names argument to specify which cipher suites are allowed. TLSv1.3 is disabled by default. If you do not specify a protocol with the protocols attribute or the specified set contains TLSv1.3, configuring cipher-suite-names enables TLSv1.3.

   Use the use-cipher-suites-order argument to honor server cipher suite order. The use-cipher-suites-order attribute is set to true by default. This differs from the legacy security subsystem behavior, which defaults to honoring client cipher suite order.

5. Update Undertow to use the configured server-ssl-context.

   Syntax

   /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=<server-ssl-context_name>)

   Example

   /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=examplehttpsSSC)

6. Reload the server.

   reload

Verification

1. Navigate to https://localhost:8443.

   If you used a self-signed certificate, the browser presents a warning that the certificate presented by the server is unknown.

2. Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the certificate in your keystore. You can view the certificate you generated with the following command:

   Syntax

   /subsystem=elytron/key-store=<server_keystore_name>:read-alias(alias=<alias>)

   Example

   /subsystem=elytron/key-store=exampleKeyStore:read-alias(alias=localhost)

   Example output

   ...
   "sha-1-digest" => "cc:f1:82:59:c7:0d:f6:91:bc:3e:69:0a:38:fb:48:be:ec:7f:d
   4:bd",
   "sha-256-digest" => "c0:f3:f9:8b:3c:f1:72:17:64:54:35:a6:bb:82:7e:51:b0:78
   :30:cb:68:ef:04:0e:f5:2b:9d:62:ca:a7:f6:35",
   ...

Procedure

1. Set up a Maven project by using the mvn command. The command creates the directory structure for the project and the pom.xml configuration file.

   $ mvn archetype:generate \
   -DgroupId=com.example.client \
   -DartifactId=client-ssl-context \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-quickstart \
   -DinteractiveMode=false

2. Navigate to the application root directory.

   $ cd client-ssl-context

3. Replace the content of the generated pom.xml file with the following text:

   <?xml version="1.0" encoding="UTF-8"?>
   
   <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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.example.client</groupId>
     <artifactId>client-ssl-context</artifactId>
     <version>1.0-SNAPSHOT</version>
   
     <name>client-ssl-context</name>
   
     <properties>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <maven.compiler.source>11</maven.compiler.source>
       <maven.compiler.target>11</maven.compiler.target>
     </properties>
   
     <repositories>
       <repository>
         <id>jboss-public-maven-repository</id>
         <name>JBoss Public Maven Repository</name>
         <url>https://repository.jboss.org/nexus/content/groups/public/</url>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </snapshots>
         <layout>default</layout>
       </repository>
       <repository>
         <id>redhat-ga-maven-repository</id>
         <name>Red Hat GA Maven Repository</name>
         <url>https://maven.repository.redhat.com/ga/</url>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </snapshots>
         <layout>default</layout>
       </repository>
     </repositories>
   
     <dependencies>
       <dependency>                                         1
         <groupId>org.wildfly.security</groupId>
         <artifactId>wildfly-elytron-client</artifactId>
         <version>2.0.0.Final-redhat-00001</version>
       </dependency>
       <dependency>                                         2
         <groupId>org.wildfly.client</groupId>
         <artifactId>wildfly-client-config</artifactId>
         <version>1.0.1.Final-redhat-00001</version>
       </dependency>
     </dependencies>
   
     <build>
       <plugins>
         <plugin>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>exec-maven-plugin</artifactId>
           <version>1.4.0</version>
           <configuration>
             <mainClass>com.example.client.App</mainClass>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>

   1

   Dependency for wildfly-elytron-client.

   2

   Dependency for wildfly-client-config.

4. Delete the src/test directory.

   $ rm -rf src/test/

Procedure

1. Create a directory to store the Java files.

   $ mkdir -p <application_home>/src/main/java/com/example/client

2. Navigate to the new directory.

   $ cd <application_home>/src/main/java/com/example/client

3. Create the Java file App.java with the following content:

   package com.example.client;
   
   import java.io.IOException;
   import java.net.URI;
   import java.net.http.HttpClient;
   import java.net.http.HttpRequest;
   import java.net.http.HttpResponse;
   import java.net.http.HttpResponse.BodyHandlers;
   import java.security.NoSuchAlgorithmException;
   import java.security.Security;
   import java.util.Properties;
   import javax.net.ssl.SSLContext;
   import org.wildfly.security.auth.client.WildFlyElytronClientDefaultSSLContextProvider;
   
   public class App  {
   
     public static void main( String[] args )  {
     String url = "https://localhost:8443/";                                                                                   1
     try {
       Security.insertProviderAt(new WildFlyElytronClientDefaultSSLContextProvider("src/wildfly-config-two-way-tls.xml"), 1);  2
       HttpClient httpClient = HttpClient.newBuilder().sslContext(SSLContext.getDefault()).build();
       HttpRequest request = HttpRequest.newBuilder()
                   .uri(URI.create(url))
                   .GET()
                   .build();
       HttpResponse<Void> httpRresponse = httpClient.send(request, BodyHandlers.discarding());
       String sslContext = SSLContext.getDefault().getProvider().getName();                                                    3
       System.out.println ("\nSSL Default SSLContext is: " + sslContext);
   
     } catch (NoSuchAlgorithmException | IOException | InterruptedException e) {
         e.printStackTrace();
       }
   
     System.exit(0);
     }
   }

   1

   Defines the JBoss EAP home page URL.

   2

   Register the security provider. 1 defines the priority for this provider. To statically register the provider, you can instead add the provider in the java.security file as: security.provider.1=org.wildfly.security.auth.client.WildFlyElytronClientDefaultSSLContextProvider <PATH>/<TO>/wildfly-config-two-way-tls.xml

   3

   Obtain the default SSL context.

4. Create the client configuration file called "wildfly-config-two-way-tls.xml" in the <application_home>/src directory.

   <?xml version="1.0" encoding="UTF-8"?>
   
   <configuration>
       <authentication-client xmlns="urn:elytron:client:1.7">
           <key-stores>
               <key-store name="truststore" type="PKCS12">
                   <file name="${path_to_client_truststore}/client.truststore.p12"/>
                   <key-store-clear-password password="secret"/>
               </key-store>
               <key-store name="keystore" type="PKCS12">
                   <file name="${path_to_client_keystore}/exampleclient.keystore.pkcs12"/>
                   <key-store-clear-password password="secret"/>
               </key-store>
           </key-stores>
           <ssl-contexts>
               <ssl-context name="client-context">
                   <trust-store key-store-name="truststore"/>
                   <key-store-ssl-certificate key-store-name="keystore" alias="exampleclientkeystore">
                       <key-store-clear-password password="secret"/>
                   </key-store-ssl-certificate>
               </ssl-context>
           </ssl-contexts>
           <ssl-context-rules>
               <rule use-ssl-context="client-context"/>
           </ssl-context-rules>
       </authentication-client>
   </configuration>

   Replace the following place holder values with actual paths:

   • ${path_to_client_truststore}
   • ${path_to_client_keystore}

Verification

1. Navigate to the <application_home> directory.

2. Run the application.

   $ mvn compile exec:java

   Example output

   INFO: ELY00001: WildFly Elytron version 2.0.0.Final-redhat-00001
   
   SSL Default SSLContext is: WildFlyElytronClientDefaultSSLContextProvider