Microsoft Windows Password Listener

The Windows Password Listener for Microsoft Windows environments captures passwords in clear text from the Windows Domain Controller and transfers them to the messaging service, where the User Password Event Manager picks them up for further processing. The Windows Password Listener captures only passwords of user accounts. For more information on password management, see the chapter "Password Management" in the DirX Identity Connectivity Administration Guide.

Architecture

The Windows Password Listener consists of two components:

Windows Password Listener Plug-in - A small component that is integrated as a dynamic link library (DLL) into the Windows domain controller’s Local Security Authority (LSA), to which it is registered as a password filter.
Windows Password Listener Service - A separate component that runs independently and thus cannot disturb the Windows domain controller operation.

Both components transfer all information in Unicode / utf-8 code set.

The following figure illustrates the architecture of the Windows Password Listener.

Figure 1. Windows Password Listener Architecture

Windows Password Listener Plug-In

The Windows Password Listener plug-in is a DLL that is based on the Microsoft Security Management Password Filters functions. Specifically, it uses the InitializeChangeNotify and PasswordChangeNotify functions, as follows:

During Windows domain controller start-up, the Password Listener plug-in calls the function InitializeChangeNotify to initialize the client.
Each time a password change occurs, the Password Listener plug-in calls the function PasswordChangeNotify. The client reads the certificate file that contains the public key, encrypts the password and writes it together with the account name into a password file. If the certificate file does not exist the password is encrypted with a default internal public key. As soon as a certificate file has been retrieved from the Java-based Server on Windows Password Listener service start-up, the password files are decrypted by the service with a default internal private key, encrypted with the certificate from the file and then sent to the Java-based Server. The name of these password files are
timestamp_rel_id, for example 20040629111230487_1107.

This interface generates a notification of any password change event.

Windows Password Listener Service

During start-up, the Windows Password Listener service reads its configuration file (options.ini) and tries to connect to the messaging service specified in ServerAddress and ServerPort. It requests the current certificate (public key for encryption) and writes it into a file to be used by the Windows password listener plug-in (CertFileName). During start-up, it also requests the list of messaging services from a Java-based Server with a ConfigurationHandler adaptor configured and active and writes them into the file specified in MsgSrvFile (default = msgServers.ini). The file is always updated when a current list of messaging services is received from the Java-based Server. The Java-based Server repeats sending it at an interval configured in the specific attribute broadcastinterval of the ConfigurationHandler adaptor. The MsgSrvFile is deleted on update and upgrade installations to make sure that the service tries to connect to the messaging service specified during installation and not to the first - possibly outdated one-listed in the MsgSrvFile.

If at some time later the Windows Password Listener service loses the connection to the original messaging service, it tries to connect to one of the messaging services listed in MsgSrvFile processing one after another. The timing behavior for building up a connection to a messaging service can be controlled with the parameters Timeout, Repeat and RetryInterval. Once a connection to another messaging service succeeds this messaging service and its host name, messaging port, SSL and client authentication flag is written to the MsgSrvFile as the first one in the list of messaging services. These parameters are also written back to the options.ini file, so that on the next Windows Password Listener service restart this messaging service is tried first to connect to.

The Windows Password Listener service checks for existing password files in the directory DirectoryPasswordFiles, reads them, adds the additional information forest name, domain name, computer name and the "User must change password during next login" flag depending on whether the password was reset by an administrator (flag is set to 1) or by the user itself (flag is set to 0) and then sends each password change request via the messaging service to the Java-based Server. If successful, it deletes the password file and then waits for further password changes.

If the Password Listener service, when processing a password file, recognizes that the assigned user no longer exists in Active Directory or that access to the user is denied, it writes a warning message to the Event Viewer and moves the password file to the folder PasswordFiles_moved residing parallel to the PasswordFiles folder.

The operating system automatically notifies the Windows Password Listener service when a password file is created. The service then reads the password file, processes it and deletes it if send successfully.

Configuration File Format

The Windows Password Listener plug-in and service components are controlled by different configuration files. The next sections identify these files and describe the parameters in them that control the plug-in or service. Most of these parameters are set automatically by the installation procedure.

Windows Password Listener Plug-In Configuration File

The libdxmEventListenerAds.ini file contains parameters that control the operation of the Windows password listener plug-in. The file is located in the directory

install_path\conf

Settings

ListenerActive: controls whether the event listener can be deactivated without rebooting the Windows domain controller machine. A value of 1 means active, a value of 0 means inactive (default: 1). This flag is checked during each password change operation.
Trace: defines the trace level for the information written to the Event Viewer and the file defined in the LogFile parameter of the File Definitions section:
0 - no trace (default)
1 - write warnings to Event Viewer
2 - write warnings and infos to Event Viewer
3 - write warnings and infos to Event Viewer and more detailed tracing to LogFile

File Definitions

DirectoryPasswordFiles: the directory where the intermediate encrypted password files are stored (default: install_path*\PasswordFiles*)
CertFileName: the name of the file that contains the current certificate to be used for encryption of the passwords (default: install_path\CertFile\Certificate.txt)
LogFile: the path and name of the file where trace information is written to (see the Trace parameter above). The default location is: install_path\log\dxmEventListener.log.

Encryption Parameters

EncrLogLevel: the log level for the encryption module. The value is an integer in the range 1 (minimal logging) to 10 (maximum logging) (default: 1)
EncrLogFile: the location where the encryption module writes log information (default: install_path\log\dxmEventListener_dxc_crypt.log).

EncrRandomFile - the random file that the encryption mechanism uses (default: install_path\log\dxmEventListener_dxc_rand.dat).

WaitTime - the time (in milliseconds) that the plug-in is to wait for the certificate (default: 5000 ms).

This section is not intended to be used by the customer directly. Support personnel will instruct the customer to use this feature in case of specific errors. Normally all error information is reported to the Windows Event Viewer.

Windows Password Listener Service Configuration File

The options.ini file contains parameters that control the operation of the Windows Password Listener service. The file is located in the directory

install_path\conf

Settings

Trace: defines the trace level for the information written to the Event Viewer and the file defined in the LogFile parameter of the File Definitions section:*
0* - no trace (default)*
1* - write warnings to Event Viewer
2 - write warnings and infos to Event Viewer
3 - write warnings and infos to Event Viewer and more detailed tracing to LogFile

Message Server

ServerAddress: the messaging service address.
ServerPort: the messaging service port.
ServerDisplayName: the display name of the Java-based Server that contains the messaging service. It is used as the section name of a messaging service in the MsgSrvFile.
PollingTime: the time in seconds that the service is to wait for messages at the messaging interface (default: 5 seconds).
MessageLifeTime: the expiration time of sent messages (default: 86400 seconds = 1 day). The messaging service automatically deletes timed-out messages.
WaitTime: the time (in milliseconds) that the service is to wait for access to a semaphore to avoid deadlocks (default: 5000 milliseconds).
Timeout: the time (in seconds) that the service is to wait for a connection when attempting to connect to the messaging service during start-up. (default: 30 seconds).
Repeat: the number of connection retries the service is to make to the messaging service when the Timeout parameter is reached (default: 10).
RetryInterval: interval to retry a connect operation to the messaging service after a temporary problem (for example network was not available). Default is 15 minutes.
UseSSL: if set to 1, the messaging service works with SSL (default: 0).

Messages

SubscriberQueue: the name of the message queue that is to receive messages (default: Dxm.event.QUEUE)
CommandPrefix: the name of the command prefix (default: dxm.event)
Stream: the internal queue (default: Dxm.event.STREAM)
SendPasswordTopicSuffix: the suffix of the topic to which password change requests are sent (default: pwd.changed, which is combined with the CommandPrefix to result in dxm.event.pwd.changed).
DomainTopicPrefix: the domain name prefix (default: My-Company) of the topic to which password change requests are sent. By default this key is set into comment. You should uncomment it and specify your own domain. Then the password change requests are combined with the domain name prefix resulting in domain_name*.dxm.event.pwd.changed*, for example, My-Company.dxm.event.pwd.changed. In this case, a Java-based Server configured to this domain and which has the flag Include domain into topic set receives these requests.
SendReqConfTopic: the topic to which configuration requests are sent. Configuration requests are sent with the appropriate flag for getting either the certificate or the list of configured messaging services. If a domain topic prefix is specified, it is prefixed to this request configuration topic.
ReceiveConfTopic: the topic to which a durable subscriber is created from where the requested or updated certificate or messaging service list is read. If a domain topic prefix is specified, it is prefixed to this response configuration topic.
ExpirationTime: the time at which the sent messages expire (at which the messaging service automatically deletes it). This parameter is used for both password and certificate requests (default: 24 hours). Setting an expiration time prevents sent messages from remaining indefinitely in the system.

File Definitions

CertFileName: the location where the certificate file is to be stored (default: install_path*\CertFile\Certificate.txt*).
DirectoryPasswordFiles: the location where the encrypted password change request files are written (default: install_path\PasswordFiles).
LogFile: the path and name of the file where trace information is written to (see the Trace parameter above). The default location is: install_path\log\dxmWinPwListener.log.
MsgSrvFile: the path and name of the file to which the list of messaging services is written at start-up. The default location is: install_path\conf\msgServers.ini.

Encryption Parameters

EncrLogLevel: the log level for the encryption module. The value is an integer in the range 1 (minimal logging) to 10 (maximum logging) (default: 1).
EncrLogFile: the location where the encryption module writes log information (default: install_path\log\dxmWinPwListener_dxc_crypt.log).
EncrRandomFile: the random file that the encryption mechanism uses (default: install_path\conf\dxmWinPwListener_dxc_rand.dat).

+ NOTE: This section is not intended to be used by the customer directly. Support personnel will instruct the customer to use this feature in case of specific errors. Normally, all error information is reported to the Windows Event Viewer.

Error Handling

The Windows Password Listener can handle the following error situations:

Windows Password Listener plug-in - if the certificate file is not available or readable, the Windows password listener plug-in encrypts incoming passwords with the default internal public certificate.
Windows Password Listener plug-in - because DirX Identity can only partially work with the full Unicode character set, the Windows Password Listener blocks password changes for account names containing Unicode characters that cannot be transformed to Latin 1 character set. The plug-in writes a message to the Windows Event Viewer (Application Log).
Windows Password Listener service - the configuration file is not available or not readable or it contains incorrect parameters. The service writes an error message to the Windows Event Viewer (Application Log).
Windows Password Listener service - the certificate cannot be retrieved from the Java-based Server during startup of the Windows Password Listener service (due to an unavailable messaging service or a non-existing certificate in the Connectivity LDAP directory or an inactive ConfigurationHandler adaptor). In this case, the certificate file cannot be written and the service cannot process password change requests. The Windows Password Listener service checks regularly for the certificate’s availability. When the certificate can be retrieved, the Windows Password Listener service starts to process the existing password files: it decrypts each password with the default internal private key, encrypts it with the retrieved public key and sends it to the Java server via the messaging service.