Configuring TLS for the Webswing Server

You can run the Webswing server for your AAI Configuration Tool on a secure HTTPS/SSL communication protocol. For this you need to configure TLS for the server, as described in this topic.

Overview of Configuring TLS for Webswing

You configure TLS for secure communication with the Webswing server over an HTTPS protocol by configuring truststores, keystores, and their passwords in two properties files: jetty.properties and webswing.properties.

Configuring a secure TLS connection for the Webswing communication with the AAI Configuration Tool involves the following tasks:

1. Preparing for setup

2. Configuring the jetty.properties files to disable HTTP and configure the HTTPS communication between Webswing and AAI Configuration Tool

3. Configuring the webswing.properties file to configure the communication between Webswing and Websocket, which provides the secure socket layer

4. Restart Webswing

Step 1. Prepare for TLS Configuration for Webswing

You will need authentication certificates when you configure the jetty.properties and webswing,properties files, which you do as part of configuring the TLS authentication. Therefore, before you begin, make sure to the have the following ready:

• A truststore certificate

• A keystore certificate

For both certificate types, you can get the certificate from any of the following ways:

• Use the ones that you use for the AAI server

• Use ones that you have for another product

• Obtain and import new certificates, as described in the steps that follow under To prepare a new keystore certificate and file.

To prepare a new keystore certificate and file

1. Generate the keystore key with the following command:
   

   keytool -genkey -alias aaiserver -keyalg RSA -keystore sc649152.keystore -ext SAN=dns:<hostname>,dns:<hostname>.<domain>.com,ip:<IP address> -validity <days>

   Example:

   keytool -genkey -alias aaiserver -keyalg RSA -keystore sc649152.keystore -ext SAN=dns:HPZTC44,dns:HPZTC44.broadcom.com,ip:192.168.50.140 -validity 3650

2. Import the certificate into a new keystore with the following command:

   keytool -importkeystore -srckeystore <keystore file> -destkeystore <keystore file> -deststoretype <type>

   Example:

   keytool -importkeystore -srckeystore sc649152.keystore -destkeystore sc649152.keystore -deststoretype pkcs12

   Note:

   You can use the same command to copy a keystore to another keystore type. JKS and JCEKS are Java specific; for interoperability, which means it is compatible with other products as well, it is recommended that you use the keystore type PKCS12.

3.  Put the keystore in the <AAI_installation>/config/ssl directory or in a directory outside the <AAI_installation> directory.

   Important!

   Do not put the keystore for Webswing in the <AAI_installation>/config directory! It will be overwritten during AAI updates.

To prepare the truststore certificate and file

If you need to create a truststore certificate, use the steps for the keystore file, replacing "truststore" wherever you see "keystore" in the commands. See To prepare a new keystore certificate and file.

To get obfuscated passwords

To ensure better security, you need to obfuscate the passwords for the keystore and truststore using a Jetty utility, as follows:

1. Find the latest version of jetty-util from Maven Central (https://mvnrepository.com/artifact/org.eclipse.jetty/jetty-util)

2. Download the JAR file.

3. Run java -cp jetty-util-9.4.18.v20190429.jar org.eclipse.jetty.util.security.Password <password>, with the password you want to obfuscate.

4. Copy and save the obfuscated password so you have it ready for Step 2. Configure the jetty.properties for Secure HTTPS.
   

Step 2. Configure the jetty.properties for Secure HTTPS

To configure HTTPS/SLL communication between Webswing and the AAI Configuration Tool you must first configure the jetty.properties file to disable HTTP and with the necessary communications parameters, as follows

1. Open the jetty.properties file in the /<AAI_installation>/config folder to edit it.

2. Disable HTTP by setting the following parameter:

   org.webswing.server.http=false

3. Enable HTTPS by setting the following parameters:

   org.webswing.server.https=true

   org.webswing.server.https.port=<port to access over https, make sure it is not blocked by firewall>

   The default Webswing port for HTTPS is 8488. You can use another port. As noted in the properties file, make sure the port is not blocked by a firewall in your organization.

4. Configure a keystore in the following parameters using the certificate you prepared in Step 1. Prepare for TLS Configuration for Webswing:

   • org.webswing.server.https.keystore: 

     • If you put the keystore in the <AAI_installation>/config/ssl directory, replace "keystore.p12" in "ssl/keystore.p12" with the name of your keystore.

     • If you put the keystore outside the <AAI_installation> directory, replace "ssl/keystore.p12" with the filename with its absolute path.

   • org.webswing.server.https.keystore.type: Specify the keystore type.

     Valid values are JKS, JCEKS, DKS, PKCS11, PKCS12

   • org.webswing.server.https.keystore.password = ODF:<obfuscated password>

     Specify the obfuscated password that you prepared in Step 1. Prepare for TLS Configuration for Webswing

     Example:

     org.webswing.server.https.keystore.password=OBF:18xp18xr18xt18xp18xr18xt

     You can use the same password for both the keystore and the truststore.

5. Configure a truststore in the same way as described for the keystore, but in the equivalent truststore parameters.

   • org.webswing.server.https.truststore:  

     • If you put the truststore in the <AAI_installation>/config/ssl directory, replace "truststore.p12" in "ssl/truststore.p12" with the name of your keystore.

     • If you put the truststore outside the <AAI_installation> directory, replace "ssl/truststore.p12" with the filename with its absolute path.

   • org.webswing.server.https.truststore.type: Specify the keystore type.

     Valid values are JKS, JCEKS, DKS, PKCS11, PKCS12

   • org.webswing.server.https.truststore.password : Specify the obfuscated password that you prepared in Step 1. Prepare for TLS Configuration for Webswing.

     Example:

     org.webswing.server.https.truststore.password=OBF:18xp18xr18xt18xp18xr18xt

     You can use the same password as you did for the keystore.

6. Add the following parameter to disable the Single Name Indicator (sni) HTTPS extension.

   org.webswing.server.sniRequired=false

7. Continue with Step 3. Configure the webswing.properties to update Websocket.

Step 3. Configure the webswing.properties to update Websocket

Webswing uses Websocket for its internal communication between the Webswing process and the application process. Therefore, you must also secure that communication. To do that you must configure the websing.properties file with the same configuration as your truststore in the jetty.properties file, as described in the steps that follow.

1. Open the webswing.properties file in the /<AAI_installation>/config folder to edit it.

2. Remove the # at the beginning of each of these parameters to un-comment them, and enter the same values from your configured jetty.properties file:

   • webswing.server.https.truststore

   • webswing.server.https.truststore.type

   • webswing.server.https.truststore.password

   Important!

   To secure the Webswing-Websocket communication, Websocket protocol must use the same certificate as Webswing. Therefore, you must configure a truststore with the identical values that you defined for the same truststore parameters in the jetty.properties file.

3. Continue with Step 4. Restart Webswing.

Step 4. Restart Webswing

Stop and restart the Webswing server to apply the security settings to the Webswing communication with the AAI Configuration Tool in your system. For information, see Manually Starting or Stopping the Webswing Server for the AAI Configuration Tool in Configuring Webswing for the AAI Configuration Tool.

Reference: The Contents of the Properties Files for Webswing TLS

For your reference, the contents of the default, delivered properties files that you use to configure TLS for Webswing to secure communication with AAI Configuration Tool are provided here.

jetty.properties

The jetty.properties file contains the following properties before you update it with your configurations. For information, see Step 2. Configure the jetty.properties for Secure HTTPS.

org.webswing.server.host=0.0.0.0

 

org.webswing.server.http=true

org.webswing.server.http.port=8088

 

org.webswing.server.https=true

org.webswing.server.https.port=8488

org.webswing.server.https.truststore=ssl/truststore.p12

# To obfuscate the password run >java -cp jetty-util-9.4.18.v20190429.jar org.eclipse.jetty.util.security.Password <password>

org.webswing.server.https.truststore.password=OBF:18xp18xr18xt18xp18xr18xt

org.webswing.server.https.truststore.type=PKCS12

 

org.webswing.server.https.keystore=ssl/keystore.p12

org.webswing.server.https.keystore.password=OBF:18xp18xr18xt18xp18xr18xt

org.webswing.server.https.keystore.type=PKCS12

 

org.webswing.server.sniRequired=false

webswing.properties

The webswing.properties file contains the following propertiesbefore you update it with your configurations. For information, see Step 3. Configure the webswing.properties to update Websocket.

# secret signing key for JWT tokens, should be at least 128 characters long string

# - change this to a random alphanumeric string in production

# - same secret must be present in admin console's webswing-admin.properties if you are using admin console

webswing.connection.secret = IPxNXVgPraMu5NptTQJe37OLLRN7Nc5vy7Hc12MKde4KX2P7l4ICAnpuHvkvX9StWMoOTx4MprwH65lLwoEEn6fcFhaG8zIY2pnw6gxxTiKMQgHprrI7UJBObkHAjIVy

 

# use this property to provide secret key from a file

#webswing.connection.secret.file = secret.key

# websocket URL of this server, if deployed outside embedded Jetty

#webswing.server.websocketUrl = ws://localhost:8080

 

# Uncomment these following properties when using Webswing only over HTTPS connections

#webswing.server.websocket.truststore.type = PKCS12

#webswing.server.websocket.truststore = ssl/truststore.p12

#webswing.server.websocket.truststore.password = OBF:18xp18xr18xt18xp18xr18xt

# If using a self-signed certificate or accessing the Webswing URL with IP address

# uncomment this and set to true.

#webswing.server.websocket.hostnameVerifier.disabled = true