Password encoding

• What password encoding is

• What password encoding is not

• Issues to consider when using the OS400 password encoding algorithm

• Enabling the OS400 password encoding algorithm for a WebSphere instance

• Manually encoding passwords in properties files

• Administration of validation list objects

• Switching algorithms

• Problem resolution

What password encoding is

The purpose of password encoding is to deter casual observation of passwords in server configuration and property files. By default, passwords are automatically encoded with a simple masking algorithm in various ASCII WebSphere server configuration files. Additionally, passwords can be manually encoded in properties files used by Java clients and by WebSphere administrative commands.

The default encoding algorithm is referred to as XOR. An alternate OS400 encoding algorithm can be used only with WebSphere Application Server for iSeries and exploits native validation list (*VLDL) objects. With the OS400 algorithm, passwords are stored in encrypted form within a validation list, and the configuration files then contain indexes to the the stored passwords instead of the masked passwords themselves as is done with the XOR algorithm.

Properties of the WebSphere Application Server instance control which algorithm to use for encoding the passwords.

Encoded passwords are of this form:

  {algorithm}encoded_password

where {algorithm} is a tag that specifies the algorithm used to encode the password (either XOR or OS400), and encoded_password is the encoded value of the password. When a server or client needs to decode a password, it uses the tag to determine what algorithm to use and then uses that algorithm to decode the encoded password.

Java clients use passwords from the sas.client.props file (which is located in the properties subdirectory of the user instance root, for example /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/default/properties). To use password encoding with Java clients, the passwords must be manually encoded in the sas.client.props file using the PropFilePasswordEncoder tool.

WebSphere administrative commands use passwords from the soap.client.props file (also located in the properties subdirectory) for SOAP connections, and some administrative commands optionally use passwords from the sas.client.props file (in the properties subdirectory) for RMI connections. To use password encoding with WebSphere administrative commands, the passwords must be manually encoded in the soap.client.props and sas.client.props files using the PropFilePasswordEncoder tool.

What password encoding is not

Whether you select to use the OS400 encoding algorithm or the default encoding algorithm, encoding is not sufficient to fully protect passwords. Native security is the primary mechanism for protecting passwords used in WebSphere configuration and property files.

Issues to consider when using the OS400 password encoding algorithm

There are important issues to consider before deciding to use the OS400 password encoding algorithm:

• Use of the OS400 password algorithm requires that the OS/400 system value QRETSVRSEC be set to 1, on the system hosting the Java client application or WebSphere server, to allow retrieval of the encrypted passwords from the validation list. Note that the QRETSVRSEC system value effects access to the encrypted data in all of the validation lists on your iSeries system.

  Note: Do not use the OS400 password encoding algorithm if this setting is not consistent with your iSeries system security policy.

• Only use the OS400 algorithm with server instances when all server instances within the WebSphere administrative domain reside on the same iSeries system:
  • WebSphere administrative domains can extend across multiple iSeries systems. The OS400 password algorithm may only be used when all of the servers within an administrative domain reside on the same iSeries system.
  • Server configuration (XML) files contain encoded passwords. If the passwords contained in XML files are encoded using the OS400 encoding algorithm, those encodings can only be valid for WebSphere server instances on the same iSeries system on which the passwords were originally encoded. Thus, copies of configuration files containing passwords encoded using the OS400 encoding algorithm cannot be used to configure servers on other iSeries systems.
  • Additionally, all WebSphere server instances within an administrative domain must be configured to use the same native validation list (*VLDL) object.

• For Java clients, the OS400 password algorithm may be used on any iSeries system, however option 1 must be installed on the system hosting the Java client.

• If an error occurs while encoding a password using the OS400 encoding algorithm, the XOR encoding algorithm will be used to encode the password. Such an error would occur for instance if an administrator manually creates the validation list object and grants insufficient authority to the validation list object for the OS/400 user profile QEJB.

Enabling the OS400 password encoding algorithm for a WebSphere instance

To enable the OS400 password encoding algorithm for a WebSphere instance, perform these steps:

1. Set the os400.security.password properties to turn on the OS400 password encoding algorithm and to specify the validation list object to use.

   IBM recommends that you use the same validation list object for all WebSphere instances on the iSeries system. An exception would be if you do not backup the objects and data for all instances simultaneously. Consider your backup and restore policy when deciding what validation list object to use for each WebSphere instance.

   To set the properties, perform one of these steps:

   • Use the -os400passwords and -validationlist options of the wasprofile -create utility (located in the bin subdirectory of the product installation, for example /QIBM/ProdData/WebSphere/AppServer/V6/Base/bin) to set the properties when creating the instance. For example, to create a WebSphere instance named prod and enable that instance for the OS400 encoding algorithm using the validation list object /QSYS.LIB/QUSRSYS.LIB/WAS.VLDL, you would do this:
     1. Run the Start Qshell (STRQSH) command on the OS/400 command line.
     2. In Qshell, run this command:

        was_install_root/bin/wasprofile -create -profileName prod -startingPort 10150 -templatePath default -os400passwords -validationlist  /QSYS.LIB/QUSRSYS.LIB/WAS.VLDL
          
        
        
        

   • Set Java system properties in the setupCmdLine Qshell script of the WebSphere instance (which is located in the bin directory of the user instance). For example, to enable the OS400 password encoding algorithm for the default instance, edit /QIBM/UserData/WebSphere/AppServer/V6/Base/default/bin/setupCmdLine:
     1. Set the property os400.security.password.encoding.algorithm to OS400. The default setting is XOR.
     2. Set the property os400.security.password.validation.list.object to the absolute name of the validation list you wish to use. The default setting is /QSYS.LIB/QUSRSYS.LIB/EJSADMIN.VLDL.
     3. Save the file.

2. Grant the QEJB user profile execute authority (*X) to the library that contains the validation list. If QEJB already has the minimum required authority (*X) to the library then proceed to the next step.

   For example, if the validation list is created in /QSYS.LIB/WSADMIN.LIB, use the Display Authority (DSPAUT) to check for the minimum required authority:

     DSPAUT OBJ('/QSYS.LIB/WSADMIN.LIB')

   Then use the Change Authority (CHGAUT) command to grant execute authority to QEJB (only if QEJB does not already have execute authority). For example:

     CHGAUT OBJ('/QSYS.LIB/WSADMIN.LIB') USER(QEJB) DTAAUT(*X)

3. Create a native validation list object (*VLDL). This step is optional for server instances. The validation list object will be created when the server is started. For remote instances, create the validation list if the validation list does not already exist on the system hosting the remote instance. Also, consider your backup and restore policy when deciding what validation list object to use with each remote instance.

   Note: When using the OS400 password encoding algorithm, the Java client is not required to reside on the same iSeries system as the WebSphere server instance that the client accesses.

   To create a validation list object, perform these steps with an OS/400 user profile with *ALLOBJ special authority:

   1. Signon the iSeries server with a user profile that has *ALLOBJ special authority.

   2. Use the Create Validation List (CRTVLDL) command to create the validation list object. For example, to create validation list object WSVLIST in library WSADMIN.LIB, use the following command:

        CRTVLDL VLDL(WSADMIN/WSVLIST)

   3. Grant the QEJB user profile *RWX authority to the validation list object. For example, to grant *RWX authority to the validation list object WSVLIST in library WSADMIN, use the following command:

      CHGAUT OBJ('/QSYS.LIB/WSADMIN.LIB/WSVLIST.VLDL') USER(QEJB) DTAAUT(*RWX)

4. Use the Change System Value (CHGSYSVAL) command to set the QRETSVRSEC system value to 1. For example:

     CHGSYSVAL SYSVAL(QRETSVRSEC) VALUE('1')

5. For server instances, start (or restart) the server and wait until the server is ready for service before attempting to manually encode passwords in properties files belonging to the instance.

Manually encoding passwords in properties files

Use the PropFilePasswordEncoder utility to encode the passwords in properties files. This Qshell script is available in WebSphere Application Server and WebSphere Application Server Network Deployment. To run the script, your user profile must have *ALLOBJ authority.

For example, to encode the passwords for properties in the sas.client.props file for the default WebSphere instance:

1. Signon the iSeries server with a user profile that has all object (*ALLOBJ) special authority.

2. Run the Start Qshell (STRQSH) command on an OS/400 command line to start the Qshell environment.

3. In Qshell, enter this command as a single line:

   /QIBM/ProdData/WebSphere/AppServer/V6/Base/bin/PropFilePasswordEncoder -profileName server1
    /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/default/properties/sas.client.props -SAS 

To encode passwords for properties in the soap.client.props file for the default Websphere instance:

1. Run the Start Qshell (STRQSH) command on an OS/400 command line to start the Qshell environment.

2. In Qshell, enter this command as a single line:

   /QIBM/ProdData/WebSphere/AppServer/V6/Base/bin/PropFilePasswordEncoder -profileName server1
    /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/default/properties/soap.client.props 
    com.ibm.SOAP.loginPassword,com.ibm.ssl.keyStorePassword,com.ibm.ssl.trustStorePassword

For more information, see The PropFilePasswordEncoder script.

Administration of validation list objects

Validation lists may be shared between multiple WebSphere instances. For example, if you have two instances of WebSphere Application Server, default and prod, both instances may use the validation list /QSYS.LIB/QUSRSYS.LIB/EJSADMIN.VLDL.

You should periodically save your validation list objects along with the other configuration data objects used by WebSphere Application Server. See Backup and recovery: Security for additional information.

Restore or replace damaged validation list objects. To replace a validation list object:

1. For all WebSphere instances that use the validation list object:
   1. Stop the servers.
   2. Set the property os400.security.password.validation.list.object for all servers to the absolute name of the new validation list you wish to use. You may use an existing validation list object or specify a new one. For new validation list objects, either create them manually, as specified above or they will be created when the server is restarted.
   3. Edit the configuration files and set each encoded password to the appropriate clear text value

2. Edit the sas.client.props and soap.client.props files. Set each encoded password to the appropriate clear text value, then manually encode the passwords.

3. Restart the servers for all WebSphere instances whose validation list objects were replaced.

Switching algorithms

To switch the encoding algorithm for a WebSphere instance:

1. For all WebSphere instances that use the validation list object, set the property os400.security.password.encoding.algorithm to OS400 or XOR. If using OS400 then complete enablement as described above in Enabling the OS400 password encoding algorithm for a WebSphere instance. If you stop with this step, then all passwords remain encoded with the old algorithm, but after restarting the server, future changes to passwords made using the administrative console results in those passwords being encoded with the new encoding algorithm.

2. Stop all servers.

3. Edit the configuration files and change all encoded passwords to their clear text values.

4. Edit the properties files and change all encoded passwords to their clear text values.

5. Restart the servers.

6. Encode the passwords in the properties files using the instructions in Manually encoding passwords in properties files.

Problem resolution

If a password cannot be decoded, for instance if a password encoding has become corrupted, do the following:

• If the password is contained in a server configuration file, then edit the file and set the password to the clear text value. Then restart the server.

• If the password is contained in the sas.client.props file or soap.client.props file, then edit the file and set the password to the appropriate clear text value. Finally, encode the password using the PropFilePasswordEncoder utility.

The instance specific setupCmdLine QShell script contains a property that allows you to obtain trace information when using the OS400 algorithm with Java clients and WebSphere administrative commands. To obtain the trace, set os400.security.password.debug=true. The trace is printed to standard output.

For more information, see Protecting plain text passwords.