298 lines
18 KiB
HTML
298 lines
18 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<LINK rel="stylesheet" type="text/css" href="../../../rzahg/ic.css">
|
||
|
|
|
||
|
|
<title>Password encoding</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<BODY>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<SCRIPT LANGUAGE="Javascript" SRC="../../../rzahg/synch.js" TYPE="text/javascript"></SCRIPT>
|
||
|
|
|
||
|
|
<h2><a name="encoding"></a>Password encoding</h2>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="#whatis">What password encoding is</a></li>
|
||
|
|
<li><a href="#isnot">What password encoding is not</a></li>
|
||
|
|
<li><a href="#issues">Issues to consider when using the OS400 password encoding
|
||
|
|
algorithm</a></li>
|
||
|
|
<li><a href="#enable_server">Enabling the OS400 password encoding algorithm
|
||
|
|
for a WebSphere instance</a></li>
|
||
|
|
<li><a href="#use_client">Manually encoding passwords in properties files</a></li>
|
||
|
|
<li><a href="#protect">Protecting plain text passwords</a></li>
|
||
|
|
<li><a href="#admin_object">Administration of validation list objects</a></li>
|
||
|
|
<li><a href="#switch">Switching algorithms</a></li>
|
||
|
|
<li><a href="#problem">Problem resolution</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><a name="whatis"></a><strong>What password encoding is</strong></p>
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>The default encoding algorithm is referred to as XOR. An alternate OS400 encoding algorithm can be used only with WebSphere Application Server - Express 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.</p>
|
||
|
|
|
||
|
|
<p>Properties of the WebSphere Application Server - Express instance control which algorithm to use for encoding the passwords.</p>
|
||
|
|
|
||
|
|
<p>Encoded passwords are of this form:</p>
|
||
|
|
<pre> {<em>algorithm</em>}<em>encoded_password</em></pre>
|
||
|
|
|
||
|
|
<p>where {<em>algorithm</em>} is a tag that specifies the algorithm used to encode the password (either XOR or OS400), and <em>encoded_password</em> 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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p><a name="isnot"></a><strong>What password encoding is not</strong></p>
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p><a name="issues"></a><strong>Issues to consider when using the OS400 password encoding algorithm</strong></p>
|
||
|
|
<p>There are important issues to consider before deciding to use the OS400 password encoding algorithm:</p>
|
||
|
|
<ul>
|
||
|
|
<li><p>Use of the OS400 password algorithm requires that the i5/OS system value QRETSVRSEC be set to 1, on the system hosting the 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.</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> Do not use the OS400 password encoding algorithm if this setting is not consistent
|
||
|
|
with your iSeries system security policy.</p></li>
|
||
|
|
|
||
|
|
<li><p>Only use the OS400 algorithm with server instances when all server instances within the WebSphere administrative domain reside on the same iSeries system:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>Additionally, all WebSphere server instances within an administrative domain must be configured to use the same native validation list (*VLDL) object.</li>
|
||
|
|
</ul><p></p></li>
|
||
|
|
|
||
|
|
<li><p>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 i5/OS user profile QEJB.</p></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><a name="enable_server"></a><strong>Enabling the OS400 password encoding algorithm for a WebSphere instance</strong></p>
|
||
|
|
<p>To enable the OS400 password encoding algorithm for a WebSphere instance, perform these steps:</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li><p>Set the os400.security.password properties to turn on the OS400 password encoding algorithm and to specify the validation list object to use.</p>
|
||
|
|
|
||
|
|
<p>It is recommended 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.</p>
|
||
|
|
|
||
|
|
<p>To set the properties, perform one of these steps:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><p>Use the -os400passwords and -validationlist options of the crtwasinst utility (located in the bin subdirectory of the product installation, for example /QIBM/ProdData/WebASE/ASE5/bin) to set the properties when creating the instance. For example, to create a WebSphere instance named <tt>prod</tt> and enable that instance for the OS400 encoding algorithm using the validation list object /QSYS.LIB/QUSRSYS.LIB/WAS.VLDL, you would do this:</p>
|
||
|
|
|
||
|
|
<ol type="a">
|
||
|
|
<li>Run the Start Qshell (STRQSH) command on the CL command line.</li>
|
||
|
|
<li>In Qshell, run this command:
|
||
|
|
<pre> /QIBM/ProdData/WebASE/ASE5/bin/crtwasinst -instance prod -portblock 10150
|
||
|
|
-os400passwords -validationlist /QSYS.LIB/QUSRSYS.LIB/WAS.VLDL</pre></li>
|
||
|
|
</ol></li>
|
||
|
|
|
||
|
|
<li><p>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 an instance, edit /QIBM/UserData/WebASE/ASE5/<em>instance</em>/bin/setupCmdLine where <em>instance</em> is the name of your instance:</p>
|
||
|
|
|
||
|
|
<ol type="a">
|
||
|
|
<li>Set the property <strong>os400.security.password.encoding.algorithm</strong> to <tt>OS400</tt>. The default setting is <tt>XOR</tt>.</li>
|
||
|
|
<li>Set the property <strong>os400.security.password.validation.list.object</strong> to the absolute name of the validation list you wish to use. The default setting is <tt>/QSYS.LIB/QUSRSYS.LIB/EJSADMIN.VLDL</tt>.</li>
|
||
|
|
<li>Save the file.</li>
|
||
|
|
</ol><p></p></li>
|
||
|
|
</ul></li>
|
||
|
|
|
||
|
|
<li><p>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.</p>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<pre> DSPAUT OBJ('/QSYS.LIB/WSADMIN.LIB')</pre>
|
||
|
|
|
||
|
|
<p>Then use the Change Authority (CHGAUT) command to grant execute authority to QEJB (only
|
||
|
|
if QEJB does not already have execute authority). For example:</p>
|
||
|
|
|
||
|
|
<pre> CHGAUT OBJ('/QSYS.LIB/WSADMIN.LIB') USER(QEJB) DTAAUT(*X)</pre></li>
|
||
|
|
|
||
|
|
<li><p>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.</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>To create a validation list object, perform these steps with an i5/OS user profile with *ALLOBJ special authority:</p>
|
||
|
|
|
||
|
|
<ol type="a">
|
||
|
|
<li><p>Signon the iSeries server with a user profile that has *ALLOBJ special authority.</p></li>
|
||
|
|
<li><p>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:</p>
|
||
|
|
|
||
|
|
<pre> CRTVLDL VLDL(WSADMIN/WSVLIST)</pre></li>
|
||
|
|
|
||
|
|
<li><p>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:</p>
|
||
|
|
|
||
|
|
<pre>CHGAUT OBJ('/QSYS.LIB/WSADMIN.LIB/WSVLIST.VLDL') USER(QEJB) DTAAUT(*RWX)</pre></li>
|
||
|
|
</ol><p></p></li>
|
||
|
|
|
||
|
|
<li><p>Use the Change System Value (CHGSYSVAL) command to set the QRETSVRSEC system value to 1. For example:</p>
|
||
|
|
|
||
|
|
<pre> CHGSYSVAL SYSVAL(QRETSVRSEC) VALUE('1')</pre></li>
|
||
|
|
|
||
|
|
<li><p>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.</p></li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p><a name="use_client"></a><strong>Manually encoding passwords in properties files</strong></p>
|
||
|
|
<p>Use the PropFilePasswordEncoder utility to encode the passwords in properties files. This Qshell script is available in WebSphere Application Server - Express. To run the script, your user profile must have *ALLOBJ authority.</p>
|
||
|
|
|
||
|
|
<p>For example, to encode the passwords for properties in the sas.client.props file in your instance, perform the following steps:</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>Signon the iSeries server with a user profile that has all object (*ALLOBJ) special authority.</li>
|
||
|
|
|
||
|
|
<li>Run the Start Qshell (STRQSH) command on an CL command line to start the Qshell environment.</li>
|
||
|
|
|
||
|
|
<li>In Qshell, enter this command as a single line:
|
||
|
|
|
||
|
|
<pre>/QIBM/ProdData/WebASE/ASE5/bin/PropFilePasswordEncoder -instance <em>instance</em>
|
||
|
|
/QIBM/UserData/WebASE/ASE5/<em>instance</em>/properties/sas.client.props -SAS </pre>
|
||
|
|
|
||
|
|
<p>where <em>instance</em> is the name of your server instance.</p></li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>To encode passwords for properties in the soap.client.props file in an instance named <tt>myInst</tt>:</p>
|
||
|
|
<ol>
|
||
|
|
|
||
|
|
<li>Run the Start Qshell (STRQSH) command on an CL command line to start the Qshell environment.</li>
|
||
|
|
|
||
|
|
<li>In Qshell, enter this command as a single line:
|
||
|
|
|
||
|
|
<pre>/QIBM/ProdData/WebASE/ASE5/bin/PropFilePasswordEncoder -instance myInst
|
||
|
|
/QIBM/UserData/WebASE/ASE5/myInst/properties/soap.client.props
|
||
|
|
com.ibm.SOAP.loginPassword,com.ibm.ssl.keyStorePassword,com.ibm.ssl.trustStorePassword</pre></li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>For more information, see <a href="../admin/qshpropenc.htm">The PropFilePasswordEncoder script</a> in the <em>Administration</em> topic.</p>
|
||
|
|
|
||
|
|
<p>If you use a text file to store user IDs and passwords for applications that run outside the WebSphere Application Server - Express process (such as another server), use the EncAuthDataFile script to encode the passwords. For more information, see <a href="../admin/qshencdata.htm">The EncAuthDataFile script</a> in the <em>Administration</em> topic.</p>
|
||
|
|
|
||
|
|
<p><a name="protect"></a><strong>Protecting plain text passwords</strong></p>
|
||
|
|
|
||
|
|
<p>WebSphere Application Server - Express has several plain text passwords. These passwords are not encrypted, but are encoded. The following is a list of files with encoded passwords:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="3" cellspacing="0">
|
||
|
|
<tr valign="top">
|
||
|
|
<th>File name</th>
|
||
|
|
<th>Additional information</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>security.xml</td>
|
||
|
|
<td>The following fields contain encoded passwords:<ul>
|
||
|
|
<li><strong>LTPA password</strong></li>
|
||
|
|
<li><strong>JAAS Auth Data</strong></li>
|
||
|
|
<li><strong>User Registry server password</strong></li>
|
||
|
|
<li><strong>LDAP User Registry bind password</strong></li>
|
||
|
|
<li><strong>Key file password</strong></li>
|
||
|
|
<li><strong>Trust file password</strong></li>
|
||
|
|
<li><strong>Crypto token device password</strong></li>
|
||
|
|
</ul></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>war/WEB-INF/ibm_web_bnd.xml</td>
|
||
|
|
<td>Specify passwords for the default basic authentication for the <tt>resource-ref</tt> bindings within all descriptors (except in the Java crytography architecture).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>server.xml</td>
|
||
|
|
<td>The following fields contain encoded passwords:<ul>
|
||
|
|
<li><strong>key file password</strong></li>
|
||
|
|
<li><strong>trust file password</strong></li>
|
||
|
|
<li><strong>crypto token device password</strong></li>
|
||
|
|
<li><strong>auth target password</strong></li>
|
||
|
|
</ul></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>resource.xml (for cells, servers, and nodes)</td>
|
||
|
|
<td>The following fields contain encoded passwords:<ul>
|
||
|
|
<li><strong>mailTransport password</strong></li>
|
||
|
|
<li><strong>mailStore password</strong></li>
|
||
|
|
</ul></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>ws-security.xml</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>ibm-webservices-bnd.xmi</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>ibm-webservicesclient-bnd.xmi</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>/properties/soap.client.props</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>/properties/sas.tools.properties</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>/properties/sas.stdclient.properties</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr valign="top">
|
||
|
|
<td>wsserver.key</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
|
||
|
|
<p><a name="admin_object"></a><strong>Administration of validation list objects</strong></p>
|
||
|
|
|
||
|
|
<p>Validation lists may be shared between multiple WebSphere instances. For example, if you have two instances of WebSphere Application Server - Express, default and prod, both instances may use the validation list /QSYS.LIB/QUSRSYS.LIB/EJSADMIN.VLDL.</p>
|
||
|
|
|
||
|
|
<p>You should periodically save your validation list objects along with the other configuration data objects used by WebSphere Application Server - Express. See <a href="../admin/snrsecur.htm">Save and restore: Security</a> in the <em>Administration</em> topic for additional information.</p>
|
||
|
|
|
||
|
|
<p>Restore or replace damaged validation list objects. To replace a validation list object:</p>
|
||
|
|
<ol>
|
||
|
|
<li>For all WebSphere instances that use the validation list object:
|
||
|
|
<ol type="a">
|
||
|
|
<li>Stop the servers.</li>
|
||
|
|
<li>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.</li>
|
||
|
|
<li>Edit the configuration files and set each encoded password to the appropriate clear text value</li>
|
||
|
|
</ol></li>
|
||
|
|
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>Restart the servers for all WebSphere instances whose validation list objects were replaced.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p><a name="switch"></a><strong>Switching algorithms</strong></p>
|
||
|
|
<p>To switch the encoding algorithm for a WebSphere instance:</p>
|
||
|
|
<ol>
|
||
|
|
<li>For all WebSphere instances that use the validation list object, set the property <strong>os400.security.password.encoding.algorithm</strong> to <tt>OS400</tt> or <tt>XOR</tt>. If using OS400 then complete enablement as described above in <a href="#enable_server">Enabling the OS400 password encoding algorithm for a WebSphere instance</a>. 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.</li>
|
||
|
|
|
||
|
|
<li>Stop all servers.</li>
|
||
|
|
|
||
|
|
<li>Edit the configuration files and change all encoded passwords to their clear text values.</li>
|
||
|
|
|
||
|
|
<li>Edit the properties files and change all encoded passwords to their clear text values.</li>
|
||
|
|
|
||
|
|
<li>Restart the servers.</li>
|
||
|
|
|
||
|
|
<li>Encode the passwords in the properties files using the instructions in <a href="#use_client">Manually encoding passwords in properties files</a>.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p><a name="problem"></a><strong>Problem resolution</strong></p>
|
||
|
|
<p>If a password cannot be decoded, for instance if a password encoding has become corrupted, do the following:</p>
|
||
|
|
<ul>
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>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.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The instance-specific setupCmdLine QShell (located in the <tt>bin</tt> directory of your instance) 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 <tt>os400.security.password.debug=true</tt>. The trace is printed to standard output.</p>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|