Configuring SSL/TLS in JBoss EAP

Procedure

1. Generate a client certificate.

   Syntax

   $ keytool -genkeypair -alias <keystore_alias> -keyalg <algorithm> -keysize <key_size> -validity <validity_in_days> -keystore <keystore_name> -dname "<distinguished_name>" -keypass <private_key_password> -storepass <keystore_password>

   Example

   $ keytool -genkeypair -alias exampleClientKeyStore -keyalg RSA -keysize 2048 -validity 365 -keystore exampleclient.keystore.pkcs12 -dname "CN=client" -keypass secret -storepass secret

2. Export the client certificate to a file.

   Syntax

   $ keytool -exportcert  -keystore <keystore_name> -alias <keystore_alias> -keypass <private_key_password> -storepass <keystore_password> -file <file_path>

   Example

   $ keytool -exportcert  -keystore exampleclient.keystore.pkcs12 -alias exampleClientKeyStore -keypass secret -storepass secret -file EAP_HOME/standalone/configuration/client.cer
   
   Certificate stored in file <EAP_HOME/standalone/configuration/client.cer>

Procedure

1. Configure a trust store with a client certificate by using the management CLI.

   1. Create a server trust store to store the client certificate to trust.

      Syntax

      /subsystem=elytron/key-store=<server_trust_store_name>:add(path=<path_to_server_trust_store_file>,credential-reference={<password>})

      Example

      /subsystem=elytron/key-store=exampleServerTrustStore:add(path=exampleTLSServer.truststore,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret})
      {"outcome" => "success"}

   2. Import the client certificate to the server trust store by specifying the client certificate alias. Only the clients that present a certificate that the server’s trust store trusts can connect to the server.

      Note

      If you are configuring two-way SSL/TLS by using a self-signed certificate, set validate to false because no chain of trust exists for the certificate.

      If you are configuring two-way SSL/TLS in a production environment by using certificates signed by a CA, set validate to true.

      Syntax

      /subsystem=elytron/key-store=<server_trust_store_name>:import-certificate(alias=<alias>,path=<certificate_file>,credential-reference={<password>},trust-cacerts=<true_or_false>,validate=<true_false>)

      Example

      /subsystem=elytron/key-store=exampleServerTrustStore:import-certificate(alias=client,path=client.cer,relative-to=jboss.server.config.dir,credential-reference={clear-text=serverTrustSecret},trust-cacerts=true,validate=false)
      {"outcome" => "success"}

   3. Export the client certificate to a trust store file.

      Syntax

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

      Example

      /subsystem=elytron/key-store=exampleServerTrustStore:store()
      {
          "outcome" => "success",
          "result" => undefined
      }

2. Configure a trust manager to verify the client certificate during the TLS handshake.

   Syntax

   /subsystem=elytron/trust-manager=<trust_manager_name>:add(key-store=<server_trust_store_name>)

   Example

   /subsystem=elytron/trust-manager=exampleTLSTrustManager:add(key-store=exampleServerTrustStore)
   {"outcome" => "success"}

Procedure

1. Generate a self-signed server certificate to use for testing and development purposes. If you have obtained a certificate from a certificate authority (CA), skip this step.

   Important

   Do not use self-signed certificates in a production environment. Use only the certificates signed by a certificate authority (CA).

   1. Create a key store to store server certificate.

      Syntax

      /subsystem=elytron/key-store=<key_store_name>:add(path=<path>,credential-reference={<password>},type=<key_store_type>)

      Example

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

   2. Generate a server certificate in the key store.

      Syntax

      /subsystem=elytron/key-store=<key_store_name>:generate-key-pair(alias=<alias>,algorithm=<algorithm>,key-size=<key_size>,validity=<validaity_in_days>,credential-reference={<password>},distinguished-name="<distinguished_name_in_certificate>")

      Example

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

   3. Store the key store to a file.

      Syntax

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

      Example

      /subsystem=elytron/key-store=exampleServerKeyStore:store()
      {
          "outcome" => "success",
          "result" => undefined
      }

   4. Export the server certificate.

      Syntax

      /subsystem=elytron/key-store=<key_store_name>:export-certificate(alias=<alias>,path=<path_to_certificate>,pem=true)

      Example

      /subsystem=elytron/key-store=exampleServerKeyStore:export-certificate(alias=localhost,path=server.cer,pem=true,relative-to=jboss.server.config.dir)
      {"outcome" => "success"}

2. Create a key manager referencing the server key store.

   Syntax

   /subsystem=elytron/key-manager=<key_manager_name>:add(credential-reference={<password>},key-store=<key_store_name>)

   Example

   /subsystem=elytron/key-manager=exampleServerKeyManager:add(credential-reference={clear-text=secret},key-store=exampleServerKeyStore)
   {"outcome" => "success"}

   The server presents this certificate to the client when SSL/TLS is enabled.

3. Import the server certificate to the client’s trust store so that the client can verify the server certificate during SSL handshake.

   Syntax

   $ keytool -import -file <server_certificate_file> -alias <alias> -keystore <client_trust_store_file> -storepass <password>

   Example

   $ keytool -import -file EAP_HOME/standalone/configuration/server.cer -alias server -keystore client.truststore.p12 -storepass secret
   
   Owner: CN=localhost
   Issuer: CN=localhost
   Serial number: 52679016fbb54f46
   Valid from: Fri Sep 30 18:25:29 IST 2022 until: Sat Sep 30 18:25:29 IST 2023
   Certificate fingerprints:
   	 SHA1: 4B:68:24:9E:2A:2D:01:4E:23:69:94:C8:9A:1C:8F:A5:D4:27:CB:98
   	 SHA256: C0:AF:74:12:90:66:25:B2:65:4E:6B:4B:89:81:2D:6B:D5:2A:F4:04:BC:85:DA:1C:AB:26:6D:57:9F:9F:EE:15
   Signature algorithm name: SHA256withRSA
   Subject Public Key Algorithm: 1024-bit RSA key (disabled)
   Version: 3
   
   Extensions:
   
   #1: ObjectId: 2.5.29.14 Criticality=false
   SubjectKeyIdentifier [
   KeyIdentifier [
   0000: 59 13 DC 6A 81 B9 27 18   6E 72 17 0E 67 FC 9F 8F  Y..j..'.nr..g...
   0010: 04 01 74 8F                                        ..t.
   ]
   ]
   
   
   Warning:
   The input uses a 1024-bit RSA key which is considered a security risk and is disabled.
   
   Trust this certificate? [no]:

   Enter yes. You get the following output:

   Certificate was added to keystore

Procedure

1. Configure a server SSL context to enable two-way SSL.

   Syntax

   /subsystem=elytron/server-ssl-context=<server_ssl_context_name>:add(key-manager=<key_manager_name>,trust-manager=<trust_manager_name>,need-client-auth=true)

   Example

   /subsystem=elytron/server-ssl-context=exampleServerSSLContext:add(key-manager=exampleServerKeyManager,trust-manager=exampleTLSTrustManager,need-client-auth=true)
   {"outcome" => "success"}

   By default, the SSL context uses TLSv1.2. You can configure the protocols attribute to use TLSv1.3 as follows:

   Syntax

   /subsystem=elytron/server-ssl-context=<server-ssl-context-name>:add(key-manager=<key_manager_name>,trust-manager=<trust_manager_name>,need-client-auth=true,protocols=[TLSv1.3])

2. Add a reference to the SSLContext to use for the http management interface.

   Syntax

   /core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=<server_ssl_context_name>)

   Example

   /core-service=management/management-interface=http-interface:write-attribute(name=ssl-context,value=exampleServerSSLContext)
   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

3. Define the socket binding configuration to use for the HTTPS management interface’s socket.

   Syntax

   /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=<socket_binding>)

   Example

   /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)
   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

4. Reload the server.

   reload
   
   ...
   Accept certificate? [N]o, [T]emporarily, [P]ermanently :

   Enter T or P to accept the certificate provided by the server either temporarily or permanently.

   The management CLI disconnects because it expects a client certificate to be presented.

Procedure

1. Configure the default server SSL context to enable two-way SSL.

   /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=need-client-auth,value=true)
   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

   By default, the SSL context uses TLSv1.2. You can configure the protocols attribute to use TLSv1.3 as follows:

   /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=protocols,value=[TLSv1.3])

2. Configure a trust manager for the server SSL context.

   Syntax

   /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=trust-manager,value=<server_trust_manager>)

   Example

   /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=trust-manager,value=exampleTLSTrustManager)
   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

3. Configure a key manager of the server SSL context.

   Syntax

   /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=key-manager,value=<key_manager_name>)

   Example

   /subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=key-manager,value=exampleServerKeyManager)
   {
       "outcome" => "success",
       "response-headers" => {
           "operation-requires-reload" => true,
           "process-state" => "reload-required"
       }
   }

4. Reload the server.

   reload

Procedure

1. Configure the trust manager to use the CRL using one of the following steps:

   • Configure the trust manager to use CRLs obtained from distribution points referenced in your certificates.

     Syntax

     /subsystem=elytron/trust-manager=<trust_manager_name>:write-attribute(name=certificate-revocation-lists,value=[])

     Example

     /subsystem=elytron/trust-manager=exampleTLSTrustManager:write-attribute(name=certificate-revocation-lists,value=[])

   • Override the CRL obtained from distribution points referenced in your certificates.

     Syntax

     /subsystem=elytron/trust-manager=<trust_manager_name>:write-attribute(name=certificate-revocation-lists,value=[{path="<CRL-file-1>"},{path="<CRL-file-2>"},...,{path="<CRL-file-N>"}])

     Example

     /subsystem=elytron/trust-manager=exampleTLSTrustManager:write-attribute(name=certificate-revocation-lists,value=[{path="intermediate.crl.pem"}])

2. Configure the trust manager to use CRL for certificate revocation checking.

   • If an OCSP responder is also configured for certificate revocation checks, add attribute ocsp.prefer-crls with the value true in the trust manager to use CRL for certificate revocation checking:

     Syntax

     /subsystem=elytron/trust-manager=<trust_manager_name>:write-attribute(name=ocsp.prefer-crls,value="true")

     Example

     /subsystem=elytron/trust-manager=exampleTLSTrustManager:write-attribute(name=ocsp.prefer-crls,value="true")

   • If no OCSP responder is configured for certificate revocation checks, the configuration is complete.