Checklist: Enabling SSL on Retain

Retain System architecture

We will look at 2 possible RetainServer – RetainWorker scenarios, because this has implications for the connections we need to set, in the Retain webconsole, and also for the certificates (placement).

Either the Retain Server and Retain Worker are on the same server, the Retain Single server scenario, or the Retain Server and the Retain Worker are on different servers, the Retain Separate server scenario.

The rule of thumb that we use is that in both scenarios the actions to enable SSL will be the same, because the RetainServer communicates with the GroupWise Server and with the RetainWorker. The difference will be that in the second scenario, the certificates to use are those of 2 or more servers.

Retain Single server scenario

We are concerned with the connections of Apache server and Tomcat server on one Retain server, and the GroupWise Domain and GroupWise Postoffice, so we’ll need to work with certificates for those. For example when RetainServer and RetainWorker are on one server.

Retain multiple server scenario

We are concerned with the connections of the Apache server and Tomcat server on more than one Retain server, and the GroupWise Domain, GroupWise Postoffice, so we’ll need to work with certificates for those. We then have a primary retain server and remote servers. For example when the RetainServer and one or more RetainWorkers are not on the same server.

For more extensive information on the Retain Architecture, please refer to the Retain Installation and Administration manual.

In the following steps we explain how to resolve this for a Retain / GroupWise / SLES system:

1.  Setting the connections in the Retain webconsole

2.   GroupWise settings and certificates

3.   Create a self-signed or trusted third party certificate

4.  Enable SSL for the Apache server, if not already enabled

5.  Import the GW domain certificate, and the GW domain PO certificate to the Retain java keystore

6.  Import the retain server certificate to the Retain trusted java keystore

7.  Import the tomcat server certificate to the Retain trusted java keystore;
import the tomcat server key and tomcat server certificate to the tomcat java keystore;
and configure the tomcat’s server.xml file

8.  Steps for the Retain multiple server scenario

1. Setting the connections in the Retain webconsole

Log in to the  Retain webconsole and check the following settings.

1.1 Retain Server | Server Configuration

Open the Retain Server | Server Configuration page

Scroll down to the Retain Server Connection, and enter the Retain Server connection details.

 

 

1.2 Retain Server | Module Configuration | GroupWise module

Open the Retain Server | Module Configuration | GroupWise Module page

Scroll down to the GroupWise SOAP Access, and enable SSL

1.3 Retain Server | Workers module

Enter the Retain Server connection details on the Workers | Connection tab.

Enable SSL on the Workers | Module specific tab.

2. Groupwise settings and certificates

2.1 Enabling SOAP

Open the GroupWise admin-console.

Go to the Post Office Agents | Agents Settings, and enable SOAP.

 

 

 2.2 Get the GW certificates

On the RetainServer, change to the /opt/ directory and make the certgw directory.

mkdir certgw

Change to the /opt/certgw/ directory

Import the required groupwise domain and postoffice certificates and keys.

scp -r root@groupwise.your-domain.com:/opt/cert-directory/groupwisedomain /opt/certgw/

3. Create a self-signed or trusted third party certificate

Change to the /opt/ directory and make the certs directory

mkdir certs

Generate self-signed or trusted third-party keys for the Retain server and for the Tomcat server, and name them tomcatserver.key, and retainserver.key

Generate self-signed or trusted third-party certificates and name them tomcatserver.crt, and retainserver.crt

Also refer to the following TID:

https://support.microfocus.com/kb/doc.php?id=7023144

4. Enable SSL for the Apache server

Change to the /etc/apache2/ directory

Copy the retainserver key to the /etc/apache2/ssl.key/ directory.

On the commandline:

cp /opt/beginfinite/certs/retainserver.key ssl.key/

Copy the retainserver certificate to the /etc/apache2/ssl.crt/ directory

cp /opt/beginfinite/certs/retainserver.crt ssl.crt/

Change to the /etc/apache2/vhosts.d directory

In the /etc/apache2/vhosts.d/ directory, create a copy of vhost-ssl.template and name it retainserver-ssl.conf

cp vhost-ssl.template retainserver-ssl.conf

Open the vhost file that was just created and set "SSLCertificateFile" and  "SSLCertificateKeyFile" to the path(s) of  key and signed certificate.

SSLCertificateFile /etc/apache2/ssl.crt/retainserver.crt

SSLCertificateKeyFile /etc/apache2/ssl.key/retainserver.key

Also change the following tag:

<VirtualHost_default_:443> to <VirtualHost *:443>

Add the line

‘SSLProtocol All –SSLv2 –SSLv3’

The retainserver-ssl.conf file will now contain:

Change to the /etc/sysconfig/ directory

Open /etc/sysconfig/apache2.

In the "APACHE_MODULES" option, make sure ‘SSL’ is in the list of modules which Apache needs to load.

Also add ‘-DSSL’ to ‘APACHE_SERVER_FLAGS’

Add the server name of the host.

Optional In order to add configurations for the apache, add ‘/etc/apache2/httpd.conf.local’ to APACHE_CONF_INCLUDE_FILES’

Save and exit the /etc/sysconfig/apache2 file.

Optional Change to the /etc/apache2/ directory.

Create the ‘httpd.conf.local’ file and add the following to the end of the file:

‘# Enter the Servers FQDN, for example your-retainserver.example.com’

‘ServerName your-retainserver.example.com’

‘# Enter the location of the SSL passphrase-file

‘#SSLPassPhraseDialog exec:/etc/httpd/conf/passphrase-file’

As an option, SSLPassPhraseDialog can be used. Uncomment the line with the ‘SSLPassPhraseDialog’to do so.

Change to the /etc/httpd/conf/ directory (or another chosen directory)

Create the passphrase file ‘passphrase’ and enter the following lines:

#!/bin/sh

echo "private key passphrase"

For the passphrase insert the chosen passphrase for the privatekey.

Save the file and make it executable with the command:

chmod +x passphrase-file

Test if the file delivers the passphrase with the following command

./passphrase

Restart apache with the command:

systemctl restart apache2

5. Import Groupwise certificates

Change to the /opt/beginfinite/retain/java/<jdk>/bin/ directory

Import from the command line:

./keytool -importcert -keystore gwkeystore -storepass changeit -noprompt -alias gwdomain -file /opt/beginfinite/certgw/gw-domain.crt

./keytool -importcert -keystore gwkeystore -storepass changeit -noprompt -alias gwdomainpo -file /opt/beginfinite/certgw/gw-domain.po.POA.crt

Viewing the content of the keystore:

./keytool –list –keystore /opt/beginfinite/retain/java/<jdk>/bin/gwkeystore

Note: Please follow relevant password security protocol, and replace the keystore password ‘changeit’.

6. Import Retain certificates

6.1 Import the retain server certificate to the Retain trusted java keystore

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias retaincert -file /opt/certs/retainserver.crt

 To check if the retainserver certificate has been added, type:

./keytool -list -alias retaincert -cacerts

The output should look like:

To remove the retain server certificate from the keystore, use the following:

./keytool -delete -alias retaincert -trustcacerts -keystore /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts

7. Import Tomcat certificates

7.1 Import the tomcat server certificate to the Retain trusted java keystore

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/jdk-11+28/lib/security/cacerts -storepass changeit -noprompt -alias tomcatcert -file /opt/beginfinite/certs/tomcatserver.crt

To check if the tomcatserver certificate has been added, type:

./keytool -list -alias tomcatcert -cacerts

7.2 Import the tomcat server certificate to a tomcat java keystore in the directory

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the command line:

./keytool -importcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore -storepass changeit -noprompt -alias tomcatcert -file /opt/beginfinite/certs/tomcatserver.crt

To check if the tomcatserver certificate has been added, type:

./keytool -list -alias tomcatcert -cacerts

7.3 Configure Tomcat SSL connector in the server.xml file

Change to the /opt/beginfinite/retain/tomcat/conf/ directory

Add the following to the server.xml file:

<Connector port="48443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true" keystoreFile="conf/tomcatkeystore"
keystorePass="changeit" clientAuth="false" sslProtocol="TLS">
</Connector>

Restart the retain-tomcat:

systemctl restart retain-tomcat

8. Steps for the Retain multiple server scenario

8.1 Make certificate directories

On the primary retain server we make new directory, for the certificates of the remote retain worker server.

Change to the /opt/certs/ directory and make the retainworker directory. In this we will store the retain serve and tomcat server keys and certificates from the retainworker server.

Should there be more than one retainworker, you could name the directory for its certificates and keys, retainworker02, etc.

mkdir retainworker

On the remote retainworker we make the certgw and the certs directory

Change to the /opt/ directory and make the certsgw and the certs directory.

mkdir certgw

mkdir certs

Change to the /opt/certs/ directory and make the retain-primary directory. In this we will store the retain server and the tomcat server certificates from the retain server.

mkdir retain-primary

8.2 Create a self-signed or trusted third party certificate for the remote retainworker server

On the retain worker server change to the /opt/ directory and make the certs directory

mkdir certs

Change to the /opt/directory/certs/ directory

Generate self-signed or trusted third-party keys for the Retain worker server and for the Tomcat server, and name them tomcatworker.key, and retainworker.key

Generate self-signed or trusted third-party certificates and name them tomcatworker.crt, and retainworker.crt

8.3 Import the groupwise keys and certificates from the primary retainserver to the remote retainworker

On the remote retainworker server run from the commandline

scp -r root@retain.your-domain.com:/opt/certgw/groupwisedomain /opt/certgw/

8.4 Import the retainserver and tomcatserver keys and certificates from the primary retainserver to the remote retainworker

On the remote retainworker server run from the commandline

scp -r root@retain.your-domain.com:/opt/certs/ /opt/certs/retain-primary/

8.5 Import the retainserver and tomcatserver keys and certificates from the remote retainworker server to the primary retainserver

On the primary retain server run from the commandline

scp -r root@retainworker.your-domain.com:/opt/certs/opt/certs/retainworker/ /opt/certs/retainworker/

 Still on the retainserver, change to the /opt/certs/retainworker/certs directory.

If the retain-primary directory is in there, remove it:

rm -r retain-primary/

8.6 Add certificates to the primary retainserver

8.6.1 Primary Retain trusted java keystore: add- remote retaincertificate and remote tomcatserver cert

On the RetainServer, change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias remretaincert -file /opt/certs/retainworker/retainworker.crt

 To check if the retainserver certificate has been added, type:

./keytool -list -alias remretaincert -cacerts

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias remtomcatcert -file /opt/certs/retainworker/tomcatworker.crt

8.6.2 Primary Tomcatsserver keystore: add remote tomcatserver certificate

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the command line:

./keytool -importcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore -storepass changeit -noprompt -alias remtomcatcert -file /opt/certs/retainworker/tomcatworker.crt

To check if the tomcatserver certificate has been added, type:

./keytool -list -alias remtomcatcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore

8.7 Add certificates to the remote retainworker server

8.7.1 Remote GroupWise keystore: Add GW certificates

Change to the /opt/beginfinite/retain/java/<jdk>/bin/ directory

Import from the command line:

./keytool -importcert -keystore gwkeystore -storepass changeit -noprompt -alias gwdomain -file /opt/certgw/gw-domain.crt

./keytool -importcert -keystore gwkeystore -storepass changeit -noprompt -alias gwdomainpo -file /opt/certgw/gw-domain.po.POA.crt

To view the content of the keystore, type:

./keytool –list –keystore /opt/beginfinite/retain/java/<jdk>/bin/gwkeystore

8.7.2 Remote Retain trusted java keystore: add- remote retaincertificate and remote tomcatserver cert

On the Remote Retain Server, change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias retainworkcert -file /opt/certs/retainworker.crt

 To check if the (remote) retainserver certificate has been added, type:

./keytool -list -alias retainworkcert -cacerts

 Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias tomcatworkcert -file /opt/certs/tomcatworker.crt

 To check if the (remote) tomcatserver certificate has been added, type:

./keytool -list -alias tomcatworkcert -cacerts

8.7.3 Remote Tomcatserver keystore: add remote tomcatserver certificate

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the command line:

./keytool -importcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore -storepass changeit -noprompt -alias tomcatworkcert -file /opt/certs/tomcatworker.crt

 To check if the (remote)tomcatserver certificate has been added, type:

./keytool -list -alias tomcatworkcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore

8.7.4 Configure Tomcat SSL connector in the server.xml file

Change to the /opt/beginfinite/retain/tomcat/conf/ directory

Add the following to the server.xml file:

<Connector port="48443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true" keystoreFile="conf/tomcatkeystore"
keystorePass="changeit" clientAuth="false" sslProtocol="TLS">
</Connector>

8.7.5 Remote Retain trusted java keystore: add- primary retain certificate and primary tomcatserver certificate

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias primretaincert -file /opt/certs/retain-primary/certs/retainserver.crt

 To check if the (remote) retainserver certificate has been added, type:

./keytool -list -alias primretaincert -cacerts

 Import from the commandline:

./keytool -import -trustcacerts -keystore  /opt/beginfinite/retain/java/<jdk>/lib/security/cacerts -storepass changeit -noprompt -alias primtomcatcert -file /opt/certs/retain-primary/certs/tomcatserver.crt

 To check if the (remote) tomcatserver certificate has been added, type:

./keytool -list -alias primtomcatcert -cacerts

8.7.6 Remote Tomcatserver keystore: add primary tomcatserver certificate

Change to the /opt/beginfinite/retain/java/<jdk>/bin directory

Import from the command line:

./keytool -importcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore -storepass changeit -noprompt -alias primtomcatcert -file /opt/certs/retain-primary/certs/tomcatserver.crt

 To check if the (remote)tomcatserver certificate has been added, type:

./keytool -list -alias primtomcatcert -keystore /opt/beginfinite/retain/tomcat/conf/tomcatkeystore

Restart the retain-tomcat on the remote server:

systemctl restart retain-tomcat

Changes in the Retain application modules

Keywords

Retain; SLES; SSL; Apache; Tomcat; PKIX