Appendix B Changing the Password Encryption Key

Sun Java^TM System Access Manager 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 on different host servers, you must use the same password encryption key for all instances.

Installation Considerations

When you install the first Access Manager instance, the Java Enterprise System 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 attribute 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 attribute 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” panel.

• 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).

The following scenarios explain why you might need to retrieve and change the password encryption key. In these scenarios, the 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.

What else needs to be changed if you change the password encryption key?

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.

For information about the ampassword utility, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.

Changing the Key Value

To change the password encryption key value, follow these steps:

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, get and save the values of the following attributes:

   • Password encryption key: am.encryption.pwd

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

   The AMConfig.properties file is installed in the following directories:

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

   • Linux systems: /etc/opt/sun/identity/config

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 of the second Access Manager instance. For example, on Solaris systems, with 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 Access Manager for the second instance. For example, on Solaris systems, with Web Server as the web container:

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

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