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.
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 tohttp-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.
NoteTo 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
orP
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’sstandalone/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.
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.
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.
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 thekey-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})
ImportantRed Hat did not specify the algorithm attribute because the
elytron
subsystem usesKeyManagerFactory.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 thekey-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"])
ImportantYou 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 theprotocols
attribute or the specified set contains TLSv1.3, configuringcipher-suite-names
enables TLSv1.3.
Use the
use-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute is set totrue
by default. This differs from the legacy security subsystem behavior, which defaults to honoring client cipher suite order.-
For TLSv1.2 and earlier, use the
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
orP
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’sstandalone/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.
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.
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
namedapplicationKS
. -
A
key-manager
, namedapplicationKM
, referencing thekey-store
. -
A
server-ssl-context
, namedapplicationSSC
, referencing thekey-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.
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
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.
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 Undertowhttps-listener
.
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 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
NoteThe
elytron
subsystem contains an already configuredserver-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 theserver-ssl-context
created by the wizard to enable SSL.NoteTo 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.
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.
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 thekey-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})
ImportantRed Hat did not specify the algorithm attribute because the
elytron
subsystem usesKeyManagerFactory.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 thekey-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"])
ImportantYou 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 theprotocols
attribute or the specified set contains TLSv1.3, configuringcipher-suite-names
enables TLSv1.3.
Use the
use-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute is set totrue
by default. This differs from the legacy security subsystem behavior, which defaults to honoring client cipher suite order.-
For TLSv1.2 and earlier, use the
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.
Inspect the certificate and verify that the fingerprints shown in your browser match the fingerprints of the certificate in your keystore. You can view the certificate you generated with the following command:
Syntax
/subsystem=elytron/key-store=<server_keystore_name>:read-alias(alias=<alias>)
Example
/subsystem=elytron/key-store=exampleKeyStore:read-alias(alias=localhost)
Example output
... "sha-1-digest" => "cc:f1:82:59:c7:0d:f6:91:bc:3e:69:0a:38:fb:48:be:ec:7f:d 4:bd", "sha-256-digest" => "c0:f3:f9:8b:3c:f1:72:17:64:54:35:a6:bb:82:7e:51:b0:78 :30:cb:68:ef:04:0e:f5:2b:9d:62:ca:a7:f6:35", ...
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