Password encoding

  1. What password encoding is
  2. What password encoding is not
  3. Issues to consider when using the OS400 password encoding algorithm
  4. Enabling the OS400 password encoding algorithm for a WebSphere instance
  5. Manually encoding passwords in properties files
  6. Protecting plain text passwords
  7. Administration of validation list objects
  8. Switching algorithms
  9. 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 WAS 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 WAS 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/WebAS5/Base/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:

 

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.

    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 crtwasinst utility (located in the bin subdirectory of the product installation, for example /QIBM/ProdData/WebAS5/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: 
          /QIBM/ProdData/WebAS5/Base/bin/crtwasinst -instance prod -portblock 10150
     -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/WebAS5/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 WAS and WAS 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/WebAS5/Base/bin/PropFilePasswordEncoder -instance server1
 /QIBM/UserData/WebAS5/Base/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/WebAS5/Base/bin/PropFilePasswordEncoder -instance server1
 /QIBM/UserData/WebAS5/Base/default/properties/soap.client.props 
 com.ibm.SOAP.loginPassword,com.ibm.ssl.keyStorePassword,com.ibm.ssl.trustStorePassword

For more information, see The PropFilePasswordEncoder script in the Administration topic.

If you use a text file to store user IDs and passwords for applications that run outside the WAS process (such as an application client or another server), use the EncAuthDataFile script to encode the passwords. For more information, see The EncAuthDataFile script in the Administration topic.

 

Protecting plain text passwords

The WAS has several plain text passwords. These passwords are not encrypted, but are encoded. The following is a list of files with encoded passwords:

File name Additional information
security.xml The following fields contain encoded passwords:

  • LTPA password

  • JAAS Auth Data

  • User Registry server password

  • LDAP User Registry bind password

  • Key file password

  • Trust file password

  • Crypto token device password
sas.client.props  
war/WEB-INF/ibm_web_bnd.xml Specify passwords for the default basic authentication for the resource-ref bindings within all descriptors (except in the Java crytography architecture).
ejb jar/META-INF/ibm_ejbjar_bnd.xml Specify passwords for the default basic authentication for the "resource-ref" bindings within all descriptors (except in the Java crytography architecture)
client jar/META-INF/ibm-appclient_bnd.xml Specify passwords for the default basic authentication for the "resource-ref" bindings within all descriptors (except in the Java crytography architecture)
ear/META-INF/ibm_application_bnd.xml Specify passwords for the default basic authentication for the "run as" bindings within all descriptors
server.xml The following fields contain encoded passwords:

  • key file password

  • trust file password

  • crypto token device password

  • auth target password

  • Session persistence password

  • DRS Client data replication password (not available in WebSphere Application Server, Version 5
resource.xml (for cells, servers, and nodes) The following fields contain encoded passwords:

  • WAS40Datasource password

  • mailTransport password

  • mailStore password

  • MQQueue queue mgr password
ws-security.xml  
ibm-webservices-bnd.xmi  
ibm-webservicesclient-bnd.xmi  
/properties/soap.client.props  
/properties/sas.tools.properties  
/properties/sas.stdclient.properties  
wsserver.key  

 

Administration of validation list objects

Validation lists may be shared between multiple WebSphere instances. For example, if you have two instances of WAS, 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 WAS. See Save and restore: Security in the Administration topic 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:

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.