Documentum Upgrade – Switch from Lockbox to AEK key

As you probably know already, Documentum removed the support for RSA Libraries and RSA Lockbox starting with Documentum version 16.7. This means that if you are planning to upgrade to 16.7 or higher versions, you will first need to remove the lockbox from your installation and extract your AEK key from it before starting the upgrade process. To be completely exact, upgrading to 16.7 or above in place (using VMs for example) is normally going to do that for you but if you are using the docker images from OpenText, it’s not going to happen. Therefore, it is always good to know how to do it anyway.

The process to “downgrade” from the Lockbox to the AEK key (the other way around wasn’t really an upgrade in terms of security anyway…) is pretty simple and if I’m not mistaken, it is now in the Upgrade & Migration Guide of Documentum 16.7. This can be prepared while the repository is running but it will require a quick restart to be applied. If you are facing any issue, you can also go back to the Lockbox first and figuring out what the issue is later.

It’s very simple and straightforward to extract the AEK key from the Lockbox but there is one requirement to met. Indeed, you will need the latest version of the dm_crypto_create utility which has been packaged starting with:

• Documentum 7.2 P42
• Documentum 7.3 P23
• Documentum 16.4 P10

If you are using an older version or an older patch, you will first need to upgrade/patch to one of these versions. It **might** be possible to just take the binary from one of these patches and use it on older versions of Documentum but that is probably not supported and it would need to be tested first to make sure it doesn’t break in the process. If you want to test that, just make sure to use the correct version of Lockbox libraries (version 3.1 for CS 7.3 and lower // version 4.0 for CS 16.4).

Once you are with the correct version/patch level, the extraction is just one simple command. Therefore, it can be automated easily in the upgrade process. Before starting, let’s setup/prepare the environment and making sure all is currently working with the Lockbox. I’m using a demo environment I built a few weeks on Kubernetes to show how it works:

[dmadmin@cs-0 ~]$ cd $DOCUMENTUM/dba
[dmadmin@cs-0 dba]$
[dmadmin@cs-0 dba]$ cp -R secure secure_$(date "+%Y%m%d")
[dmadmin@cs-0 dba]$
[dmadmin@cs-0 dba]$ cd secure
[dmadmin@cs-0 secure]$ ls -ltr
total 24
-rw-rw-r-- 1 dmadmin dmadmin 3750 Mar 30 13:30 lockbox.lb
-rw-rw-r-- 1 dmadmin dmadmin    3 Mar 30 13:30 lockbox.lb.FCD
drwxrwx--- 2 dmadmin dmadmin  152 Mar 30 17:41 ldapdb
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ gr_repo="GR_REPO1"
[dmadmin@cs-0 secure]$ s_ini="$DOCUMENTUM/dba/config/${gr_repo}/server.ini"
[dmadmin@cs-0 secure]$ 
[dmadmin@cs-0 secure]$ grep "crypto" ${s_ini}
crypto_mode = AES256_RSA1024_SHA256
crypto_keystore = Local
crypto_lockbox = lockbox.lb
crypto_keyname = CSaek
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ lb_name=$(grep "^crypto_lockbox" ${s_ini} | sed 's,crypto_lockbox[[:space:]]*=[[:space:]]*,,')
[dmadmin@cs-0 secure]$ aek_name=$(grep "^crypto_keyname" ${s_ini} | sed 's,crypto_keyname[[:space:]]*=[[:space:]]*,,')
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ echo "Lockbox Name: ${lb_name} -- AEK Name: ${aek_name}"
Lockbox Name: lockbox.lb -- AEK Name: CSaek
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ read -s -p "  --> Please put here the Lockbox Passphrase and press Enter: " lb_pp; echo
  --> Please put here the Lockbox Passphrase and press Enter:
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ read -s -p "  --> Please put here the AEK Passphrase and press Enter: " aek_pp; echo
  --> Please put here the AEK Passphrase and press Enter:
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ # If the below command returns '0', then the Lockbox name, AEK passphrase and the AEK Key name are correct
[dmadmin@cs-0 secure]$ # but it doesn't really test the Lockbox passphrase
[dmadmin@cs-0 secure]$ dm_crypto_create -lockbox ${lb_name} -lockboxpassphrase ${lb_pp} -keyname ${aek_name} -passphrase ${aek_pp} -check


Key - CSaek uses algorithm AES_256_CBC.

** An AEK store with the given passphrase exists in lockbox lockbox.lb and got status code returned as '0'.
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ # If the below command returns 'Reset host done', then the Lockbox name and Lockbox passphrase are both correct
[dmadmin@cs-0 secure]$ dm_crypto_manage_lockbox -lockbox ${lb_name} -lockboxpassphrase ${lb_pp} -resetfingerprint
Lockbox lockbox.lb
Lockbox Path $DOCUMENTUM/dba/secure/lockbox.lb
Reset host done
[dmadmin@cs-0 secure]$

Once everything is ready & verified, extracting the AEK key is a piece of cake:

[dmadmin@cs-0 secure]$ # AEK passphrase isn't needed to extract the AEK key
[dmadmin@cs-0 secure]$ dm_crypto_create -lockbox ${lb_name} -lockboxpassphrase ${lb_pp} -keyname ${aek_name} -removelockbox -output ${aek_name}


Retrieved key 'CSaek' from lockbox 'lockbox.lb' and stored as '$DOCUMENTUM/dba/secure/CSaek'
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ ls -ltr
total 24
-rw-rw-r-- 1 dmadmin dmadmin 3750 Mar 30 13:30 lockbox.lb
-rw-rw-r-- 1 dmadmin dmadmin    3 Mar 30 13:30 lockbox.lb.FCD
drwxrwx--- 2 dmadmin dmadmin  152 Mar 30 17:41 ldapdb
-rw-r----- 1 dmadmin dmadmin  144 May  8 21:52 CSaek
[dmadmin@cs-0 secure]$

When it’s done, a new file has been created with the name specified in the “-output” parameter (${aek_name} above, meaning “CSaek“). The only remaining step is reflecting this change in the server.ini and restarting the repository:

[dmadmin@cs-0 secure]$ grep "crypto" ${s_ini}
crypto_mode = AES256_RSA1024_SHA256
crypto_keystore = Local
crypto_lockbox = lockbox.lb
crypto_keyname = CSaek
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ sed -i 's,^crypto_lockbox,#&,' ${s_ini}
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ grep "crypto" ${s_ini}
crypto_mode = AES256_RSA1024_SHA256
crypto_keystore = Local
#crypto_lockbox = lockbox.lb
crypto_keyname = CSaek
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ 
[dmadmin@cs-0 secure]$ $DOCUMENTUM/dba/dm_shutdown_${gr_repo}
Stopping Documentum server for repository: [GR_REPO1]


        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2018. OpenText Corporation
        All rights reserved.
        Client Library Release 16.4.0200.0080

Connecting to Server using docbase GR_REPO1.GR_REPO1
[DM_SESSION_I_SESSION_START]info:  "Session 010f123450009905 started for user dmadmin."

Connected to OpenText Documentum Server running Release 16.4.0200.0256  Linux64.Oracle
Session id is s0
API> shutdown,c,T,T
...
OK
API> exit
Bye
Waiting for 90 seconds for server pid, 4188, to disappear.

Fri May  8 21:53:39 UTC 2020: Waiting for shutdown of repository: [GR_REPO1]
Fri May  8 21:53:39 UTC 2020: checking for pid: 4188

Fri May  8 21:53:49 UTC 2020: Waiting for shutdown of repository: [GR_REPO1]
Fri May  8 21:53:49 UTC 2020: checking for pid: 4188

repository: [GR_REPO1] has been shutdown
checking that all children (4214 4218 4219 4263 4305 4348 4542 4557 4584 4766) have shutdown
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ $DOCUMENTUM/dba/dm_start_${gr_repo}
starting Documentum server for repository: [GR_REPO1]
with server log: [$DOCUMENTUM/dba/log/GR_REPO1.log]
server pid: 5055
[dmadmin@cs-0 secure]$
[dmadmin@cs-0 secure]$ head -20 $DOCUMENTUM/dba/log/${gr_repo}.log


    OpenText Documentum Content Server (version 16.4.0200.0256  Linux64.Oracle)
    Copyright (c) 2018. OpenText Corporation
    All rights reserved.

2020-05-08T21:54:02.033346      5055[5055]      0000000000000000        [DM_SERVER_I_START_SERVER]info:  "Docbase GR_REPO1 attempting to open"

2020-05-08T21:54:02.033471      5055[5055]      0000000000000000        [DM_SERVER_I_START_KEY_STORAGE_MODE]info:  "Docbase GR_REPO1 is using database for cryptographic key storage"

2020-05-08T21:54:02.033507      5055[5055]      0000000000000000        [DM_SERVER_I_START_SERVER]info:  "Docbase GR_REPO1 process identity: user(dmadmin)"

2020-05-08T21:54:02.833702      5055[5055]      0000000000000000        [DM_SESSION_I_INIT_BEGIN]info:  "Initialize Post Upgrade Processing."

2020-05-08T21:54:02.835032      5055[5055]      0000000000000000        [DM_SESSION_I_INIT_BEGIN]info:  "Initialize Base Types."

2020-05-08T21:54:02.837725      5055[5055]      0000000000000000        [DM_SESSION_I_INIT_BEGIN]info:  "Initialize dmRecovery."

2020-05-08T21:54:02.846022      5055[5055]      0000000000000000        [DM_SESSION_I_INIT_BEGIN]info:  "Initialize dmACL."

[dmadmin@cs-0 secure]$

That’s basically it. You are now running with the plain AEK Key just like before the introduction of the Lockbox a few years ago with the Documentum 7.x version.

Maybe one last note on the “dfc.crypto.repository” property of the dfc.properties. As you might know, this property has been introduced to support the move to the lockbox so that Documentum knows which repository should be used for all crypto needs. This parameter should apparently stay, even if you remove the lockbox and continue with the AEK file only because the decryption logic is on the server side and so the DFC Clients still need to know which repository can help on that part. Maybe that will change though…