Enabling SSL for Innoslate

Configure SSL for Innoslate on Apache Tomcat

• Option A: Create a self-signed certificate (suitable for internal/test environments).
• Option B: Use a certificate issued by a Certificate Authority (CA) for production.

Prerequisites

• Apache Tomcat installed (e.g., C:\Innoslate4\apache-tomcat on Windows or /opt/innoslate4/apache-tomcat on Linux/macOS).
• Java JDK installed (includes keytool utility, e.g., C:\Program Files\Java\jdk-17\bin\keytool.exe on Windows).
• Basic knowledge of command-line usage.
• If changing the domain name, ensure it matches the certificate’s Common Name (CN) or Subject Alternative Name (SAN) before proceeding.
• Port 8443 (or 443 for production) open in your firewall.

Note: Verify your Java version (java -version) and Tomcat version (e.g., 9) for compatibility with Innoslate and modern TLS protocols (TLS 1.2/1.3).

Option A: Use a Self-Signed Certificate

Step 1A: Generate a Self-Signed Certificate

Use the keytool utility to create a self-signed certificate:

"<jdk-path>/keytool.exe" -genkeypair -alias tomcatssl -keyalg RSA -keysize 2048 -keystore keystore.jks -validity 3650

• Replace <jdk-path> with your JDK’s bin directory (e.g., C:\Program Files\Java\jdk-17\bin on Windows or /usr/lib/jvm/jdk-17/bin on Linux/macOS).
• For Linux/macOS, omit .exe (e.g., /usr/lib/jvm/jdk-17/bin/keytool).
• When prompted:
  • Enter your domain name (e.g., yourdomain.com) as the Common Name (CN) to avoid browser warnings.
  • Provide organization details and a keystore password (record this password).
  • Press Enter at the key password prompt to reuse the keystore password.

This creates keystore.jks in the current directory, valid for 10 years.

Option B: Use a CA-Issued Certificate

Step 1B-1: Generate a Keystore and CSR

1. Create a keystore with a key pair (if not already done):

"<jdk-path>/keytool.exe" -genkeypair -alias tomcatssl -keyalg RSA -keysize 2048 -keystore keystore.jks -validity 3650

• Use the same <jdk-path> as above.
• Enter your domain name as the CN and a keystore password.

1. Generate a Certificate Signing Request (CSR):

"<jdk-path>/keytool.exe" -certreq -alias tomcatssl -file certreq.csr -keystore keystore.jks

• Enter the keystore password when prompted.
• This creates certreq.csr. Submit it to your CA (e.g., DigiCert, GoDaddy, Let’s Encrypt).

Note: For Let’s Encrypt, use tools like Certbot to automate CSR generation and certificate issuance.

Step 1B-2: Import the CA-Issued Certificate

Once the CA provides your signed certificate (e.g., yourdomain.crt) and any root/intermediate certificates (e.g., root_ca.crt, intermediate_ca.crt), import them:

"<jdk-path>/keytool.exe" -import -trustcacerts -alias root -file root_ca.crt -keystore keystore.jks
"<jdk-path>/keytool.exe" -import -trustcacerts -alias intermediate -file intermediate_ca.crt -keystore keystore.jks
"<jdk-path>/keytool.exe" -import -trustcacerts -alias tomcatssl -file yourdomain.crt -keystore keystore.jks

• Enter the keystore password for each command.
• Import certificates in order: root, intermediate(s), then your signed certificate.
• Check your CA’s documentation for specific files and import order. Some CAs provide a single chain file.

Common Steps: Apply SSL to Apache Tomcat

Step 2: Move the Keystore File

Move keystore.jks to the Tomcat configuration directory:

• Windows: C:\Innoslate4\apache-tomcat\conf\
• Linux/macOS: /opt/innoslate4/apache-tomcat/conf/

Step 3: Configure server.xml for SSL

Edit server.xml in the Tomcat configuration directory (e.g., C:\Innoslate4\apache-tomcat\conf\server.xml).

Add or modify the HTTPS connector for port 8443 (or 443 for production):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
           clientAuth="false" sslEnabledProtocols="TLSv1.2,TLSv1.3"
           keystoreFile="C:\Innoslate4\apache-tomcat\conf\keystore.jks"
           keystorePass="your_keystore_password"
           keyAlias="tomcatssl" />

• Replace your_keystore_password with the password set in Step 1A or 1B-1.
• For Linux/macOS, update the keystoreFile path (e.g., /opt/innoslate4/apache-tomcat/conf/keystore.jks).
• Adjust maxThreads based on your server’s capacity (e.g., 200–500 for production).
• For production, consider using port 443 (requires root privileges on Linux/macOS or additional Windows configuration).

Step 4: Disable or Redirect HTTP (Optional but Recommended)

To enforce HTTPS, configure Tomcat to redirect HTTP traffic:

1. Comment out the HTTP Connector:

In server.xml, locate the default HTTP connector (port 8080) and comment it out to disable non-SSL access:

<!--
<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />
-->

• If you keep the HTTP connector active, ensure redirectPort="8443" matches your HTTPS port.

1. Enforce HTTPS in web.xml:

Edit web.xml in the Tomcat configuration directory (e.g., C:\Innoslate4\apache-tomcat\conf\web.xml). Add the following before </web-app>:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Entire Application</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>

• Note: This applies to all applications on the Tomcat instance. For Innoslate only, add this to C:\Innoslate4\apache-tomcat\webapps\innoslate\WEB-INF\web.xml.
• Back up web.xml before editing.

Final Step: Restart Tomcat and Verify

1. Restart Tomcat:

   1.  C:\Innoslate4\apache-tomcat\bin\startup.bat.

1. Verify HTTPS:

   • Access Innoslate at https://yourdomain.com:8443.
   • For self-signed certificates (Option A), expect browser warnings; add an exception for testing or import the certificate to your client’s trusted store.
   • Check Tomcat logs (e.g., C:\Innoslate4\apache-tomcat\logs\catalina.<date>.log) for errors if HTTPS fails.

2. Troubleshooting:

   • Ensure port 8443 is open in your firewall (e.g., netsh advfirewall on Windows, ufw on Linux).
   • Verify the CN in the certificate matches your domain.