REMOTE KEY MANAGEMENT (RKM) ENABLEMENT FOR EXISTING DOCUMENTUM CONTENT SERVER DEPLOYMENTS White Paper ABSTRACT This white paper provides detailed overview of how to enable Remote Key Management (RKM) for existing pre-7.2 or 7.2 Content Server deployments. It helps in planning and implementing RKM integration by covering different ways to achieve it for different configurations and specifies the recommended way. June, 2015 EMC WHITE PAPER
To learn more about how EMC products, services, and solutions can help solve your business and IT challenges, contact your local representative or authorized reseller, visit www.emc.com, or explore and compare products in the EMC Store Copyright 2015 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as 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 registered trademark of VMware, Inc. in the United States and/or other jurisdictions. All other trademarks used herein are the property of their respective owners. Part Number H14263 2
TABLE OF CONTENTS EXECUTIVE SUMMARY... 4 Audience... 4 Terminology... 4 Prerequisites... 4 RKM ENABLEMENT DURING UPGRADE... 4 RKM ENABLEMENT FOR EXISTING DOCBASE (FRESH OR UPGRADED / MIGRATED)... 7 Using License Configuration Panel... 7 Using Upgrade Existing Repository... 13 ENABLING RKM FOR REMOTE CONTENT SERVER (RCS)... 21 TROUBLESHOOTING TIPS... 25 BEST PRACTICES... 27 CONCLUSION... 27 REFERENCES... 27 3
EXECUTIVE SUMMARY RSA Data Protection Manager (RSA DPM) can be used to secure and manage encryption keys created / used by Content Server. This feature is known as Remote Key Management (RKM). Four types of keys are managed by RSA DPM if configured for Content Server: Docbase Key (DBK), Login Ticket Key (LTK), File Store Key (FSK) and Public/Private Key (PPK). Prior to Content Server version 7.2, Remote Key Management for encryption keys can only be enabled during Docbase configuration. It was not possible to enable RKM for existing Docbase, even during Docbase upgrade. Content Server 7.2 introduced a feature to enable RKM for an existing Docbase. For pre-7.2 Docbases, RKM can now be enabled during upgrade or post-upgrade. This paper explains this feature and describes how RKM can be enabled for different configurations. AUDIENCE This white paper is intended for system administrators, support professionals and customers. TERMINOLOGY Special terms, abbreviations and acronyms that may appear in this guide are defined below: Table 1 TERM AEK DBK LTK FSK PPK DPM RKM RCS Terminology DESCRIPTION Administration Encryption Key Docbase Key Login Ticket Key File Store Key Private/Public Key Data Protection Manager Remote Key Management Remote Content Server PREREQUISITES 1. RSA Data Protection Manager (referred in this paper as RKM server) should be deployed and configured as described below: o o Create Identity Group for Docbase and Identities for each Content Server serving Docbase Create key classes for storing encryption keys (DBK, LTK, FSK and PPK), providing same encryption algorithm and key size with which these keys were created. This is same as encryption algorithm and key size of AEK created while configuring Docbase. Content Server creates these keys with same algorithm and size with the exception of PPK whose encryption algorithm and key size is always RSA and 1024 respectively. Note that AEK key size may be different than other key sizes if AEK was upgraded post Docbase configuration (like during Docbase upgrade). So, be careful that key classes are created with same key size as these keys and not AEK, whose value is given in server.ini. 2. Make sure that Trusted Content Services license is enabled for Content Server. You can enable licenses using Server Configuration Program. RKM ENABLEMENT DURING UPGRADE You can enable RKM during Docbase Upgrade from 6.x/7.x to 7.2. Content Server also supports enabling RKM post upgrade to 7.2 which is described in next section. You can enable RKM even if you are upgrading/changing AEK or enabling Lockbox (for AEK) during upgrade. In all cases, key size of other keys (DBK, LTK, FSK, PPK) remain same as that given during Docbase configuration and same key size should be specified while creating key classes in RKM server. Note that pre 7.2 there was no 4
option to choose key algorithm / key size for AEK and other keys. Encryption keys were created with default key algorithm and key size. Also, default key algorithm/size was different for different releases. Below table will help you find out the attributes of key classes that should be created in RKM Server, depending on the version from which you are upgrading: Table 2 DEFAULT VALUES FOR ENCRYPTION KEYS BASE VERSION KEY ALGORITHM KEY SIZE KEY ALGORITHM KEY SIZE (DBK / FSK / LTK) (DBK / FSK / LTK) (PPK) (PPK) 6.X 3DES 168 RSA 1024 7.X (7.0, 7.1) AES 128 RSA 1024 Follow below steps to enable RKM during upgrade from pre-7.2 deployment to 7.2: 1. Follow steps given in Content Server Upgrade/Migration Guide for upgrading Content Server, Docbroker and Docbase, till screen for enabling modules is shown during Docbase upgrade 2. Enable Module 'Remote Key Management' and click 'Next' 5
3. Enter names of key classes created in RKM Server and click 'Next' 6
4. Enter RKM Server information and click 'Next' 5. Continue with Docbase upgrade RKM will be enabled for Docbase after upgrade completes successfully. You can follow the steps provided in Troubleshooting section to verify that RKM is enabled and Docbase is using RKM for key management. RKM ENABLEMENT FOR EXISTING DOCBASE (FRESH OR UPGRADED / MIGRATED) This section describes steps to enable RKM for a fresh 7.2 Docbase (if RKM was not enabled during Docbase creation) or for a Docbase upgraded / migrated from some previous version (6.x/7.x) to 7.2 (if RKM was not enabled during upgrade). You can enable RKM for an existing Docbase in two ways as described in next two sections. USING LICENSE CONFIGURATION PANEL This is preferred way to enable RKM if there is no extra requirement like upgrading AEK or moving AEK to Lockbox along with enabling RKM. Follow below steps to enable RKM: 1. Start Server Configuration ( %DM_HOME%\install\Server_Configuration_Program.exe) 2. Select 'Licensing' and click 'Next' 7
3. Enter installation owner password and click 'Next' 8
4. Verify that 'Trusted Content Services' license is checked which is required for enabling RKM 5. Select 'Yes' for enabling new module 'RKM' and click 'Next' 9
6. Select the repository for which you want to enable RKM and click 'Next' 10
7. Select 'Remote Key Management' module and click 'Next' 8. Enter the names of key classes created earlier and click 'Next' 11
9. Enter RKM Server information and click 'Next' 12
10. Click 'Next' to finish configuration USING UPGRADE EXISTING REPOSITORY You can use 'Upgrade existing Repository' functionality to enable RKM if you have extra requirements like: Upgrade / Change AEK key Move AEK key to Lockbox Follow below steps to enable RKM using the option of upgrade existing Docbase: 1. Start Server Configuration ( %DM_HOME%\install\Server_Configuration_Program.exe) 2. Select 'Repository' and click 'Next' 13
3. Enter installation owner password and click 'Next' 14
4. Select option 'Upgrade an existing repository' and select the repository for which you want to enable RKM; click 'Next' 5. Select 'Keep AEK key unchanged' or 'Upgrade AEK key' if want to upgrade AEK or move an existing AEK to Lockbox; click 'Next' 15
6. Enter Docbroker information and click 'Next' 16
7. Select connection mode for Docbroker and click 'Next' 8. Configure SSL Certificates if applicable and click 'Next' 17
9. Enter Mail Server details and click 'Next' 18
10. Enable 'Remote Key Management' module 11. Enter the names of key classes created earlier and click 'Next' 19
12. Enter RKM Server information and click 'Next' to proceed with Docbase upgrade 20
13. Click 'Next' to finish upgrade ENABLING RKM FOR REMOTE CONTENT SERVER (RCS) If you have Remote Content Server configured in distributed or load-balanced mode for Primary Server on which you have enabled RKM, then you need to upgrade RCS for RCS to continue working properly. For both pre-7.2 and 7.2 environments, upgrading RCS will automatically enable RKM for RCS, if RKM has been enabled for Primary Server. Follow below steps to upgrade 7.2 RCS: 1. Stop Server 2. Start cfsconfigurationprogram (%DM_HOME%\install\ cfsconfigurationprogram.exe) 3. Select 'Upgrade content-file server' and click 'Next' 21
4. Configure AEK and Lockbox settings and click 'Next' 22
5. Select content-file server to upgrade and click 'Next' 6. Enter Docbase Owner username and password; click 'Next' 23
7. Provide Keystore (p12) containing Identity Certificate for RCS and Keystore password; click 'Next' 24
8. Click 'Next' to finish configuration For pre-7.2 RCS, first upgrade Content Server to 7.2. Then, upgrade content-file server following the same steps as above. TROUBLESHOOTING TIPS This section describes how to verify whether RKM is configured and enabled properly for the Docbase and also how to troubleshoot issues in case RKM configuration fails. Steps to verify that RKM is configured successfully: 1. Key Migration Utility logs Check Keys migration utility logs to verify that key migration operation, migrating keys from database to RKM Server was successful. If this operation fails, then Installer will throw an error and all the steps till that failure will be roll-backed. Logs Location: %Documentum%\dba\config\<DOCBASE_NAME>\dm_crypto_upgrade_rkm.out 2. RKM Server Key Classes Verify that keys have been created inside key classes which were provided during installation. For DBK, LTK and PPK only one key should be created in the key classes. For FSK, number of keys created should be same as number of encrypted file-stores for that Docbase. 25
3. Docbase Logs After enabling RKM, restart Docbase. Verify that below is displayed on Docbase startup in Docbase logs (%Documentum%\dba\log\<DOCBASE_NAME>.log): [DM_SERVER_I_START_KEY_STORAGE_MODE]info: "Docbase <DOCBASE_NAME> is using RSA Key Manager for cryptographic key storage" 4. Server.ini configuration If RKM is enabled for Docbase, then below should be set properly in server.ini (%DOCUMENTUM%\dba\config\<DOCBASE_NAME>\server.ini) inside section 'RKM configuration parameters': o o Property crypto_keystore should be set to Remote key_class property should be present for all 4 keys with the same name as key classes created in RKM server Sample Server.ini: #RKM configuration parameters crypto_mode = AES128_RSA1024_SHA256 crypto_keystore = Remote #Above values cannot be changed once docbase is created crypto_keyname=aek.key rkm_dbk_key_class=repo71n1_dbk rkm_ltk_key_class=repo71n1_ltk rkm_fsk_key_class=repo71n1_fsk rkm_ppk_key_class=repo71n1_ppk Try these troubleshooting steps if any of the above verification fails: 1. Check the error in key migration logs, fix the issue and try enabling RKM again 2. Start installer in Debug mode if Key Migration is failing to get DEBUG logs. To start installer in Debug mode, use below command: %DM_HOME%\install\Server_Configuration_Program.exe -DLOG_LEVEL=DEBUG Debug logs will be created at below location: 26
%DM_HOME%\install\logs\install.log BEST PRACTICES For enabling RKM on 7.2 Docbases (fresh or upgraded), recommended way is using License configuration panel as against using upgrade existing Docbase. For Docbases migrated from pre-7.2 versions to 7.2, RKM should be enabled Post Migration instead of during migration. To achieve this, follow the steps in RKM enablement for existing Docbases after Docbase migration is successful. CONCLUSION This white paper can be used as a quick reference guide for planning RKM integration for an existing Content Server deployment in order to enhance system security. Secondly, it can be used as a guide for enabling RKM feature and troubleshooting issues. REFERENCES EMC Documentum Content Server Version 7.2 Installation Guide EMC Documentum Content Server Version 7.2 Upgrade and Migration Guide CONTACT US To learn more about how EMC products, services, and solutions can help solve your business and IT challenges, contact your local representative or authorized reseller, visit www.emc.com, or explore and compare products in the EMC Store. EMC 2, EMC, the EMC logo, are registered trademarks or trademarks of EMC Corporation in the United States and other countries. VMware is a registered trademark or trademark of VMware, Inc., in the United States and other jurisdictions. Copyright 2015 EMC Corporation. All rights reserved. Published in the USA. 06/15 White Paper, H14263 27 EMC believes the information in this document is accurate as of its publication date. The information is subject to change without notice.