white paper - distributed content ssl configuration and ... · distributed content ssl...

35
White Paper Abstract This white paper explains the configuration of Distributed Content (ACS, BOCS and DMS) in SSL mode and monitors the logs for content transfer operations. This guide describes the end-to-end SSL configuration steps for each component ACS, BOCS, DMS and WDK-based client level and troubleshooting tips as well. February 2013 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Upload: haliem

Post on 24-Jun-2018

234 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

White Paper

Abstract

This white paper explains the configuration of Distributed Content (ACS, BOCS and DMS) in SSL mode and monitors the logs for content transfer operations. This guide describes the end-to-end SSL configuration steps for each component ACS, BOCS, DMS and WDK-based client level and troubleshooting tips as well. February 2013

DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Page 2: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

2 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Copyright © 2013 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate of its publication date. The information is subject to change without notice. The information in this publication is provided “as is”. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. VMware is a registered trademark of VMware, Inc. All other trademarks used herein are the property of their respective owners. Part Number H11452

Page 3: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

3 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Table of Contents

Executive summary.................................................................................................. 4 Audience ............................................................................................................................ 4 Abbreviation ....................................................................................................................... 4

Distributed Content SSL Configuration ..................................................................... 4 Secure Socket Layer ........................................................................................................... 4 ACS Configuration In SSL Mode .......................................................................................... 5 BOCS Configuration In SSL Mode ........................................................................................ 7 DMS Configuration In SSL Mode ......................................................................................... 9 WDK-based Client Configuration In SSL Mode ................................................................... 11 Other Required Configuration ........................................................................................... 13 Verify SSL Configuration ................................................................................................... 18

Monitor Logs During Content Transfer over SSL....................................................... 19 ACS read request .............................................................................................................. 19 ACS write request ............................................................................................................. 20 BOCS read request ........................................................................................................... 22 BOCS write synchronous request ...................................................................................... 24 Asynchronous write request ............................................................................................. 27 Predictive Caching request ............................................................................................... 31

Useful Points ......................................................................................................... 33

Troubleshooting Tips ............................................................................................. 34

Conclusion ............................................................................................................ 35

References ............................................................................................................ 35

Page 4: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

4 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Executive summary This white paper covers the following points for Distributed Content configuration to support SSL –

• ACS, BOCS and DMS configuration in SSL mode. • WDK-based Client configuration in SSL mode. • Monitor UCF client, WDK and BOCS logs during content transfer for each read and

write request. • Troubleshooting.

Audience

This white paper is intended for developers and testers who needs to configure the Distributed Content in SSL environment. This paper will help reader to understand the ACS, BOCS, DMS configuration to support SSL and to monitor the HTTPS URLs during content transfer operations. It assumes that the reader possess the knowledge of Content Server, DA and Distributed content (ACS, BOCS and DMS) functionality.

Abbreviation

Special terms, abbreviations and acronyms that may appear in this guide are defined below.

1. CS Content Server 2. ACS Accelerated Content Server 3. BOCS Branch Office Caching Server 4. DMS Documentum Messaging Server 5. GR Global Repository 6. SSL Secure Socket Layer 7. DC Distributed Content 8. DFC Documentum Foundation Classes 9. DA Documentum Administrator 10. WDK Web Development Kit

Distributed Content SSL Configuration

Secure Socket Layer Secure Socket Layer is a protocol designed to enable applications to

transmit information back and forth between client and server securely. SSL uses a cryptographic system that uses two keys to encrypt/decrypt data − a public key known to everyone and a private or secret key known only to the recipient of the message. A public key can be used to encrypt the message and a corresponding private key can be used to decrypt them.

Page 5: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

5 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Documentum release 7.0 onwards, all components ACS, BOCS, DMS have the java certified with FIPS compliance as bundled with documentum. User may use the documentum bundled java or any external java to create the keystores and import the certificates. With regard to SSL, another particular change in documentum 7.0 is “Ciphers” attribute with limiting the size 128 have been added in server.xml for JBOSS application server to restrict the key size 128 bits to be used by java.

If user wants to use this guide for pre Documentum 7.0 release, then they do not need to worry about “ciphers” attribute to add in JBOSS config file server.xml. They may ignore the “ciphers” setting in server.xml for SSL configuration.

ACS Configuration In SSL Mode To configure ACS in SSL mode –

1. Create a keystore for JBOSS application server by executing the below command through command line. It can be created by using the java keytool utlity.

From <Java_home>\bin-

keytool.exe -genkey -alias acskey -keyalg RSA -keystore acs.keystore

(Here, alias name is ‘acskey’ and keystore name is ‘acs.keystore’. User can choose anything for these names.)

Note: Keystore can be created from any java like Documentum bundled java (<Documentum>/ java64) or any external java.

2. This command will prompt for some details mentioned below. Type the full hostname of the ACS server machine for common name (first and last name). Give other details accordingly.

Enter keystore password:

Re-enter new password:

What is your first and last name?

[Unknown]: acsmachine.dnsname.com

What is the name of your organizational unit?

[Unknown]: emc

What is the name of your organization?

[Unknown]: emc

What is the name of your City or Locality?

[Unknown]: Pleasanton

What is the name of your State or Province?

[Unknown]: CA

Page 6: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

6 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

What is the two-letter country code for this unit?

[Unknown]: US

Is CN= acsmachine.dnsname.com, OU=emc, O=emc, L=Pleasanton, ST=CA, C=US correct?

[no]: yes

Enter key password for <acskey>

(RETURN if same as keystore password):

3. Modify server.xml in JBOSS to enable SSL and server to use HTTPS protocol.

Uncomment the below lines in <JBOSS_HOME>\server\DctmServer_MethodServer\deploy\jbossweb.sar\server.xml

<Connector protocol="HTTP/1.1" SSLEnabled="true"

port="8443" address="${jboss.bind.address}"

scheme="https" secure="true" clientAuth="false"

keystoreFile="${jboss.server.home.dir}/conf/acs.keystore"

keystorePass="password" sslProtocol = "TLS"

ciphers="TLS_RSA_WITH_AES_128_CBC_SHA"/>

Give the path for acs.keystore file created in step2 for ‘keystoreFile’ attribute. Give the keystore password for ‘keystorePass’ attribute which is set in step2 during keystore creation.

HTTPS Port (9082) is referred from ‘bindings-jboss-beans.xml’ file. User can change the port value. “<JBOSS_HOME>\server\DctmServer_MethodServer\conf\bindingservice.beans\META-INF\bindings-jboss-beans.xml”

4. Restart ACS.

5. Access ACS url with https protocol and 9082 port.

https://<acsmachine.dnsname.com>:9082/ACS/servlet/ACS

6. Generate the acs certificate by exporting acs.keystore. Use the below command through command line.

From <java_home>/bin

keytool.exe -export -alias acskey -file acs.cer -keystore acs.keystore

7. Import acs certificate (exported in step6) into each running java in ACS and BOCS machines by using the below command through command line.

Page 7: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

7 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

keytool.exe -import -noprompt -trustcacerts -alias acscert -file "C:\certificate\acs.cer" -keystore "<java>/jre/lib/security/cacerts"

In ACS machine, import this certificate into documentum bundled java (<Documentum>\java64, <Documentum>\java) and any other external java if that is running.

In BOCS machine, import this certificate into documentum bundled java (<Documentum>\java64, <C:\ProgramFiles\Documentum>\java) and any other external java if that is running.

It will prompt for keystore password. Give the default password for java truststore ‘cacerts’ that is ‘changeit’.

BOCS Configuration In SSL Mode To configure BOCS in SSL mode –

1. Create a keystore for JBOSS application server by executing the below command through command line. It can be created by using the java keytool utlity.

From <Java_home>\bin-

keytool.exe -genkey -alias bocskey -keyalg RSA -keystore bocs.keystore

(Here, alias name is ‘bocskey’ and keystore name is ‘bocs.keystore’. User can choose anything for these names.)

Note: Keystore can be created from any java like Documentum bundled java (<Documentum>/ java64) or any external java.

2. This command will prompt for some details mentioned below. Type the full hostname of the BOCS server machine for common name (first and last name). Give other details accordingly.

Enter keystore password:

Re-enter new password:

What is your first and last name?

[Unknown]: bocsmachine.dnsname.com

What is the name of your organizational unit?

[Unknown]: emc

What is the name of your organization?

[Unknown]: emc

What is the name of your City or Locality?

[Unknown]: Pleasanton

What is the name of your State or Province?

Page 8: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

8 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

[Unknown]: CA

What is the two-letter country code for this unit?

[Unknown]: US

Is CN= bocsmachine.dnsname.com, OU=emc, O=emc, L=Pleasanton, ST=CA, C=US correct?

[no]: yes

Enter key password for <bocskey>

(RETURN if same as keystore password):

3. Modify server.xml in JBOSS to enable SSL and server to use HTTPS protocol.

Uncomment the below lines in <JBOSS_HOME>\server\ DctmServer_BOCS \deploy\jbossweb.sar\server.xml

<Connector protocol="HTTP/1.1" SSLEnabled="true"

port="8443" address="${jboss.bind.address}"

scheme="https" secure="true" clientAuth="false"

keystoreFile="${jboss.server.home.dir}/conf/bocs.keystore"

keystorePass="password" sslProtocol = "TLS"

ciphers="TLS_RSA_WITH_AES_128_CBC_SHA"/>

Give the path for bocs.keystore file created in step2 for ‘keystoreFile’ attribute. Give the keystore password for ‘keystorePass’ attribute which is set in step2 during keystore creation.

HTTPS Port (8088) is referred from ‘bindings-jboss-beans.xml’ file. User can change the port value. “<JBOSS_HOME>\server\DctmServer_BOCS\conf\bindingservice.beans\META-INF\bindings-jboss-beans.xml”

4. Restart BOCS.

5. Access BOCS url with https protocol and 8088 port.

https://<bocsmachine.dnsname.com>:8088/bocs/servlet/ACS

6. Generate the bocs certificate by exporting bocs.keystore. Use the below command through command line.

From <java_home>/bin

Keytool.exe -export -alias bocskey -file bocs.cer -keystore bocs.keystore

7. Import bocs certificate (exported in step6) into each running java in BOCS and DMS machines by using the below command through command line.

Page 9: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

9 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

keytool.exe -import -noprompt -trustcacerts -alias bocscert -file "C:\certificate\bocs.cer" -keystore "<java>/jre/lib/security/cacerts"

In BOCS machine, import this certificate into documentum bundled java (<Documentum>\java64, <C:\ProgramFiles\Documentum>\java) and any other external java if that is running.

In DMS machine, import this certificate into documentum bundled java (<Documentum>\java64, <Documentum>\java) and any other external java if that is running.

It will prompt for keystore password. Give the default password for java truststore ‘cacerts’ that is ‘changeit’.

DMS Configuration In SSL Mode To configure DMS in SSL mode –

1. Create a keystore for JBOSS application server by executing the below command through command line. It can be created by using the java keytool utlity.

From <Java_home>\bin-

keytool.exe -genkey -alias dmskey -keyalg RSA -keystore dms.keystore

(Here, alias name is ‘dmskey’ and keystore name is ‘dms.keystore’. User can choose anything for these names.)

Note: Keystore can be created from any java like Documentum bundled java (<Documentum>/ java64) or any external java.

2. This command will prompt for some details mentioned below. Type the full hostname of the DMS server machine for common name (first and last name). Give other details accordingly.

Enter keystore password:

Re-enter new password:

What is your first and last name?

[Unknown]: dmsmachine.dnsname.com

What is the name of your organizational unit?

[Unknown]: emc

What is the name of your organization?

[Unknown]: emc

What is the name of your City or Locality?

[Unknown]: Pleasanton

What is the name of your State or Province?

Page 10: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

10 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

[Unknown]: CA

What is the two-letter country code for this unit?

[Unknown]: US

Is CN= dmsmachine.dnsname.com, OU=emc, O=emc, L=Pleasanton, ST=CA, C=US correct?

[no]: yes

Enter key password for <dmskey>

(RETURN if same as keystore password):

3. Modify server.xml in JBOSS to enable SSL and server to use HTTPS protocol.

Uncomment the below lines in <JBOSS_HOME>\ server\DctmServer_DMS\deploy\jbossweb.sar\server.xml

<Connector protocol="HTTP/1.1" SSLEnabled="true"

port="8443" address="${jboss.bind.address}"

scheme="https" secure="true" clientAuth="false"

keystoreFile="${jboss.server.home.dir}/conf/dms.keystore"

keystorePass="password" sslProtocol = "TLS"

ciphers="TLS_RSA_WITH_AES_128_CBC_SHA"/>

Give the path for dms.keystore file created in step2 for ‘keystoreFile’ attribute. Give the keystore password for ‘keystorePass’ attribute which is set in step2 during keystore creation.

HTTPS Port (8491) is referred from ‘bindings-jboss-beans.xml’ file. User can change the port value. “<JBOSS_HOME>\server\DctmServer_DMS\conf\bindingservice.beans\META-INF\bindings-jboss-beans.xml”

4. Restart DMS.

5. Access DMS url with https protocol and 8491 port.

https://<dmsmachine.dnsname.com>:8491/dms-ws

6. Generate the dms certificate by exporting dms.keystore. Use the below command through command line.

From <java_home>/bin

Keytool.exe -export -alias dmskey -file dms.cer -keystore dms.keystore

7. Import dms certificate (exported in step6) into each running java in BOCS, DMS and WDK client machines by using the below command through command line.

Page 11: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

11 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

keytool.exe -import -noprompt -trustcacerts -alias dmscert -file "C:\certificate\dms.cer" -keystore "<java>/jre/lib/security/cacerts"

In BOCS machine, import this certificate into documentum bundled java (<Documentum>\java64, <C:\ProgramFiles\Documentum>\java) and any other external java if that is running.

In DMS machine, import this certificate into documentum bundled java (<Documentum>\java64, <Documentum>\java) and any other external java if that is running.

In WDK client machine, import this certificate in that java where client application is running.

It will prompt for keystore password. Give the default password for java truststore ‘cacerts’ that is ‘changeit’.

WDK-based Client Configuration In SSL Mode To configure WDK Client application server in SSL mode –

(User should have the WDK client application deployed on supported application server.)

1. Create a keystore for application server by executing the below command through command line. It can be created by using the java keytool utlity.

From <Java_home>\bin-

keytool.exe -genkey -alias wdkkey -keyalg RSA -keystore wdk.keystore

(Here, alias name is ‘wdkkey’ and keystore name is ‘wdk.keystore’. User can choose anything for these names.)

2. This command will prompt for some details mentioned below. Type the full hostname of the WDK client machine for common name (first and last name). Give other details accordingly.

Enter keystore password:

Re-enter new password:

What is your first and last name?

[Unknown]: wdkmachine.dnsname.com

What is the name of your organizational unit?

[Unknown]: emc

What is the name of your organization?

[Unknown]: emc

What is the name of your City or Locality?

[Unknown]: Pleasanton

Page 12: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

12 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

What is the name of your State or Province?

[Unknown]: CA

What is the two-letter country code for this unit?

[Unknown]: US

Is CN= wdkmachine.dnsname.com, OU=emc, O=emc, L=Pleasanton, ST=CA, C=US correct?

[no]: yes

Enter key password for <wdkkey>

(RETURN if same as keystore password):

3. Modify server.xml in application server to enable SSL and server to use HTTPS protocol. Check for the ‘SSL’ configuration lines in server.xml, uncomment them and provide the appropriate details for keystore file path, password, port etc.

Example, for tomcat, uncomment the below lines in <app_server_home>/conf/server.xml

<Connector protocol="HTTP/1.1" port="8443" maxThreads="200" scheme="https" secure="true" SSLEnabled="true" keystoreFile="${user.home}/wdk.keystore" keystorePass="password" clientAuth="false" sslProtocol="TLS"/>

4. Restart the application server.

5. Access WDK-based client application url with https protocol and 8443 port (that is a default port, it may be changed).

https://<wdkmachine.dnsname.com>:8443/<wdk-client-app-name>

Example, for DA client, it will be like:

https://< wdkmachine.dnsname.com>:8443/da

6. Generate the WDK-based client certificate by exporting wdk.keystore. Use the below command through command line.

From <java_home>/bin

keytool.exe -export -alias wdkkey -file wdk.cer -keystore wdk.keystore

7. In WDK client machine, import this certificate (exported in step 6) in that java where WDK application is running.

keytool.exe -import -noprompt -trustcacerts -alias wdkcert -file "C:\certificate\wdk.cer" -keystore "<java>/jre/lib/security/cacerts"

It will prompt for keystore password. Give the default password for java truststore ‘cacerts’ that is ‘changeit’.

Page 13: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

13 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Other Required Configuration Below configuration steps (1 -3) can be done through iapi by accessing ACS, BOCS and DMS config objects or through DA as well.

1. Through iapi :

Access the ACS server config object through iapi and modify the ACS base url and supported protocol. Provide the below url as ‘acs_base_url’ and https protocol as ‘acs_supported_protocol’.

acs_base_url – https://<acsmachine.dnsname.com>:9082/ACS/servlet/ACS

acs_supported_protocol – https

Or

Through DA:

Go to Distributed Content Configuration-> ACS Servers-> Select the ACS server-> right click-> properties-> click on base url-> click on edit

Modify the protocol to ‘https’ and base url to ‘https://<acsmachine.dnsname.com>:9082/ACS/servlet/ACS

Click ok.

Page 14: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

14 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

2. Through iapi :

Access the BOCS server config object through iapi and modify the BOCS base url and supported protocol. Provide the below url as ‘base_url’ and https protocol as ‘supported_protocol’.

base_url – https://<bocsmachine.dnsname.com>:8088/bocs/servlet/ACS

supported_protocol – https

Or

Through DA:

Go to Distributed Content Configuration-> BOCS Servers-> Select the BOCS server-> right click-> properties-> click on base url-> click on edit

Page 15: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

15 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Modify the protocol to ‘https’ and base url to ‘https://<bocsmachine.dnsname.com>:8088/bocs/servlet/ACS

Click ok.

Page 16: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

16 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

3. Through iapi :

Access the DMS server config object through iapi and modify the post url and consume url. Provide the below url as ‘message_post_url’ and as ‘message_consume_url’.

https://<dmsmachine.dnsname.com>:8491

Or

Through DA:

Go to Distributed Content Configuration-> Messaging Server-> Select the DMS server-> right click-> properties

Modify the ‘Post URL’ and ‘Consume URL’ to https://<dmsmachine.dnsname.com>:8491

Page 17: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

17 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

4. Modify the ‘dms.webservice.update.url’ parameter value in dms.properties file.

In DMS machine <Documentum>\jboss5.1.0\server\DctmServer_DMS\deploy\DMS.ear\lib\configs.jar\dms.properties

Modify the value of ‘dms.webservice.update.url’ to ‘https://<dmsmachine.dnsname.com>:8491

5. For BOCS pull mode, modify the acs.properties file in BOCS machine.

<Documentum>\jboss5.1.0\server\DctmServer_BOCS\deploy\bocs.ear\lib\configs.jar\config\acs.properties

Modify ‘dms.pulling.url’ and ‘dms.server.base.urls’ parameters’ values.

dms.pulling.url = https://<dmsmachine.dnsname.com>:8491

dms.server.base.urls =

https://<dmsmachine.dnsname.com>:8491

6. While content transfer, a separate JRE will be installed with UCF client if this JRE version is higher than the existing JRE in machine. All certificates except DMS (ACS, BOCS and WDK

Page 18: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

18 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

client) needs to be import in UCF’s JRE and browser’s java (where WDK application url is being accessed). Default location for UCF client JRE is: <User-directory>\Documentum\ucf\<machine-hostname>\shared\jre<version>

For importing acs, bocs, wdk certificates into UCF client JRE:

keytool.exe -import -noprompt -trustcacerts -alias acscert -file "C:\certificate\acs.cer" -keystore "<User-directory>\Documentum\ucf\<machine-hostname>\shared\<jre>\lib\security\cacerts" keytool.exe -import -noprompt -trustcacerts -alias bocscert -file "C:\certificate\bocs.cer" -keystore "<User-directory>\Documentum\ucf\<machine-hostname>\shared\<jre>\lib\security\cacerts" keytool.exe -import -noprompt -trustcacerts -alias wdkcert -file "C:\certificate\wdk.cer" -keystore "<User-directory>\Documentum\ucf\<machine-hostname>\shared\<jre>\lib\security\cacerts" For importing acs, bocs, wdk certificates into browser java:

keytool.exe -import -noprompt -trustcacerts -alias acscert -file "C:\certificate\acs.cer" -keystore “<JAVA>\<jre>\lib\security\cacerts" keytool.exe -import -noprompt -trustcacerts -alias bocscert -file "C:\certificate\bocs.cer" -keystore “<JAVA>\<jre>\lib\security\cacerts" keytool.exe -import -noprompt -trustcacerts -alias wdkcert -file "C:\certificate\wdk.cer" -keystore “<JAVA>\<jre>\lib\security\cacerts"

Verify SSL Configuration User may follow below steps to verify the ACS, BOCS and DMS configured in SSL mode.

1. After each server restart, logs for ACS, BOCS and DMS servers can be checked if there is

any error or exception after enabling the SSL. 2. Try to access ACS, BOCS, DMS and WDK client application URLs from each machine by

using their full hostname with HTTPS protocol and SSL port. These URLs should be accessible from each machine.

3. User can retrieve any certificate to verify if it has been imported in trusted store or not by using the below command.

From <java>/bin keytool.exe -list -keystore “<jre_path>\lib\security\cacerts"

Provide the keystore password.

Page 19: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

19 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Monitor Logs During Content Transfer over SSL This section describes the UCF client logs for all content transfer requests and WDK, BOCS

logs for asynchronous write and predictive caching requests. In all cases, UCF client log level is set to ‘FINEST’, WDK client log level is set to ‘DEBUG’ and BOCS log level is set to ‘DEBUG’.

ACS read request The below UCF client log shows that the read request is successfully handled by ACS in SSL mode. ACS read url gets generated with HTTPS protocol and 9082 port.

Page 20: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

20 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

The below block diagram shows the interaction of different components during read and write requests through ACS.

Figure1: ACS read, write request

ACS write request The below UCF client log shows that the write request is successfully handled by ACS in SSL mode. ACS write url gets generated with HTTPS protocol and 9082 port.

WDK-based Client app

UCF Client

UCF Server/DFC

Content Server

ACS

HTTPS Request

Page 21: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

21 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Page 22: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

22 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

BOCS read request The below UCF client log shows that the read request is successfully handled by BOCS in SSL mode. BOCS read url gets generated with HTTPS protocol and 8088 port.

Page 23: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

23 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

The below block diagram shows the interaction of different components during read and write requests through BOCS.

Page 24: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

24 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Figure2: BOCS read, write request

BOCS write synchronous request a.) BOCS write request: The below UCF client log shows that the write request is successfully handled by BOCS in SSL mode. BOCS write url gets generated with HTTPS protocol and 8088 port.

WDK-based Client app

UCF Client

UCF Server/DFC

Content Server ACS

BOCS

Cache

HTTPS Request

HTTPS Request

Page 25: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

25 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Page 26: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

26 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Page 27: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

27 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

b.) BOCS move request: The below UCF client log shows that the move request is successfully handled by BOCS in SSL mode. BOCS move url gets generated with HTTPS protocol and 8088 port.

Asynchronous write request

a.) Park request: The below UCF client log shows that the park request is successfully handled by BOCS in SSL mode. BOCS park url gets generated with HTTPS protocol and 8088 port.

Page 28: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

28 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Below WDK log shows the park request handled with HTTPS and 8088 port. Content is successfully parked on BOCS server in prime store.

Page 29: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

29 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

b.) BOCS store request: Below WDK log shows the BOCS store request handled with HTTPS and 8088 port.

Below WDK log shows the message is successfully sent to DMS (https ://< dmsmachinename.dnsname.com>:8491/).

Page 30: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

30 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

c.) ACS store request: Below BOCS log shows the ACS store request handled with HTTPS and 9082 port. Content is now successfully sent to the ACS.

Once the content is written to the repository, message is being processed successfully. Below BOCS server log shows the response status is sent to return URL (https ://< dmsmachinename.dnsname.com >:8491) that updates the message status in database.

Page 31: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

31 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

The below block diagram shows the interaction of different components during asynchronous write requests.

Figure3: Asynchronous write request

Predictive Caching request Below BOCS log shows the predictive caching request handled with HTTPS and 9082 port by ACS URL. Content is downloaded successfully to the BOCS cache.

WDK-based Client app

UCF Client

UCF Server/DFC

Content Server ACS

BOCS

Cache

HTTPS Request

HTTPS Request

HTTPS return url

Message

DMS

Page 32: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

32 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Below BOCS log shows the message is being processed successfully and the response status is sent to return URL (https ://< dmsmachinename.dnsname.com>:8491) that updates the message status in database.

Page 33: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

33 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Useful Points

1. For exporting the certificates, user can apply below alternate way. a.) Access the HTTPS url by using the hostname, browser throws the ‘certificate error’ at

right side in address bar. Click on that. Click on view certificates-> Install certificate-> click next-> select ‘Place all certificates in the following store’-> browse the certificate store-> select ‘Trusted root certification authorities’-> click next-> click finish->click ok.

b.) Close the browser and reopen it. It will not throw ‘certificate error’ now.

c.) Go to tools-> internet options-> content->click on certificates-> go to trusted root

certification authorities.

d.) Select the same certificate which got installed in step a.

e.) Click on export-> click next-> select first option .cer-> click next-> browse the file name. (like C:\acs.cer)-> click next-> click finish. It will pop up the message “The export was successful”. Click ok -> close the window.

2. Make sure the keystore file and corresponding password is given correctly in application server’s configuration file (server.xml). Size of the cipher to be specified correctly.

3. If DMS is installed on the same CS machine then one keystore (ACS one) can be used for both servers ACS and DMS. If the DMS is installed on another machine then DMS machine’s keystore should be created and used.

4. If the keystore is tampered and a new keystore is being replaced then the new corresponding certificate should be replaced/imported in every machine’s running JVM wherever it was imported before.

5. If the apache tomcat 7.0 application server is used for deploying WDK-based client application then tomcat will try to use APR connector that needs other different SSL settings (particularly keys and certificates). “OpenSSL” can be used to generate those attributes. Or else user can disable the APR library path in server.xml file and can use the normal SSL configuration settings.

Page 34: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

34 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

Troubleshooting Tips

S. No.

Issues Possible Cause Solution

1. SSLexception: java.security.cert.CertificateException: No name “hostname” matching found

Accessing the URL with different hostname which is not used in specific certificate.

While accessing any URL (ACS, BOCS, DMS or WDK client app), hostname should be used as full CN name in URL. That same CN has been set while creating the keystore.

2. "java.io.FileNotFoundException: <some-directory>/<keystorefilename>.keystore not found"

Keystore file is not there in path which is specified in server.xml.

Check and provide the correct path for .keystore file as ‘keystoreFile’ attribute in server.xml.

3. "java.io.FileNotFoundException: Keystore was tampered with, or password was incorrect"

Wrong keystore password is provided in server.xml for ‘keystorePass’ attribute.

Check and provide the correct password for keystore as ‘keystorePass’ attribute in server.xml. Or User can create a new keystore with new password and provide the same server.xml.

4. SSLexception: javax.net.ssl.SSLException: java.lang.RuntimeException: Could not generate DH keypair

During content transfer, if ucf client is using JRE version lower to 1.7.07

UCF's private JRE version should be 1.7, update 07 or higher than this. (Here, it is assumed that Documentum version 7.0 is being used by user.)

5. java.security.InvalidKeyException: Illegal key size

If the ‘ciphers’ attribute is not defined in server.xml to specify the size to be used by JBOSS then cipher size above 128 bits (AES128) is being used by JBOSS application server.

If user wants to use more strength ciphers (above AES128), they should install "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files". Or ‘Ciphers’ attribute with limiting the size 128 can be added in server.xml for JBOSS. ciphers="TLS_RSA_WITH_AES_128_CBC_SHA" (This option is implemented in Documentum 7.0 onwards.)

Page 35: White Paper - Distributed Content SSL Configuration and ... · DISTRIBUTED CONTENT SSL CONFIGURATION AND 3 TROUBLESHOOTING GUIDE Table of Contents Executive summary

35 DISTRIBUTED CONTENT SSL CONFIGURATION AND TROUBLESHOOTING GUIDE

6. Connection issues with ACS, BOCS, DMS and WDK-based client machines.

Not able to ping machines with their full CN (which is used during keystore creation).

Map the machine’s ip to their full hostname in etc/hosts file. (This hostname must have been used in keystore creation as common name.)

Conclusion This white paper explains the procedure for configuring Distributed Content to support secure socket layer connections. It is easy to understand and very helpful in setting up the ACS, BOCS, DMS and WDK-based client in SSL environment. It describes the content transfer behavior in SSL environment and monitors the logs for HTTPS and SSL port URLs being used during operations.

References • http://developer-

content.emc.com/developer/downloads/Distributed_Content_Configuration_And_Troubleshooting.pdf

• https://support.emc.com/docu32947_Documentum-Content-Server-6.7-Distributed-Configuration-Guide.pdf?language=en_US

• http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html