Chapter 13 Changing the Password Encryption Key

Sun Java^TM System Access Manager 7.1 uses a password encryption key to encrypt user passwords. All Access Manager subcomponents must use the same password encryption key value. If you plan to deploy multiple instances of Access Manager, you must use the same password encryption key for all instances.

• Installation Considerations

• Changing the Encryption Key Value

Installation Considerations

When you install Access Manager, the Sun Java Enterprise System (Java ES) installer generates a default password encryption key string. You can either accept this default value or specify another value produced by a J2EE random number generator. The installer stores the password encryption key value in the am.encryption.pwd property in the AMConfig.properties file.

If you specify a value for the password encryption key, the string must be at least 12 characters long.

To deploy multiple instances of Access Manager, save the password encryption key value from the am.encryption.pwd property after you install the first instance. Then, use this key value to set the value when you deploy additional instances:

• If you run the Java ES installer, copy this value into the Password Encryption Key field on the Access Manager: Administration page.

• If you run the amconfig script, set the AM_ENC_PWD variable to this value in the amsamplesilent configuration file (or copy of the file) before you run the script.

• On Windows systems, if you run amconfig.bat, set the AM_ENC_PWD variable in the AmConfigurator.properties configuration file (or copy of the file).

Changing the Encryption Key Value

The following scenarios explain why you might need to retrieve and change the password encryption key. In these scenarios, all Access Manager instances use the same Directory Server.

• If you are doing a multiple server installation of Access Manager and you did not save the password encryption key when you installed the first Access Manager instance, you must retrieve the key to use when you deploy additional instances.

• If you have deployed an additional Access Manager instance that uses a different password encryption key from the first Access Manager instance, you must modify the encryption key value to match the first instance.

Passwords and the password encryption key must be consistent throughout a deployment. If you change a password in one place or instance, you must also update the password in all other places and instances.

The serverconfig.xml file contains the encrypted user passwords, which are identified by the <DirPassword> element. For example:

<DirPassword>
Adfhfghghfhdghdfhdfghrteutru
</DirPassword>

The puser and dsameuser passwords in serverconfig.xml are encrypted using the password encryption key defined in am.encryption.pwd in the AMConfig.properties file. If you change the password encryption key, you must also re-encrypt these passwords in the serverconfig.xml file using the ampassword utility (or ampassword.bat on Windows systems).

For information about the ampassword utility, see Chapter 2, The ampassword Command Line Tool, in Sun Java System Access Manager 7.1 Administration Reference.

If you are changing the password encryption key value on a Windows system, follow the next procedure, but run amconfig.bat with configuration parameters specified in the AMConfigurator.properties file (or a copy of the file).

To change the password encryption key value

1. Log in as or become superuser (root) on the host server where the first Access Manager instance is installed.

2. In the AMConfig.properties file for the first Access Manager instance, save the values of the following properties:

   • Password encryption key: am.encryption.pwd

   • Shared secret: com.iplanet.am.service.secret

   The AMConfig.properties file is installed in the following directory, depending on your platform:

   • Solaris systems: /etc/opt/SUNWam/config

   • Linux and HP-UX systems: /etc/opt/sun/identity/config

   • Windows systems: javaes-install-dir\identity\config

     javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5.

3. Log in as or become superuser (root) on the server where the second Access Manager instance is deployed.

4. As a precaution, back up the AMConfig.properties and serverconfig.xml files, which are in the /config directory.

5. Stop the web container for the second Access Manager instance.

   For example, on a Solaris system, with Sun Java System Web Server as the web container:

   # cd /opt/SUNWwbsvr/https-host2-name #./stop

6. Edit the AMConfig.properties file and replace the values for am.encryption.pwd and com.iplanet.am.service.secret with the values that you saved from the first Access Manager instance in Step 2.

7. Because the encryption key defined in am.encryption.pwd is changed, you must run the ampassword utility to re-encrypt and replace the passwords in the serverconfig.xml file. The passwords in serverconfig.xml are identified by the <DirPassword> element. Consider the following cases:

   Passwords are the same. If the password for puser and dsameuser is the same as the amadmin password in serverconfig.xml, run ampassword to re-encrypt the amadmin password. For example on Solaris systems:

   # cd /opt/SUNWam/bin
   # ./ampassword --encrypt password
   

   where password is the password you used for amadmin when you installed the first instance. Use the ampassword output (new encrypted password) to replace the two passwords in the serverconfig.xml file for the second instance.

   Passwords are different. If the passwords for puser and dsameuser are different from the amadmin password in serverconfig.xml, run ampassword to re-encrypt each password (type="proxy" and type="admin").

   Use the ampassword output (new encrypted passwords) to replace the puser and dsameuser passwords in serverconfig.xml for the second instance.

8. Restart the web container for the second Access Manager instance. For example, on a Solaris system, with Web Server as the web container:

   # cd /opt/SUNWwbsvr/https-host2-name # ./start

Next Steps

Repeat Step 3 through Step 8 for any additional instances of Access Manager in the deployment.