IBM Platform Symphony 5.2 Fix Patch #229037 Readme File

Description

This patch provides a new feature. This feature enables user-definable AES-128 key for password encryption. Use this feature to perform the following functions:

·         Generate an AES-128 key. Once you have properly defined the EGO_KEYFILE parameter, you can use the egogenkey command-line tool to generate the key. (You can also create the key using an alternative method); egogenkey is provided as convenience.

·         Customize the AES-128 key to encrypt or decrypt the passwords of users defined in the users.xml file.

·         Apply the generated key to refresh all passwords based on the new key through the egoapplykey command-line tool.

This fix patch applies only to the following platforms:

·          Windows 64-bit

       ·          Linux x86_64 

Readme file for: IBM® Platform Symphony

Product/Component Release: 5.2

Update Name: Fix pack

Fix ID: sym-5.2-build229037-All

Publication date: 17th Jan 2014

Last modified date: 17th Jan 2014

 

Contents:

1.      Download location

2.      Products or components affected

3.      System requirements

4.      Installation and configuration

5.      List of fixes

6.      List of files

7.      Copyright and trademark information

1.   Download location

Search Fix ID in http://www.ibm.com/eserver/support/fixes/

2.   Products or components affected

Product/Component Name, Platform, Fix ID:

Platform Symphony/vemkd, Windows 64-bit & Linux x86_64, sym-5.2-build229037-All

Platform Symphony/egogenkey, Windows 64-bit & Linux x86_64, sym-5.2-build229037-All

Platform Symphony/egoapplykey, Windows 64-bit & Linux x86_64, sym-5.2-build229037-All

Platform Symphony/egostashpass-AD, Windows 64-bit, sym-5.2-build229037-All

Platform Symphony/sec_ego_default, Windows 64-bit & Linux x86_64, sym-5.2-build229037-All

Platform Symphony/sec_ego_ext_ad, Windows 64-bit, sym-5.2-build229037-All

 

3.   System requirements

None

4.   Installation and configuration

4.1          Before installation

            

             Attention: If you have patched package which is newer than this package, please use the correspond newer binaries from the newer package.

             1.      Shut down the cluster:

               Log on to the master host as the cluster administrator and run:

·         Windows

C:\>soamcontrol app disable all

C:\>egosh service stop all

C:\>egosh ego shutdown all

·         Linux

> source $EGO_TOP/cshrc.platform

> soamcontrol app disable all

> egosh service stop all

> egosh ego shutdown all

            2.      Back up files:

 

                  For Linux, on each management host in the cluster, back up the following binaries that will be replaced by this patch:

                         $EGO_TOP/1.2.6/linux2.6-glibc2.3-x86_64/etc/vemkd

                         $EGO_TOP/1.2.6/linux2.6-glibc2.3-x86_64/lib/sec_ego_default.so

                         $SOAM_HOME/5.2/linux2.6-glibc2.3-x86_64/lib/sec_ego_default.so

 

4.2      Installation steps

1.      Installation Instructions

1)       On Windows

Copy the appropriate EGO MSP package and SOAM MSP package to each management host in the cluster.

·    Interactive installation:

1) Double-click the EGO MSP package to run the EGO installer.

For example, if you are upgrading EGO on a Windows 64-bit management host, download and install ego1.2.6_win-x64-229037.msp.

2) Double-click the SOAM MSP package to run the SOAM installer.

                       ·    Silent installation:

1) Run the EGO installers from the command line using the following commands:

C:\>msiexec /update <EGO_package_name_path> /l*v <ego_install_log> /norestart /quiet REINSTALLMODE=omus

Where:

                               · EGO_package_name_path is the fully qualified filename of the EGO MSP package in this release.

· ego_install_log is the log file for the EGO upgrade.

For example, to update a Windows 64-bit management host, run the following commands:

C:\>msiexec /update C:\ego1.2.6_win-x64-229037.msp /l*v updateEGO.log /norestart /quiet REINSTALLMODE=omus

2) Run the SOAM installers from the command line using the following commands:

C:\>msiexec /update <SOAM_package_name_path> /l*v <soam_install_log> /norestart /quiet REINSTALLMODE=omus

Where:

                                · SOAM_package_name_path is the fully qualified filename of the SOAM MSP package in this release.

· soam_install_log is the log file for the SOAM upgrade.

For example, to update a Windows 64-bit management host, run the following commands:

C:\>msiexec /update C:\soam5.2.0_win-x64-229037.msp /l*v updateSOAM.log /norestart /quiet REINSTALLMODE=omus

2)       On Linux

1.       Copy the tar file sym5.2.0_lnx26-lib23-x64-229037.tar to the $EGO_TOP directory on each management host in the cluster.

2.       On each linux management node, replace the old binaries with the update binaries by command “tar –xvf sym5.2.0_lnx26-lib23-x64-229037.tar”

 

4.3          After installation

1.      Verify the installation

Run the vemkd -V command, you should see the following output:

>vemkd -V

Platform EGO 1.2.6.229037, Jan 10 2014

Copyright Platform Computing Inc., an IBM Company, 1992-2012.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

 

binary type: linux2.6-glibc2.3-x86_64

notes:

fixes:

 

Run the egoapplykey -V command, you should see the following output:

 >egoapplykey -V

Platform EGO 1.2.6.229037, Jan 10 2014

Copyright Platform Computing Inc., an IBM Company, 1992-2012.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

 

binary type: linux2.6-glibc2.3-x86_64

notes:

fixes:

 

Run the egogenkey -V command, you should see the following output:

>egogenkey -V

Platform EGO 1.2.6.229037, Jan 10 2014

Copyright Platform Computing Inc., an IBM Company, 1992-2012.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

 

binary type: linux2.6-glibc2.3-x86_64

notes:

fixes:

2.      Start the upgraded cluster

 Log on to the master host as the cluster administrator and run:

·         Windows

 

C:\>egosh ego start

C:\>egosh user logon –u <username> -x <password>

C:\>soamcontrol app enable <appName>

 

·         Linux

> source $EGO_TOP/cshrc.platform

> egosh ego start

> egosh user logon –u <username> -x <password>

> soamcontrol app enable <appName>

 

4.4               Configuration, Usage and Trouble Shooting

·         Configuration

                 Edit the $EGO_CONFDIR/ego.conf file (on your Platform Symphony management host) to define the EGO_KEYFILE parameter, which defines the absolute path to the location where the generated key file is stored.  For file access, place the key file

                 in a secure location. Only management hosts in the cluster require access to the key file. For file permissions, for security reasons, set permissions for the key file. Set ownership and permission as owner=os_clusteradmin, permission=600.

 

                 Use the following syntax:

         EGO_KEYFILE=keyfile_location

 

                 For example, EGO_KEYFILE=/tmp/seckey.conf.

 

                 The EGO_KEYFILE parameter is not defined by default. If a value is not specified or the parameter is not defined, the built-in key is used.

 

                 Once you have properly configured the EGO_KEYFILE parameter, you can use the egogenkey tool to easily generate an AES-128 key.

 

·         Usage

                  Customize an AES-128 key to encrypt or decrypt passwords of EGO users (defined in the users.xml file). This feature enables you to do the following:

                   1) Generate an AES-128 key to encrypt or decrypt passwords from the egogenkey tool. You can use the egogenkey tool as a means to conveniently create the key, if you have set up the EGO_KEYFILE parameter properly.

2)  Apply the generated key to encrypt all passwords from the egoapplykey tool.

                 To enable password encryption with an AES-128 key:

1.       Stop the cluster:

a.       Log on to the master host as the cluster administrator.

b.      Run the following commands to stop the cluster:
> egosh service stop all
> egosh ego shutdown

 

2.       Define the EGO_KEYFILE parameter in $EGO_CONFDIR/ego.conf. Refer to the Configuration section above for details.

 

3.       Run egogenkey to generate the key, which is temporarily stored in a location that you specify. For example:

 

      > egogenkey

      >Enter location to store temporary key file:/tmp/key.tmp

    

      Attention: The temporary file location specified here can NOT be same with the file location configured by EGO_KEYFILE in ego.conf.

 

1.       Run egoapplykey to apply the generated key file and store it in the location specified by EGO_KEYFILE. Ensure that you back up $EGO_CONFDIR/users.xml and the key file specified by EGO_KEYFILE to enable database recovery in case of fatal errors. If egoapplykey runs successfully, and you do not need to roll back to the old password used for encrypted passwords in users.xml, you can delete the backed up files.

Here is an example of running egoapplykey:


> egoapplykey

To enable database recovery in case of fatal errors, back up users.xml and the key file specified by EGO_KEYFILE before proceeding. Continue Y/N? y

Enter location of temporary key file: /tmp/key.tmp

Enter Admin password: Admin        

Applying temporary key file to generate new encryption key...

      New encryption key has been applied successfully and saved to location specified by EGO_KEYFILE.

2.       If you have configured the AD plug-in as the security plug-in, use the following commands to stash the “Admin” password:

·         AD plug-in: egostashpass-AD

3.       Start the cluster with the following command:

> egosh ego start

 

·         Troubleshooting

1.       If egosc cannot start up successfully and the VEMKD log includes the following message: Failed to create credential for EGO default Cluster Administrator, it may be because the VEMKD process failed to load the correct encryption password key from EGO_KEYFILE. Usually, this issue is caused by permission control settings. Ensure EGO LIM is started as the cluster administrator account and that the cluster administrator can access EGO_KEYFILE on Windows.

2.       If the user cannot log on to the SD but can log on to EGO successfully, before changing the encryption password key, ensure that you stop the cluster including EGO services.

3.       Ensure EGO has permissions to access the key file defined by the EGO_KEYFILE parameter. If failover is not set up, the shared directory is not configured on management hosts, and the key file is stored in the UNC path (which could be the same as a shared directory), the VEMKD process uses the default encryption key, in which case authentication may not work well. This occurs because the local system user account does not have permissions to access the key file. In this case, use Windows administrative tools to configure EGO LIM to start as the cluster administrator; then, ensure that the cluster administrator can access EGO_KEYFILE.

 

4.5          Uninstalling

1.      Shut down the cluster

Log on to the master host as the cluster administrator and run:

·         Windows:

C:\>soamcontrol app disable all

C:\>egosh service stop all

C:\>egosh ego shutdown all

 

·         Linux:

> source $EGO_TOP/cshrc.platform

> soamcontrol app disable all

> egosh service stop all

> egosh ego shutdown all

 2.      Roll back installation

·         Windows:

1)      Get the EGO msp package and SOAM msp package for Symphony 5.2

2)      On each management host in the cluster, use the following command to roll back EGO:

C:\>msiexec /uninstall <EGO_SP_path> /package <EGO_5.2_path> /norestart /quiet /l*v <ego_rollback_log> MASTERHOST=<masterhost> CLUSTERADMIN=<domain\admin> LICENSEFILE=<lincense_path>

Where:

·   EGO_SP_path is the fully qualified filename of the EGO MSP package in this release.

·   EGO_5.2_path is the fully qualified filename of the EGO msp package for Symphony5.2.

·   ego_rollback_log is the log file for the EGO rollback.

·   masterhost is the master host of the cluster that is being rolled back.

·   domain\admin is the domain and username of the cluster’s administrator.

·   license_path is the fully qualified filename of the license file.

3)      On each management host in the cluster, use the following command to roll back SOAM:

C:\>msiexec /uninstall <SOAM_SP_path> /package <SOAM_5.2_path> /norestart /quiet /l*v <soam_rollback_log> MASTERHOST=<masterhost> CLUSTERADMIN=<domain\admin> LICENSEFILE=<lincense_path>

Where:

·   SOAM_SP_path is the fully qualified filename of the SOAM MSP package in this release.

·   SOAM_5.2_path is the fully qualified filename of the SOAM msp package for Symphony5.2.

·   soam_rollback_log is the log file for the SOAM rollback.

·   masterhost is the master host of the cluster that is being rolled back.

·   domain\admin is the domain and username of the cluster’s administrator.

·   license_path is the fully qualified filename of the license file.

 

·         Linux:

           Restore the backup files on each management host

 3.      Start the cluster

 Log on to the master host as the cluster administrator and run:

·         Windows

 

C:\>egosh ego start

C:\>egosh user logon –u <username> -x <password>

C:\>soamcontrol app enable <appName>

·         Linux

> source $EGO_TOP/cshrc.platform

> egosh ego start

> egosh user logon –u <username> -x <password>

> soamcontrol app enable <appName>

5.   List of fixes

 

<APAR#>: P100265

Description: Support configurable encryption key for stored password.

 

6.   List of files

 

1. ego1.2.6_win-x64-229037.msp
The file lists of ego1.2.6_win-x64-229037.msp:
1.2.6/etc/vemkd.exe
1.2.6/etc/vemkd.pdb
1.2.6/bin/egoapplykey.exe;
1.2.6/bin/egogenkey.exe;
1.2.6/bin/egostashpass-AD.exe
1.2.6/lib/sec_ego_default.dll 
1.2.6/lib/sec_ego_default.pdb
1.2.6/lib/sec_ego_ext_ad.dll   
1.2.6/lib/sec_ego_ext_ad.pdb   
 
2. soam5.2.0_win-x64-229037.msp
The file lists of soam5.2.0_win-x64-229037.msp:
soam/5.2/w2k3_x64-vc7-psdk/lib/sec_ego_default.dll 
soam/5.2/w2k3_x64-vc7-psdk/lib/sec_ego_ext_ad.dll
 
3. sym5.2.0_lnx26-lib23-x64-229037.tar
     The file lists of sym5.2.0_lnx26-lib23-x64-229037.tar:
1.2.6/linux2.6-glibc2.3-x86_64/etc/vemkd
1.2.6/linux2.6-glibc2.3-x86_64/bin/egogenkey
1.2.6/linux2.6-glibc2.3-x86_64/bin/egoapplykey
1.2.6/linux2.6-glibc2.3-x86_64/lib/sec_ego_default.so
soam/5.2/linux2.6-glibc2.3-x86_64/lib/sec_ego_default.so

 

7.       Copyright and trademark information

© Copyright IBM Corporation 2014

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM®, the IBM logo and ibm.com® are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.