Microsoft KB Archive/151082

{|
 * width="100%"|

HOWTO: Password Change Filtering & Notification in Windows NT

 * }

Q151082

-

The information in this article applies to:


 * Microsoft Win32 Software Development Kit (SDK), version 4.0

-

SUMMARY
This article describes the password change package facility that can be used to receive notification of password changes and can provide control over password quality.

The password change notification can be used to synchronize foreign account databases. Password change notification functionality is available on Windows NT 3.51 and later.

The password filter can provide strict control over the quality or strength of new passwords, and the PasswordFilter routine can indicate whether the new password is appropriate. Password filter functionality is only available on Windows NT 4.0 systems with Service Pack 2 installed.

NOTE: Other potential uses for this facility exist but are not discussed in this article.

CAUTION: Take great care when dealing with passwords in clear text (non- encrypted text). Sending passwords over the network in clear text could compromise security on the network because network "sniffers" can watch for such password traffic. Zeroing memory used to store passwords is recommended prior to freeing the memory. It is assumed that the reader of this article knows how to deal with password information in a secure manner.

The interface to this functionality may be subject to change in a future release of Windows NT.

Considerations that Apply to Password Change Events
 All buffers passed into the notification and filter routines should be treated as read-only. Writing any data to these buffers may cause undefined behavior. The notification and filter routines should be thread-safe. Use critical sections or other synchronization techniques to protect data where appropriate. The InitializeChangeNotify function is called when the password notify DLL is loaded. If this function returns FALSE, the DLL is unloaded. This function is provided to allow for password notify specific initialization that allows the password DLL to be used for other purposes. The PasswordFilter function is called when a password change has been requested. Such password-change events take place during account creation, administrative password over-ride, and user-specified password changes. If this function returns TRUE, the password is considered valid and the system continues to evaluate the password through any other password-change packages installed on the system. If this function returns FALSE, the password is considered invalid, and ERROR_ILL_FORMED_PASSWORD (1324) is returned to the source of the password change request. The PasswordChangeNotify function is called after successful filtering of the provided passwords and storage of the new password. The return value from PasswordChangeNotify is currently unused. For the current release of Windows NT, PasswordChangeNotify should always return STATUS_SUCCESS (0x00000000L). Notification and filtering only take place on the computer that houses the updated account. Keep this in mind when dealing with domain-user accounts. Notification on domain accounts only takes place on the Primary domain controller for the domain. Notification packages should be installed on all BDCs in a domain, in addition to the PDC, to allow notifications to continue in the event of server role changes.  The following registry entry, of type REG_MULTI_SZ, must be configured appropriately for this facility to be used:

     HKEY_LOCAL_MACHINE\ SYSTEM\ CurrentControlSet\ Control\ Lsa\ Notification Packages (value of type REG_MULTI_SZ)

Notification Packages contains a list of DLLs to be loaded and notified of password changes and password change requests. If this value does not exist in the registry, it must be created.  The following functions comprise the password change package:

<ul> InitializeChangeNotify</li> PasswordFilter</li> PasswordChangeNotify</li></ul>

Each function is optional and must be declared NTAPI or WINAPI to insure proper calling convention. Each function used must appear in the .DEF file used to build the DLL.</li> Unhandled exceptions encountered in these functions cause security related failures system-wide; structured exception handling should be used when appropriate.</li> The caller of the password-change function blocks until each function has completed. When appropriate, move lengthy processing to a separate thread prior to returning from PasswordChangeNotify or PasswordFilter.</li> The PasswordChangeNotify, PasswordFilter, and InitializeChangeNotify functions run in the security context of the Local System account.</li> The loading of notification packages is an auditable event through enabling of AuditCategorySystem "Restart, Shutdown, and System" audit event type.</li> Password change notification and password filters only support password changes initiated from Windows 95 and Windows NT clients. Password changes initiated by 16-bit Windows clients do not generate password notification events because they use a different password change protocol that cannot support password notification.</li></ol>

Microsoft Provided Password Filter DLL
System administrators who wish to increase password strength without having to write their own filter may use the password filter supplied by Microsoft along with Service Pack 2 for Windows NT 4.0. This filter, PASSFILT.DLL, will need to be copied to %system root%\SYSTEM32 after Service Pack 2 is installed on the system. To enable the filter follow steps 6 and 7 above.

PASSFILT.DLL implements the following password policy:

<ol> Passwords must be at least six (6) characters long.</li>  Passwords must contain characters from at least three (3) of the following four (4) classes:

<pre class="FIXEDTEXT">  Description                            Examples English Upper Case Letters            A, B, C, ... Z  English Lower Case Letters             a, b, c, ... z  Westernized Arabic Numerals            0, 1, 2, ... 9  Non-alphanumeric ("Special characters") E.g., punctuation symbols. </li> Passwords may not contain your user name or any part of your full name.</li></ol>

Strong Password Functionality Included with Windows 2000
The functionality described above for Windows NT 4.0 has been moved into the operating system security components for Windows 2000. Strong password enforcement can be enabled on Windows 2000 by opening the Local Computer Policy MMC snap-in and enabling the "Passwords must meet complexity requirements" setting in Computer Configuration\Windows Settings\Security Settings\Account Policies\Password Policies.

Sample Code
<pre class="CODESAMP">/*++

Copyright (c) 1995, 1996 Microsoft Corporation

Module Name:

pswdntfy.c

Abstract:

This module illustrates how to implement password change notification and password filtering in Windows NT 4.0.

Password change notification is useful for synchronization of      non-Windows NT account databases.

Password change filtering is useful for enforcing quality or      strength of passwords in an Windows NT account database.

This sample illustrates one approach to enforcing additional password quality.

Author:

Scott Field (sfield)   14-May-96

--*/

#include <windows.h>  #include "ntsecapi.h" // \mstools\samples\win32\winnt\security\include\

#ifndef STATUS_SUCCESS #define STATUS_SUCCESS ((NTSTATUS)0x00000000L) #endif

NTSTATUS NTAPI PasswordChangeNotify(                      PUNICODE_STRING UserName,                       ULONG RelativeId,                       PUNICODE_STRING Password                       ) /*++  Routine Description: This (optional) routine is notified of a password change. Arguments: UserName - Name of user whose password changed RelativeId - RID of the user whose password changed NewPassword - Cleartext new password for the user Return Value: STATUS_SUCCESS only - errors from packages are ignored. --*/   {      #ifdef DEBUG LPWSTR String; String = HeapAlloc(GetProcessHeap, 0,                  Password->Length + UserName->Length + (256*sizeof(WCHAR))); swprintf(String,              L"Password for account %.*ls (rid 0x%x) changed to %.*ls\n",               UserName->Length / sizeof(WCHAR),               UserName->Buffer,               RelativeId,               Password->Length / sizeof(WCHAR),               Password->Buffer              ); OutputDebugStringW( String ); ZeroMemory(String,         Password->Length + UserName->Length + (256*sizeof(WCHAR))); HeapFree(GetProcessHeap, 0, String); #endif return STATUS_SUCCESS; }  BOOL NTAPI PasswordFilter(      PUNICODE_STRING UserName,       PUNICODE_STRING FullName,       PUNICODE_STRING Password,       BOOL SetOperation       ) /*++

Routine Description:

This (optional) routine is notified of a password change.

Arguments:

UserName - Name of user whose password changed

FullName - Full name of the user whose password changed

NewPassword - Cleartext new password for the user

SetOperation - TRUE if the password was SET rather than CHANGED

Return Value:

TRUE if the specified Password is suitable (complex, long, etc). The system will continue to evaluate the password update request through any other installed password change packages.

FALSE if the specified Password is unsuitable. The password change on the specified account will fail.

--*/   {       BOOL bComplex = FALSE; // assume the password in not complex enough DWORD cchPassword; PWORD CharType; DWORD i;      DWORD dwNum = 0; DWORD dwUpper = 0; DWORD dwLower = 0;

//       // check if the password is complex enough for our liking by       // checking that at least two of the four character types are // present. //

CharType = HeapAlloc(GetProcessHeap, 0, Password->Length); if(CharType == NULL) return FALSE;

cchPassword = Password->Length / sizeof(WCHAR);

if(GetStringTypeW( CT_CTYPE1, Password->Buffer, cchPassword, CharType )) {

for(i = 0 ; i < cchPassword ; i++) {

//               // keep track of what type of characters we have encountered //

if(CharType[i] & C1_DIGIT) { dwNum = 1; continue; }

if(CharType[i] & C1_UPPER) { dwUpper = 1; continue; }

if(CharType[i] & C1_LOWER) { dwLower = 1; continue; }

if(!(CharType[i] & (C1_ALPHA | C1_DIGIT) )) {

//                   // any other character types make the password complex //

dwNum = 2;

break; }          } // for

//           // Indicate whether we encountered enough password complexity //

if( (dwNum + dwUpper + dwLower) >= 2 ) bComplex = TRUE;

ZeroMemory( CharType, Password->Length ); } // if

HeapFree(GetProcessHeap, 0, CharType);

return bComplex; }

BOOL NTAPI InitializeChangeNotify(      void       ) /*++

Routine Description:

This (optional) routine is called when the password change package is loaded.

Arguments:

Return Value:

TRUE if initialization succeeded.

FALSE if initialization failed. This DLL will be unloaded by the system.

--*/   {

#ifdef DEBUG OutputDebugString( TEXT("Initialize Change Notify called!\n") ); #endif

//       // initialize any critical sections associated with password change // events, etc.      //

return TRUE; }

/********

pswdntfy.def

LIBRARY pswdntfy

EXPORTS InitializeChangeNotify PasswordChangeNotify PasswordFilter

********/ Additional query words: 4.00 password notification authenticate sync

Keywords : _IK kbAPI kbKernBase kbGrpDSKernBase kbwin32sdkfaq

Issue type : kbhowto

Technology : kbWin32SDKSearch kbAudDeveloper kbSDKSearch kbWin32sSearch kbWin32SDK400