Difference between revisions of "SSL Configuration using Java Keystore"

From LogicalDOC Community Wiki
Jump to navigationJump to search
m (SSL Configuration)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
==SSL Configuration==
 
  
 
LogicalDOC embeds the Tomcat application server and it can be configured to support the encrypted protocol HTTPS. This is useful when you want to expose the program on the Internet.
 
LogicalDOC embeds the Tomcat application server and it can be configured to support the encrypted protocol HTTPS. This is useful when you want to expose the program on the Internet.
Basically you only have to follows the steps described in the Apache how-to at [https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html "SSL Configuration HOW-TO"]
 
  
 +
{{Advice|<b><u>Please be aware that this procedure is not coverded by the standard support contract</u>.</b> <br/>In case you want this matter to be handled professionally, please write to sales@logicaldoc.com for a quote.}}
 +
 +
Basically you only have to follows the steps described in the Apache how-to at [https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html SSL Configuration HOW-TO]
 
What follows is a re-visioned extract from that how-to
 
What follows is a re-visioned extract from that how-to
  
Line 27: Line 28:
 
Windows:<br/>
 
Windows:<br/>
 
     %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
 
     %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
       -keystore \path\to\my\keystore
+
       -keystore <LDOC_HOME>\conf\keystore
 
<br/>
 
<br/>
 
Unix:<br/>
 
Unix:<br/>
 
     $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
 
     $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
       -keystore /path/to/my/keystore
+
       -keystore <LDOC_HOME>/conf/keystore
 +
 
 +
<small>replace <LDOC_HOME> with the installation path of LogicalDOC</small>
  
 
After executing this command, you will first be prompted for the keystore password. The default password used by Tomcat is "changeit" (all lower case), although you can specify a custom password if you like. You will also need to specify the custom password in the server.xml configuration file, as described later.
 
After executing this command, you will first be prompted for the keystore password. The default password used by Tomcat is "changeit" (all lower case), although you can specify a custom password if you like. You will also need to specify the custom password in the server.xml configuration file, as described later.
Line 42: Line 45:
  
 
==Edit the Tomcat configuration file==     
 
==Edit the Tomcat configuration file==     
The final step is to configure your secure socket in the $CATALINA_BASE/conf/server.xml file, where $CATALINA_BASE represents the base directory for the Tomcat 6 instance. An example <Connector> element for an SSL connector is included in the default server.xml file installed with Tomcat. It will look something like this:
+
The final step is to configure your secure socket in the <LDOC_HOME>/tomcat/conf/server.xml file, where <LDOC_HOME> represents the base directory for the LogicalDOC installation. An example <Connector> element for an SSL connector looks something like this:
  
    <-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
+
     <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
     <Connector  
+
               port="8443" maxThreads="200"
              port="8443" minSpareThreads="5" maxSpareThreads="75"
 
               enableLookups="true" disableUploadTimeout="true"
 
              acceptCount="100" maxThreads="200"
 
 
               scheme="https" secure="true" SSLEnabled="true"
 
               scheme="https" secure="true" SSLEnabled="true"
               keystoreFile="${user.home}/.keystore" keystorePass="changeit"
+
               keystoreFile="<LDOC_HOME>/conf/keystore"
              clientAuth="false" sslProtocol="TLS"/>
+
              keystorePass="changeit" clientAuth="false" sslProtocol="TLS"
 +
              URIEncoding="UTF-8" server="Undisclosed/8.41" />
 
    
 
    
You will note that the Connector element itself is commented out by default, so you will need to remove the comment tags around it. Then, you can customize the specified attributes as necessary.
+
<small>replace <LDOC_HOME> with the installation path of LogicalDOC</small>
 +
 
 +
{{Advice|LogicalDOC application will be updated from time to time so it is not safe to maintain the keystore inside the tomcat/ folder, please put your keystore inside the conf/ folder of the LogicalDOC installation path.}}
  
 
The port attribute (default value is 8443) is the TCP/IP port number on which Tomcat will listen for secure connections. You can change this to any port number you wish.
 
The port attribute (default value is 8443) is the TCP/IP port number on which Tomcat will listen for secure connections. You can change this to any port number you wish.
  
If you change the port number here, you should also change the value specified for the redirectPort attribute on the non-SSL connector. This allows Tomcat to automatically redirect users who attempt to access a page with a security constraint specifying that SSL is required, as required by the Servlet 2.4 Specification.
+
If you change the port number here, you should also change the value specified for the redirectPort attribute on the non-SSL connector. This allows Tomcat to automatically redirect users who attempt to access a page with a security constraint specifying that SSL is required.
  
After completing these configuration changes, you must restart Tomcat as you normally do, and you should be in business. You should be able to access LogicalDOC via SSL. For example, try:
+
After completing these configuration changes, you must restart LogicalDOC as you normally do, you should be able to access via SSL. For example, try:
  
 
     https://localhost:8443
 
     https://localhost:8443

Latest revision as of 14:36, 9 April 2020

LogicalDOC embeds the Tomcat application server and it can be configured to support the encrypted protocol HTTPS. This is useful when you want to expose the program on the Internet.


Note idea.png Please be aware that this procedure is not coverded by the standard support contract.
In case you want this matter to be handled professionally, please write to sales@logicaldoc.com for a quote.


Basically you only have to follows the steps described in the Apache how-to at SSL Configuration HOW-TO What follows is a re-visioned extract from that how-to

Prepare the certificate Keystore

To install and configure SSL support on Tomcat, you need a keystore that is a file containing one or more certificates Tomcat currently operates on JKS format keystores. The JKS format is Java's standard "Java KeyStore" format, and is the format created by the keytool command-line utility. This tool is included in the JDK.

Each entry in a keystore is identified by an alias string. To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package) about keytool.

To create a new keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal command line:

Windows:

   %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA


Unix:

   $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA


(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other servers and components.)

This command will create a new file, in the home directory of the user under which you run it, named ".keystore". To specify a different location or filename, add the -keystore parameter, followed by the complete pathname to your keystore file, to the keytool command shown above. You will also need to reflect this new location in the server.xml configuration file, as described later. For example:

Windows:

   %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
     -keystore <LDOC_HOME>\conf\keystore


Unix:

   $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
     -keystore <LDOC_HOME>/conf/keystore

replace <LDOC_HOME> with the installation path of LogicalDOC

After executing this command, you will first be prompted for the keystore password. The default password used by Tomcat is "changeit" (all lower case), although you can specify a custom password if you like. You will also need to specify the custom password in the server.xml configuration file, as described later.

Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on. This information will be displayed to users who attempt to access a secure page in your application, so make sure that the information provided here matches what they will expect.

Finally, you will be prompted for the key password, which is the password specifically for this Certificate (as opposed to any other Certificates stored in the same keystore file). You MUST use the same password here as was used for the keystore password itself. (Currently, the keytool prompt will tell you that pressing the ENTER key does this for you automatically.)

If everything was successful, you now have a keystore file with a Certificate that can be used by your server.

Edit the Tomcat configuration file

The final step is to configure your secure socket in the <LDOC_HOME>/tomcat/conf/server.xml file, where <LDOC_HOME> represents the base directory for the LogicalDOC installation. An example <Connector> element for an SSL connector looks something like this:

   <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
              port="8443" maxThreads="200"
              scheme="https" secure="true" SSLEnabled="true"
              keystoreFile="<LDOC_HOME>/conf/keystore"
              keystorePass="changeit" clientAuth="false" sslProtocol="TLS"
              URIEncoding="UTF-8" server="Undisclosed/8.41" />
   		

replace <LDOC_HOME> with the installation path of LogicalDOC


Note idea.png LogicalDOC application will be updated from time to time so it is not safe to maintain the keystore inside the tomcat/ folder, please put your keystore inside the conf/ folder of the LogicalDOC installation path.


The port attribute (default value is 8443) is the TCP/IP port number on which Tomcat will listen for secure connections. You can change this to any port number you wish.

If you change the port number here, you should also change the value specified for the redirectPort attribute on the non-SSL connector. This allows Tomcat to automatically redirect users who attempt to access a page with a security constraint specifying that SSL is required.

After completing these configuration changes, you must restart LogicalDOC as you normally do, you should be able to access via SSL. For example, try:

   https://localhost:8443

and you should see the usual login page.

Importing a certificate

Please note that each certificate issuer is different and the procedure to install their certificates in Tomcat may be differ.

It is responsibility fo your certificate issuer to provide you with a tutorial on installing the certificate in Tomcat. So refer to your certificate issuer for getting help.

For your convenience, here below is a list of How-Tos from different issuers:


In general, if you have your Certificate you can import it into you local keystore. First of all you have to import a so called Chain Certificate or Root Certificate into your keystore. After that you can proceed with importing your Certificate.

  • Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.
 For Entrust commercial certificates go to: http://www.entrust.net
 For Verisign commercial certificates go to: http://www.verisign.com/support/install/intermediate.html
 For Thawte go to: http://www.thawte.com/certs/trustmap.html
 For GoDaddy go to: https://www.godaddy.com/help/tomcat-generate-csrs-and-install-certificates-5239
  • Import the Chain Certificate into your keystore
         keytool -import -alias root -keystore <your_keystore_filename> \
         	-trustcacerts -file <filename_of_the_chain_certificate>
  • And finally import your new Certificate
         keytool -import -alias tomcat -keystore <your_keystore_filename> \
         	-file <your_certificate_filename>