UAL File Corruption in Entrust IdentityGuard and how to fix it!

System administrators managing Entrust Identity Guard environments occasionally encounter the dreaded UAL file corruption error. This blog post will walk you through understanding, resolving, and preventing this critical issue.

The Problem: UAL File Corruption

If you've encountered an error message similar to the following, you're dealing with a UAL file corruption issue:

[5201200] Error reading key information from configuration. (Ref:1476745221)
Caused by: [5201231] Error validating administrator passwords using key protection 
data provided. (Ref:1474910185)

Caused by: [5201242] There was an error while attempting to retrieve some data that is 
bound to the local computer. (Ref:1210140705)
Caused by: com.entrust.toolkit.exceptions.UALException: Invalid or corrupt UAL file

What Causes UAL File Corruption?

The primary culprits are:

• Hardware changes to your server
• System patches and updates
• Windows updates

The Solution: Re-binding Your IdentityGuard Server (to fix UAL corruption)

Follow these steps carefully to resolve the issue:

1. Backup your configuration
   
   Create a backup copy of the entire "etc" directory on your IdentityGuard server.
   On Windows systems, this is typically located at:
   C:\Program Files\Entrust\IdentityGuard\identityguard130\etc

2. Rename the masterkeys file
   
   Rename the file ./etc/masterkeys.kpf to something like masterkeys.kpf.bak

3. Launch Master User Shell

4. Open the Master User Shell but do not attempt to log in yet.

5. Initialize as replica
   
    Enter the command: init -replica

   ⚠️ WARNING: Do not enter just 'init' as this will initialize a new IdentityGuard Server that will be unable to read your current data. You must use init -replica.

6. Enter your master passwords
   
   Provide the same three master passwords you used previously, which should be stored in your password manager for security:
   
   Password is required for Master1
   Password is required for Master2
   Password is required for Master3

7. Update version references if needed
   
   In the identityguard.properties file, find and replace any instances of older version references (like "identityguard120") with the correct version (such as "identityguard130").

Preventing UAL File Corruption

UAL files use a concept called "strikes" (also known as UAL Fingerprint failures). A strike occurs when there's a change to UAL input parameters, such as hardware or software modifications. While a single strike won't cause an exception, multiple changes will result in decryption failure and require manual rebinding.

1. Unbind before system changes
   
   Before making any hardware or software changes to your system (physical or virtual), unbind the keys via Master User Shell using system unbind after completing changes, rebind the keys using the system bind command.

2. Check for binding issues before patching
   
   Review the identityguard_system.log file for any outstanding binding issues before applying Windows patches. If you see a message like "The key protection file binding has changed; run 'system bind' again," clear the strike by running the system bind command in Master User Shell.

3. Verify binding status before service restarts
   
   Since UAL information is only processed at system restart, run system bindcheck from Master User Shell before restarting Entrust services. If you see "Binding Status: The master keys are bound, but you should update the binding," run the system bind command to resolve the issue.