Language:
Format:

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

You can enable one-way SSL/TLS both for the JBoss EAP management interfaces and the applications deployed on JBoss EAP. For more information, see the following procedures:

1.1. Enabling one-way SSL/TLS for management interfaces

Enable one-way SSL/TLS for management interfaces so that the communication between JBoss EAP management interfaces and the clients connecting to the interfaces is secure.

To enable one-way SSL/TLS for management interfaces, you can use the following procedures:

Enabling one-way SSL/TLS for management interfaces by using the wizard: Use this procedure to quickly set up SSL/TLS using a CLI-based wizard. Elytron creates the required resources for you based on your inputs to the wizard.
Enable one-way SSL/TLS for management interfaces by using the subsystem commands: Use this procedure to configure the required resource for enabling SSL/TLS manually. Manually configuring the resources gives you more control over the server configuration.

Additionally, you can disable SSL/TLS for management interfaces using the procedure Disabling SSL/TLS for management interfaces by using the security command.

1.1.1. Enabling one-way SSL/TLS for management interfaces by using the wizard

Elytron provides a wizard to quickly set up SSL/TLS. You can either use an existing keystore containing certificates or use the keystore and self-signed certificates that the wizard generates to enable SSL/TLS. You can also obtain and use certificates from the Let’s Encrypt certificate authority by using the --lets-encrypt option. For information about Let’s Encrypt, see the Let’s Encrypt documentation.

Use the self-signed certificates the wizard generates to enable SSL/TLS for testing and development purposes only. For production environments always use certificate authority (CA)-signed certificates.

Important

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

The wizard configures the following resources that are required to enable SSL/TLS for for management interfaces:

key-store
key-manager
server-ssl-context
The server-ssl-context is then applied to http-interface.

Elytron names each resource as resource-type-UUID. For example, key-store-9e35a3be-62bb-4fff-afc2-2d8d141b82bc. The universally unique identifier (UUID) helps avoid name collisions for the resources.

Prerequisites

JBoss EAP is running.

Procedure

Launch the wizard to configure one-way SSL/TLS for management interfaces by entering the following command in the management CLI.

Syntax

security enable-ssl-management --interactive

Enter the required information when prompted.

Use the --lets-encrypt option to obtain and use certificates from the Let’s Encrypt certificate authority.

If SSL/TLS is already enabled for management interfaces the wizard exits with the following message:

SSL is already enabled for http-interface

To change the existing configuration, first disable SSL/TLS for management interfaces and then create a new configuration. For information about disabling SSL/TLS for management interfaces, see Disabling SSL/TLS for management interfaces by using the wizard.

Note

To enable one-way SSL/TLS, enter n or blank when prompted to enable SSL mutual authentication. Setting mutual authentication enables two-way SSL/TLS.

Example of using the wizard interactively

security enable-ssl-management --interactive

Example inputs to the wizard prompts

Please provide required pieces of information to enable SSL:

Certificate info:
Key-store file name (default management.keystore): exampleKeystore.pkcs12
Password (blank generated): secret
What is your first and last name? [Unknown]: localhost
What is the name of your organizational unit? [Unknown]:
What is the name of your organization? [Unknown]:
What is the name of your City or Locality? [Unknown]:
What is the name of your State or Province? [Unknown]:
What is the two-letter country code for this unit? [Unknown]:
Is CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?y
Validity (in days, blank default): 365
Alias (blank generated): localhost
Enable SSL Mutual Authentication y/n (blank n):n //For one way SSL/TLS enter blank or n here

SSL options:
keystore file: exampleKeystore.pkcs12
distinguished name: CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown,
C=Unknown
password: secret
validity: 365
alias: localhost
Server keystore file exampleKeystore.pkcs12, certificate file exampleKeystore.pem and exampleKeystore.csr file will be generated in server configuration directory.

Do you confirm y/n :y

After you enter y, the server reloads. If you configured a self-signed certificate, used the wizard to generate self-signed certificate or configured a certificate that is not trusted by the Java virtual machine (JVM), the management CLI prompts you to accept the certificate that the server presents.

Unable to connect due to unrecognised server certificate
Subject    - CN=localhost,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown
Issuer     - CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
Valid From - Mon Jan 30 23:32:20 IST 2023
Valid To   - Tue Jan 30 23:32:20 IST 2024
MD5 : b6:e7:f0:57:59:9e:bf:b8:20:99:10:fc:e2:0b:0f:d0
SHA1 : 9c:f0:92:de:c1:11:df:71:0b:d7:16:02:c8:7e:c9:83:ab:e3:0c:2e


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

Enter T or P to proceed with the connection.

You get the following output:

Server reloaded.
SSL enabled for http-interface
ssl-context is ssl-context-a18ba30e-6a26-4ed6-87c5-feb7f3e4dff1
key-manager is key-manager-a18ba30e-6a26-4ed6-87c5-feb7f3e4dff1
key-store   is key-store-a18ba30e-6a26-4ed6-87c5-feb7f3e4dff1

Verification

Verify SSL/TLS by connecting with the management CLI client.

You can test SSL/TLS by placing an Elytron client SSL context in a configuration file and then connecting to the server using the management CLI and referencing the configuration file.

Navigate to the directory containing the keystore file. In this example, the keystore file exampleKeystore.pkcs12 was generated in the server’s standalone/configuration directory.
Example
```
$ cd JBOSS_HOME/standalone/configuration
```

Create a client trust-store with server certificates.

Syntax

$ keytool -importcert -keystore <trust_store_name> -storepass <password> -alias <alias> -trustcacerts -file <file_containing_server_certificate>

Example

$ keytool -importcert -keystore client.truststore.pkcs12 -storepass secret -alias localhost -trustcacerts -file exampleKeystore.pem

If you used a self-signed certificate, you are prompted to trust the certificate.

Define the client-side SSL context in a file, for example example-security.xml.

Syntax

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.2">
        <key-stores>
            <key-store name="${key-store_name}" type="PKCS12" >
                <file name="${path_to_truststore}"/>
                <key-store-clear-password password="${keystore_password}" />
            </key-store>
        </key-stores>
        <ssl-contexts>
            <ssl-context name="${ssl_context_name}">
                <trust-store key-store-name="${trust_store_name}" />
            </ssl-context>
        </ssl-contexts>
        <ssl-context-rules>
            <rule use-ssl-context="${ssl_context_name}" />
        </ssl-context-rules>
    </authentication-client>
</configuration>

Example

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.2">
        <key-stores>
            <key-store name="clientStore" type="PKCS12" >
                <file name="JBOSS_HOME/standalone/configuration/client.truststore.pkcs12"/>
                <key-store-clear-password password="secret" />
            </key-store>
        </key-stores>
        <ssl-contexts>
            <ssl-context name="client-SSL-context">
                <trust-store key-store-name="clientStore" />
            </ssl-context>
        </ssl-contexts>
        <ssl-context-rules>
            <rule use-ssl-context="client-SSL-context" />
        </ssl-context-rules>
    </authentication-client>
</configuration>

Connect to the server and issue a command.

Example

$ EAP_HOME/bin/jboss-cli.sh -c --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=<path_to_the_configuration_file>/example-security.xml :whoami

Expected output

{
    "outcome" => "success",
    "result" => {"identity" => {"username" => "$local"}}
}

Verify SSL/TLS by using a browser.
1. Navigate to https://localhost:9993.
  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-a18ba30e-6a26-4ed6-87c5-feb7f3e4dff1:read-alias(alias="localhost")
```
  You can get the keystore name from the wizard’s output, for example, "key-store is key-store-a18ba30e-6a26-4ed6-87c5-feb7f3e4dff1".
  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",
...
```
  After you accept the server certificate, you are prompted for login credentials. You can login using user credentials of existing JBoss EAP users.

SSL/TLS is now enabled for JBoss EAP management interfaces.

Additional resources

1.1.2. Enabling one-way SSL/TLS for management interfaces by using the subsystem commands

Use the elytron subsystem commands to secure the JBoss EAP management interfaces with SSL/TLS.

For testing and development purposes, you can use self-signed certificates. You can either use an existing keystore containing certificates or use the keystore that Elytron generates when you create the key-store resource. For production environments always use certificate authority (CA)-signed certificates.

Important

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

Prerequisites

JBoss EAP is running.

Procedure

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)

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.

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

Store the certificate in a file.

Syntax

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

Example

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

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

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)

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

Verify SSL/TLS by connecting through a client.

You can test SSL/TLS by placing an Elytron client SSL context in a configuration file and then connecting to the server by using the management CLI referencing the configuration file.

Navigate to the directory containing the keystore file. In this example, the keystore file exampleserver.keystore.pkcs12 was generated in the server’s standalone/configuration directory.
Example
```
$ cd JBOSS_HOME/standalone/configuration
```

Export the server certificate so that it can be imported into a client trust store.

$ keytool -export -alias <alias> -keystore <key_store> -storepass <keystore_password>-file <file_name>

Example

$ keytool -export -alias localhost -keystore exampleserver.keystore.pkcs12 -file -storepass secret server.cer

Create a client trust-store with the server certificates.

Syntax

$ keytool -importcert -keystore <trust_store_name> -storepass <password> -alias <alias> -trustcacerts -file <file_containing_server_certificate>

Example

$ keytool -importcert -keystore client.truststore.pkcs12 -storepass secret -alias localhost -trustcacerts -file server.cer

If you used a self-signed certificate, you are prompted to trust the certificate.

Define the client-side SSL context in a file, for example example-security.xml.

Syntax

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.2">
        <key-stores>
            <key-store name="${key-store_name}" type="PKCS12" >
                <file name="${path_to_truststore}"/>
                <key-store-clear-password password="${keystore_password}" />
            </key-store>
        </key-stores>
        <ssl-contexts>
            <ssl-context name="${ssl_context_name}">
                <trust-store key-store-name="${trust_store_name}" />
            </ssl-context>
        </ssl-contexts>
        <ssl-context-rules>
            <rule use-ssl-context="${ssl_context_name}" />
        </ssl-context-rules>
    </authentication-client>
</configuration>

Example

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.2">
        <key-stores>
            <key-store name="clientStore" type="PKCS12" >
                <file name="JBOSS_HOME/standalone/configuration/client.truststore.pkcs12"/>
                <key-store-clear-password password="secret" />
            </key-store>
        </key-stores>
        <ssl-contexts>
            <ssl-context name="client-SSL-context">
                <trust-store key-store-name="clientStore" />
            </ssl-context>
        </ssl-contexts>
        <ssl-context-rules>
            <rule use-ssl-context="client-SSL-context" />
        </ssl-context-rules>
    </authentication-client>
</configuration>

Connect to the server and issue a command.

Example

$ EAP_HOME/bin/jboss-cli.sh -c --controller=remote+https://127.0.0.1:9993 -Dwildfly.config.url=example-security.xml :whoami

Expected output

{
    "outcome" => "success",
    "result" => {"identity" => {"username" => "$local"}}
}

Verify SSL/TLS by using a browser.
1. Navigate to https://localhost:9993.
  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" => "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",
...
```
  After you accept the server certificate, you are prompted for login credentials. You can login using user credentials of existing JBoss EAP users.

SSL/TLS is now enabled for JBoss EAP management interfaces.

Additional resources

1.1.3. Disabling SSL/TLS for management interfaces by using the `security` command

Use the security command to disable SSL/TLS for management interfaces. You might want to do this to use a different SSL/TLS configuration to the one that is configured.

Disabling SSL/TLS using the command does not delete the Elytron resources. The command just undefines the secure-socket-binding and the ssl-context attributes of the http-interface management-interface resource.

Prerequisites

JBoss EAP is running.

Procedure

Use the disable-ssl-management command in the management CLI.

security disable-ssl-management

The server reloads with the following output:

...
Server reloaded.
Reconnected to server.
SSL disabled for http-interface

You can enable SSL/TLS for server management interfaces using one of the following methods:

Enable one-way SSL/TLS for management interfaces by using the wizard: Use this procedure to quickly set up SSL/TLS using a CLI-based wizard. Elytron creates the required resources for you based on your inputs to the wizard.
Enable one-way SSL/TLS for management interfaces by using the subsystem commands: Use this procedure to configure the required resource for enabling SSL/TLS manually. Manually configuring the resources gives you more control over the server configuration.

1.2. Enabling one-way SSL/TLS for applications deployed on JBoss EAP

Enable one-way SSL/TLS for applications deployed on JBoss EAP so that the communication between the applications and clients, such as web browsers, is secure.

To enable one-way SSL/TLS for applications deployed on JBoss EAP, you can use the following procedures:

Enabling SSL/TLS for applications by using the automatically generated self-signed certificate: Use this procedure in development or testing environments only. This procedure helps you to quickly enable SSL/TLS for applications without having to do any configurations.
Enable one-way SSL/TLS for applications deployed on JBoss EAP by using the wizard: Use this procedure to quickly set up SSL/TLS using a CLI-based wizard. Elytron creates the required resources for you based on your inputs to the wizard.
Enabling one-way SSL/TLS for applications by using the subsystem commands: Use this method to configure the required resource for enabling SSL/TLS manually. Manually configuring the resources gives you more control over the server configuration.

Additionally, you can disable SSL/TLS for applications deployed on JBoss EAP by using the procedure Disabling SSL/TLS for applications by using the security command.

1.2.1. The default SSL context in Elytron

To help developers quickly set up one-way SSL/TLS for applications, the elytron subsystem contains the required resources to enable one-way SSL/TLS, ready to use in a development or testing environment by default.

The following resources are provided by default:

A key-store named applicationKS.
A key-manager, named applicationKM, referencing the key-store.
A server-ssl-context, named applicationSSC, referencing the key-manager.

Default TLS configuration

...
<tls>
    <key-stores>
        <key-store name="applicationKS">
            <credential-reference clear-text="password"/>
            <implementation type="JKS"/>
            <file path="application.keystore" relative-to="jboss.server.config.dir"/>
        </key-store>
    </key-stores>
    <key-managers>
        <key-manager name="applicationKM" key-store="applicationKS" generate-self-signed-certificate-host="localhost">
            <credential-reference clear-text="password"/>
        </key-manager>
    </key-managers>
    <server-ssl-contexts>
        <server-ssl-context name="applicationSSC" key-manager="applicationKM"/>
    </server-ssl-contexts>
</tls>
...

The default key-manager, applicationKM, contains a generate-self-signed-certificate-host attribute with the value localhost. The generate-self-signed-certificate-host attribute indicates that when this key-manager is used to obtain the server’s certificate, if the file that backs its key-store doesn’t already exist, then the key-manager should automatically generate a self-signed certificate with localhost as the Common Name. This generated self-signed certificate is stored in the file that backs the key-store.

As the file that backs the default key-store doesn’t exist when the server is installed, just sending an https request to the server generates a self-signed certificate and enables one-way SSL/TLS for application. For more information, see Enabling SSL/TLS for applications by using the automatically generated self-signed certificate.

Additional resources

1.2.2. Enabling SSL/TLS for applications by using the automatically generated self-signed certificate

JBoss EAP automatically generates a self-signed certificate the first time the server receives an HTTPS request. The elytron subsystem also contains key-store, key-manager, and server-ssl-context resources that are ready to use in a development or testing environment by default. Therefore, as soon as JBoss EAP generates a self-signed certificate, the applications are secured using the certificate.

Important

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

Prerequisites

JBoss EAP is running.

Procedure

Navigate to the server URL at the port 8443, for example, https://localhost:8443.
JBoss EAP generates a self-signed certificate when it receives this request. You can see the server logs for details about this certificate.
The browser flags the connection as insecure because the generated certificate is self-signed.

Verification

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

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

SSL/TLS is enabled for applications.

Additional resources

1.2.3. Enabling one-way SSL/TLS for applications deployed on JBoss EAP by using the wizard

Important

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

The wizard configures the following resources that are required to enable SSL/TLS for applications:

key-store
key-manager
server-ssl-context
The server-ssl-context is then applied to Undertow https-listener.

Prerequisites

JBoss EAP is running.

Procedure

Launch the wizard to configure one-way SSL/TLS for applications by entering the following command in the management CLI:

Syntax

security enable-ssl-http-server --interactive

Enter the required information when prompted.

Use the --lets-encrypt option to obtain and use certificates from the Let’s Encrypt certificate authority.

If a server-ssl-context already exists, the wizard exits with the following message:

An SSL server context already exists on the HTTPS listener, use --override-ssl-context option to overwrite the existing SSL context

Note

The elytron subsystem contains an already configured server-ssl-context resource by default. Therefore, you must use the --override-ssl-context option the first time you launch the wizard after a fresh installation.

For more information, see The default SSL context in Elytron.

If you override the existing server-ssl-context, Elytron will use the server-ssl-context created by the wizard to enable SSL.

Note

To enable one-way SSL/TLS, enter n or blank when prompted to enable SSL mutual authentication. Setting mutual authentication enables two-way SSL/TLS.

Example of starting the wizard

security enable-ssl-http-server --interactive --override-ssl-context

Example inputs to the wizard prompts

Please provide required pieces of information to enable SSL:

Certificate info:
Key-store file name (default default-server.keystore): exampleKeystore.pkcs12
Password (blank generated): secret
What is your first and last name? [Unknown]: localhost
What is the name of your organizational unit? [Unknown]:
What is the name of your organization? [Unknown]:
What is the name of your City or Locality? [Unknown]:
What is the name of your State or Province? [Unknown]:
What is the two-letter country code for this unit? [Unknown]:
Is CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?y
Validity (in days, blank default): 365
Alias (blank generated): localhost
Enable SSL Mutual Authentication y/n (blank n):n //For one way SSL/TLS enter blank or n here

SSL options:
keystore file: exampleKeystore.pkcs12
distinguished name: CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
password: secret
validity: 365
alias: localhost
Server keystore file exampleKeystore.pkcs12, certificate file exampleKeystore.pem and
exampleKeystore.csr file will be generated in server configuration directory.

Do you confirm y/n :y

After you enter y, the server reloads with the following output:

Server reloaded.
SSL enabled for default-server
ssl-context is ssl-context-4cba6678-c464-4dcc-90ff-9295312ac395
key-manager is key-manager-4cba6678-c464-4dcc-90ff-9295312ac395
key-store   is key-store-4cba6678-c464-4dcc-90ff-9295312ac395

Verification

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.

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",
...

SSL/TLS is now enabled for applications deployed on JBoss EAP.

Additional resources

1.2.4. Enabling one-way SSL/TLS for applications by using the subsystem commands

Use the elytron subsystem commands to secure the applications deployed on JBoss EAP with SSL/TLS.

Important

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

Prerequisites

JBoss EAP is running.

Procedure

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)

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.

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

Store the certificate in a file.

Syntax

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

Example

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

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

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)

Reload the server.
```
reload
```

Verification

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.

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",
...

SSL/TLS is now enabled for applications deployed on JBoss EAP.

Additional resources

1.2.5. Disabling SSL/TLS for applications by using the `security` command

Use the security command to disable SSL/TLS for applications deployed on JBoss EAP. Disabling SSL/TLS using the command does not delete the Elytron resources. The command just sets the ssl-context for the server to its default value applicationSSC.

Prerequisites

JBoss EAP is running.

Procedure

Use the security disable-ssl-http-server command in the management CLI.
```
security disable-ssl-http-server
```
The server reloads with the following output:
```
...
Server reloaded.
SSL disabled for default-server
```

You can enable SSL/TLS for applications deployed on JBoss EAP using one of the following procedure:

Enabling SSL/TLS for applications by using the automatically generated self-signed certificate: Use this procedure in development or testing environments only. This procedure helps you to quickly enable SSL/TLS for applications without having to do any configurations.
Enable one-way SSL/TLS for applications deployed on JBoss EAP by using the wizard: Use this procedure to quickly set up SSL/TLS using a CLI-based wizard. Elytron creates the required resources for you based on your inputs to the wizard.
Enabling one-way SSL/TLS for applications by using the subsystem commands: Use this method to configure the required resource for enabling SSL/TLS manually. Manually configuring the resources gives you more control over the server configuration.

Additional resources

Select Your Language

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

1.1. Enabling one-way SSL/TLS for management interfaces

1.1.1. Enabling one-way SSL/TLS for management interfaces by using the wizard

1.1.2. Enabling one-way SSL/TLS for management interfaces by using the subsystem commands

1.1.3. Disabling SSL/TLS for management interfaces by using the `security` command

1.2. Enabling one-way SSL/TLS for applications deployed on JBoss EAP

1.2.1. The default SSL context in Elytron

1.2.2. Enabling SSL/TLS for applications by using the automatically generated self-signed certificate

1.2.3. Enabling one-way SSL/TLS for applications deployed on JBoss EAP by using the wizard

1.2.4. Enabling one-way SSL/TLS for applications by using the subsystem commands

1.2.5. Disabling SSL/TLS for applications by using the `security` command

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language and Page Formatting Options

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

1.1. Enabling one-way SSL/TLS for management interfaces

1.1.1. Enabling one-way SSL/TLS for management interfaces by using the wizard

1.1.2. Enabling one-way SSL/TLS for management interfaces by using the subsystem commands

1.1.3. Disabling SSL/TLS for management interfaces by using the security command

1.2. Enabling one-way SSL/TLS for applications deployed on JBoss EAP

1.2.1. The default SSL context in Elytron

1.2.2. Enabling SSL/TLS for applications by using the automatically generated self-signed certificate

1.2.3. Enabling one-way SSL/TLS for applications deployed on JBoss EAP by using the wizard

1.2.4. Enabling one-way SSL/TLS for applications by using the subsystem commands

1.2.5. Disabling SSL/TLS for applications by using the security command

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links

1.1.3. Disabling SSL/TLS for management interfaces by using the `security` command

1.2.5. Disabling SSL/TLS for applications by using the `security` command