Chapter 1. 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.

1.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

$ 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

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>

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.

1.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

/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"}

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"}
```

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
}

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"}

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

1.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

/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"}

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"}

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
}

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"}

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.

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

Additional resources

1.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

/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])

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"
    }
}

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"
    }
}

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.

Verification

Verify that management console is protected.
1. Verify using the CLI:
  Syntax
```
$ curl --verbose --location --cacert <server_certificate> --cert <client_keystore>:<password> --cert-type P12 https://localhost:9993
```
  Example
```
$ curl --verbose --location --cacert server.cer --cert exampleclient.keystore.pkcs12:secret --cert-type P12 https://localhost:9993
...
< HTTP/1.1 200 OK
...
```
2. Verify using a browser.
  1. 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.
  2. Access https://localhost:9993 in a browser.
    The browser prompts you to present a certificate to identify with the server.
  3. 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.
  4. Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the server you generated. You can see 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=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",
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="${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_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.

$ ./jboss-cli.sh --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=/path/to/wildfly-config.xml --connect

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

1.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.

/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])

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"
    }
}

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"
    }
}

Reload the server.
```
reload
```

Verification

Verify that you can access the JBoss EAP welcome page.
1. Verify using the CLI:
  Syntax
```
$ curl --verbose --location --cacert <server_certificate> --cert <client_keystore>:<password> --cert-type P12 https://localhost:8443
```
  Example
```
$ 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>
...
```
2. Verify using a browser.
  1. 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.
  2. Navigate to https://localhost:8443 in a browser.
    The browser prompts you to present a certificate to identify with the server.
  3. 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.
  4. Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the server you generated. You can see 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=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",
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

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

Runtimes

Integration and Automation

Language:

Language:

Chapter 1. Enabling two-way SSL/TLS for management interfaces and applications

1.1. Generating client certificates

1.2. Configuring a trust store and a trust manager for client certificates

1.3. Configuring a server certificate for two-way SSL/TLS

1.4. Configuring SSL context to secure JBoss EAP management interfaces with SSL/TLS

1.5. Configuring `server-ssl-context` to secure applications deployed on JBoss EAP with SSL/TLS

Language:

Language and Page Formatting Options

Language:

Chapter 1. Enabling two-way SSL/TLS for management interfaces and applications

1.1. Generating client certificates

1.2. Configuring a trust store and a trust manager for client certificates

1.3. Configuring a server certificate for two-way SSL/TLS

1.4. Configuring SSL context to secure JBoss EAP management interfaces with SSL/TLS

1.5. Configuring server-ssl-context to secure applications deployed on JBoss EAP with SSL/TLS

1.5. Configuring `server-ssl-context` to secure applications deployed on JBoss EAP with SSL/TLS