The IAPassword utility

Both the Integration Agent and the integration services' configuration files can include configuration settings that refer to files containing encrypted data. The IAPassword utility is a platform-independent Java program that an Integration Agent administrator can use to create and modify the contents of these encrypted files.

You must have installed a JRE on your system to run the password utility; see Add a JRE to your Integration Agent location.

Before using the Integration Agent, you must run the IAPassword utility twice: once to create a .wspasswd file and once to create a .passwd file (or any named file that matches the configuration in IAConfig.xml).

For example, the web service user account that the Integration Agent uses whenever it calls the RegisterIntegrationAgent, SubmitAPXML, or ReceiveAPXML web service methods is defined by the webservices-auth element of the Integration Agent's configuration file, as shown here:

<web-services-auth>

<user>IA_User</user>

<password><file>./.wspasswd</file></password>

<company>Default Company</company>

</web-services-auth>

To avoid storing the web service user's password in plain text, the Integration Agent decrypts the .wspasswd file and uses the single string contained within as the password element's actual value.

Similarly, an integration service's configuration files can contain encrypted elements (for example, integration user passwords and encrypted-constant elements) that get their values from encrypted files. Here's an example of an encrypted-constant:

<constants>

<constant name="device" type="string" overwrite="false">localhost</constant>

<constant name="my_first_constant">This is an auto-typed constant...</constant>

<encrypted-constant name="my_second_constant" type="string" overwrite="true">

<file>/tmp/.constant</file>

</encrypted-constant>

</constants>

You can find the IAPassword program in the following location:

• Windows: <IAHOME>\bin\iapassword.bat
• Linux: <IAHOME>/bin/iapassword.sh

IAPassword parameters

IAPassword accepts the following command-line parameters:

Parameter	Required	Description
--new <string>	Yes	Specifies the string to be stored in the encrypted file.
--old <string>	If the file already exists	Specifies the current string that is stored in the encrypted file.
--file <path>	No	The path of the encrypted file. This can be specified as absolute or as relative to the installation folder (NOT relative to the current directory). If not specified, the default value is <IAHOME>/conf/.passwd. (There's an example of how to change the Web Service password below.)

Examples

To change the web service user's password, use the following command:

iapassword --new "MyNewPassword" --old ia_user --file conf/.wspasswd

This command changes the contents of the file <IAHOME>/conf/.wspasswd to the string "MyNewPassword" (without quotes).

To create the encrypted-constant file, use the following command:

iapassword --new "This is a string constant..." --file /tmp/.constant

Whenever iapassword is executed, it logs messages via log4j to the <IAHome>\log\AlarmPointIAdmin.txt file. You can change this logging behavior by modifying the log4j configuration file at <IAHOME>/conf/cli/logl4j-bridge.xml.

Using the IAPassword utility to secure Integration Agent passwords

To create a new password file, open a command prompt, navigate to the <IAHome>\bin folder and type one of the following commands. We recommend that you surround the password with double quotes, since it prevents failure when non-alphanumeric characters are present in the password.

Windows

iapassword --new "mypassword01" --file conf/filename.passwd

Linux, AIX, other

./iapassword.sh --new "mypassword01" --file conf/filename.passwd

Non-alphanumeric characters in passwords

Passwords that contain non-alphanueric characters must be escaped so that they are not misinterpreted on the command line.

When the password is surrounded by double-quotes, IAPassword correctly handles punctuation characters and alphanumeric characters from the "English (United States)" locale. This includes the characters A-Z, a-z, 0-9 and the following characters:

~`!@#$%^&*()_+{}|[]\:;<>?,./

Spaces and double quote characters should not be used in passwords encrypted by the IAPassword utility.