Chapter 2. Enabling two-way SSL/TLS for management interfaces and applications SSL/TLS, or transport layer security (TLS), is a certificates-based security protocol that is used to secure the data transfer between two entities communicating over a network. Use two-way SSL/TLS when you want the server to connect only with trusted clients. Two-way SSL/TLS provides the following security functions: Authentication In one-way SSL/TLS, the server presents its certificate to a client to authenticate itself. In two-way SSL/TLS, the client also presents its certificate to the server for the server to authenticate the client. Two-way SSL/TLS, therefore, is also called mutual authentication. Confidentiality The data transferred between the client and the server is encrypted. Data integrity The TLS protocol provides data integrity with secure hash functions, which are used for message authentication code (MAC) computations. You can enforce specific algorithms and hash functions for the connections using the cipher-suite-filter and cipher-suite-names attributes of the SSL context resources. For more information, see server-ssl-context attributes . You can secure both JBoss EAP management interfaces and deployed applications by using two-way SSL/TLS. To secure management interfaces with two-way SSL/TLS, use the following procedures: Obtain a certificate from a certificate authority (CA) for the client. Alternatively, for non-production environments, you can generate a self-signed certificate by following the procedure: Generate client certificates . Configure a trust store and a trust manager for client certificate Configure a server certificate for two-way SSL/TLS . Configure SSL context to secure JBoss EAP management interfaces with SSL/TLS To secure applications deployed on JBoss EAP with two-way SSL/TLS, use the following procedures: Obtain a certificate from a certificate authority (CA) for the client. Alternatively, for non-production environments, you can generate a self-signed certificate by following the procedure: Generate client certificates . Configure a trust store and a trust manager for client certificate Configure a server certificate for two-way SSL/TLS Configure SSL context to secure applications deployed on JBoss EAP with SSL/TLS You can configure certificate revocation checks by following the procedures in Configuring certificate revocation checks in Elytron . 2.1. Generating client certificates Generate self-signed client certificates using the keytool command, in the CLI, for the purpose of testing and development of a two-way SSL/TLS configuration. Important Do not use self-signed certificates in a production environment. Use only the certificates signed by a certificate authority (CA). Procedure Generate a client certificate. Syntax Example USD keytool -genkeypair -alias exampleClientKeyStore -keyalg RSA -keysize 2048 -validity 365 -keystore exampleclient.keystore.pkcs12 -dname "CN=client" -keypass secret -storepass secret Export the client certificate to a file. Syntax USD keytool -exportcert -keystore <keystore_name> -alias <keystore_alias> -keypass <private_key_password> -storepass <keystore_password> -file <file_path> Example USD 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> You can now use the generated client certificate to configure a server trust store and a trust manager in a server. For more information, see Configuring a trust store and a trust manager for client certificates . 2.2. Configuring a trust store and a trust manager for client certificates Configure a trust store with the client certificate and a trust manager with a reference to the trust store to verify the client certificate during the TLS handshake. Prerequisites You have obtained or generated a client certificate. For more information, see Generating client certificates . JBoss EAP is running. Procedure Configure a trust store with a client certificate by using the management CLI. Create a server trust store to store the client certificate to trust. Syntax Example 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 Example Export the client certificate to a trust store file. Syntax Example Configure a trust manager to verify the client certificate during the TLS handshake. Syntax Example The client certificate in the configured trust store is used to verify the certificate that a client presents during TLS handshake with the server. Additional resources Configuring certificate revocation checks using certificate revocation lists Configuring certificate revocation checks using OCSP in Elytron key-store attributes trust-manager attributes 2.3. Configuring a server certificate for two-way SSL/TLS Configure a server certificate, which will be presented to clients during the TLS handshake. Prerequisites JBoss EAP is running. Procedure 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). Create a key store to store server certificate. Syntax Example Generate a server certificate in the key store. Syntax Example Store the key store to a file. Syntax Example Export the server certificate. Syntax Example Create a key manager referencing the server key store. Syntax Example The server presents this certificate to the client when SSL/TLS is enabled. Import the server certificate to the client's trust store so that the client can verify the server certificate during SSL handshake. Syntax Example Enter yes . You get the following output: steps To secure the management interfaces with two-way SSL/TLS, follow this procedure: Configuring SSL context to secure JBoss EAP interfaces with SSL/TLS To secure applications deployed to JBoss EAP with SSL/TLS, follow this procedure: Configuring SSL context to secure applications deployed on JBoss EAP with SSL/TLS Additional resources key-store attributes key-manager attributes 2.4. Configuring SSL context to secure JBoss EAP management interfaces with SSL/TLS Secure the JBoss EAP management interfaces with two-way SSL/TLS so that only the clients that present a certificate trusted by the server can connect to the server's management interfaces. Prerequisites JBoss EAP is running. You have configured server trust store and a trust manager for client certificates. For more information, see Configuring a trust store and a trust manager for client certificates . You have configured the server certificate. For more information, see Configuring the server certificate for SSL/TLS Procedure Configure a server SSL context to enable two-way SSL. Syntax Example By default, the SSL context uses TLSv1.2. You can configure the protocols attribute to use TLSv1.3 as follows: Syntax Add a reference to the SSLContext to use for the http management interface. Syntax Example Define the socket binding configuration to use for the HTTPS management interface's socket. Syntax Example Reload the server. 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. Verification Verify that management console is protected. Verify using the CLI: Syntax Example Verify using a browser. Import the client certificate into your browser. The example certificate created in the Generating client certificates procedure is called exampleclient.keystore.pkcs12 and the example password to import it is secret . Refer to your browser's documentation for information about importing certificates to the browser. Access https://localhost:9993 in a browser. The browser prompts you to present a certificate to identify with the server. Choose the certificate you imported to the browser. For example, exampleclient.keystore.pkcs12 . If you use a self-signed certificate, the browser presents a warning that the certificate presented by the server is unknown. 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 in a keystore with the following command: Syntax Example After you accept the server certificate, you are prompted for login credentials. You can login using user credentials of existing JBoss EAP users. Verify that management CLI is protected. Create the file wildfly-config.xml with the following content: Example <?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=" USD{path_to_client_truststore} /client.truststore.p12"/> <key-store-clear-password password="secret" /> </key-store> <key-store name="keystore" type="PKCS12"> <file name=" USD{path_to_client_truststore} /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"> <key-store-clear-password password="secret" /> </key-store-ssl-certificate> <providers> <global/> </providers> </ssl-context> </ssl-contexts> <ssl-context-rules> <rule use-ssl-context="client-context" /> </ssl-context-rules> </authentication-client> </configuration> Note You can use masked passwords in the key-store-clear-password element, in place of clear text, for obfuscation. Access management CLI by presenting the client certificate. Both the clients: the client's web browser, and management CLI, trust the server's certificate, and the server trusts both clients. The communication between the client and server is over SSL/TLS. Additional resources server-ssl-context attributes 2.5. Configuring server-ssl-context to secure applications deployed on JBoss EAP with SSL/TLS Elytron provides a default server-ssl-context called applicationSSC , which you can use to configure SSL/TLS. Alternately, you can create your own SSL context in Elytron. The following procedure demonstrates using the default SSL context - applicationSSC , to configure SSL/TLS for applications. Prerequisites JBoss EAP is running. You have configured a server trust store and a trust manager for client certificates. For more information, see Configuring a trust store and a trust manager for client certificates . You have configured the server certificate. For more information, see Configuring the server certificate for SSL/TLS Procedure Configure the default server SSL context to enable two-way SSL. By default, the SSL context uses TLSv1.2. You can configure the protocols attribute to use TLSv1.3 as follows: Configure a trust manager for the server SSL context. Syntax Example Configure a key manager of the server SSL context. Syntax Example Reload the server. Verification Verify that you can access the JBoss EAP welcome page. Verify using the CLI: Syntax Example Verify using a browser. Import the client certificate into your browser. The example certificate created in the Generating client certificates procedure is called exampleclient.keystore.pkcs12 and the example password to import it is secret . Refer to your browser's documentation for information about importing certificates to the browser. Navigate to https://localhost:8443 in a browser. The browser prompts you to present a certificate to identify with the server. Choose the certificate you imported to the browser. For example, exampleclient.keystore.pkcs12 . If you use a self-signed certificate, the browser presents a warning that the certificate presented by the server is unknown. 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 in a keystore with the following command: Syntax Example After you accept the server certificate, you can access JBoss EAP welcome page. Two-way SSL/TLS is now configured for applications. Additional resources server-ssl-context attributes

Commands:
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>
keytool -genkeypair -alias exampleClientKeyStore -keyalg RSA -keysize 2048 -validity 365 -keystore exampleclient.keystore.pkcs12 -dname "CN=client" -keypass secret -storepass secret
keytool -exportcert -keystore <keystore_name> -alias <keystore_alias> -keypass <private_key_password> -storepass <keystore_password> -file <file_path>
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>
/subsystem=elytron/key-store= <server_trust_store_name> :add(path= <path_to_server_trust_store_file> ,credential-reference={ <password> })
/subsystem=elytron/key-store=exampleServerTrustStore:add(path=exampleTLSServer.truststore,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret}) {"outcome" => "success"}
/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> )
/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"}
/subsystem=elytron/key-store= <server_trust_store_name> :store()
/subsystem=elytron/key-store=exampleServerTrustStore:store() { "outcome" => "success", "result" => undefined }
/subsystem=elytron/trust-manager= <trust_manager_name> :add(key-store= <server_trust_store_name> )
/subsystem=elytron/trust-manager=exampleTLSTrustManager:add(key-store=exampleServerTrustStore) {"outcome" => "success"}
/subsystem=elytron/key-store= <key_store_name> :add(path= <path> ,credential-reference={ <password> },type= <key_store_type> )
/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"}
/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> ")
/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"}
/subsystem=elytron/key-store= <key_store_name> :store()
/subsystem=elytron/key-store=exampleServerKeyStore:store() { "outcome" => "success", "result" => undefined }
/subsystem=elytron/key-store= <key_store_name> :export-certificate(alias= <alias> ,path= <path_to_certificate> ,pem=true)
/subsystem=elytron/key-store=exampleServerKeyStore:export-certificate(alias=localhost,path=server.cer,pem=true,relative-to=jboss.server.config.dir) {"outcome" => "success"}
/subsystem=elytron/key-manager= <key_manager_name> :add(credential-reference={ <password> },key-store= <key_store_name> )
/subsystem=elytron/key-manager=exampleServerKeyManager:add(credential-reference={clear-text=secret},key-store=exampleServerKeyStore) {"outcome" => "success"}
keytool -import -file <server_certificate_file> -alias <alias> -keystore <client_trust_store_file> -storepass <password>
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]:
Certificate was added to keystore
/subsystem=elytron/server-ssl-context= <server_ssl_context_name> :add(key-manager= <key_manager_name> ,trust-manager= <trust_manager_name> ,need-client-auth=true)
/subsystem=elytron/server-ssl-context=exampleServerSSLContext:add(key-manager=exampleServerKeyManager,trust-manager=exampleTLSTrustManager,need-client-auth=true) {"outcome" => "success"}
/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])
/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=ssl-context,value=exampleServerSSLContext) { "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } }
/core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value= <socket_binding> )
/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" } }
reload Accept certificate? [N]o, [T]emporarily, [P]ermanently :
curl --verbose --location --cacert <server_certificate> --cert <client_keystore> : <password> --cert-type P12 https://localhost:9993
curl --verbose --location --cacert server.cer --cert EAP_HOME /standalone/configuration/exampleclient.keystore.pkcs12:secret --cert-type P12 https://localhost:9993 < HTTP/1.1 200 OK
/subsystem=elytron/key-store= <server_keystore_name> :read-alias(alias= <alias> )
/subsystem=elytron/key-store=exampleServerKeyStore:read-alias(alias=localhost) "sha-1-digest" => "5e:3e:ad:c8:df:d7:f6:63:38:05:e2:a3:a7:31:07:82:c8:c8:94:47", "sha-256-digest" => "11:b6:8f:00:42:e1:7f:6c:16:ef:db:08:5e:13:d9:b8:16:6e:a0:3c:2e:d4:e5:fd:cb:53:90:88:d2:9c:b1:99",
<?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=" USD{path_to_client_truststore} /client.truststore.p12"/> <key-store-clear-password password="secret" /> </key-store> <key-store name="keystore" type="PKCS12"> <file name=" USD{path_to_client_truststore} /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"> <key-store-clear-password password="secret" /> </key-store-ssl-certificate> <providers> <global/> </providers> </ssl-context> </ssl-contexts> <ssl-context-rules> <rule use-ssl-context="client-context" /> </ssl-context-rules> </authentication-client> </configuration>
./jboss-cli.sh --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=/ path/to/ wildfly-config.xml --connect
/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" } }
/subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=protocols,value=[TLSv1.3])
/subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=trust-manager,value= <server_trust_manager> )
/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" } }
/subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=key-manager,value= <key_manager_name> )
/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" } }
reload
curl --verbose --location --cacert <server_certificate> --cert <client_keystore> : <password> --cert-type P12 https://localhost:8443
curl --verbose --location --cacert server.cer --cert exampleclient.keystore.pkcs12:secret --cert-type P12 https://localhost:8443 <h3>Your Red Hat JBoss Enterprise Application Platform is running.</h3>
/subsystem=elytron/key-store= <server_keystore_name> :read-alias(alias= <alias> )
/subsystem=elytron/key-store=exampleServerKeyStore:read-alias(alias=localhost) "sha-1-digest" => "5e:3e:ad:c8:df:d7:f6:63:38:05:e2:a3:a7:31:07:82:c8:c8:94:47", "sha-256-digest" => "11:b6:8f:00:42:e1:7f:6c:16:ef:db:08:5e:13:d9:b8:16:6e:a0:3c:2e:d4:e5:fd:cb:53:90:88:d2:9c:b1:99",