HOWTO: Password Change Filtering & Notification in Windows NT

MORE INFORMATION

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:
  • InitializeChangeNotify
  • PasswordFilter
  • PasswordChangeNotify
  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.
• Unhandled exceptions encountered in these functions cause security related failures system-wide; structured exception handling should be used when appropriate.
• 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.
• The following functions run in the security context of the Local System account: PasswordChangeNotify; PasswordFilter; InitializeChangeNotify.
• The loading of notification packages is an auditable event through enabling of AuditCategorySystem "Restart, Shutdown, and System" audit event type.
• 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.

Microsoft Provided Password Filter DLL

• Passwords must be at least six (6) characters long.
• Passwords must contain characters from at least three (3) of the following four (4) classes:

     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.
  						

• Passwords may not contain your user name or any part of your full name.

Strong Password Functionality Included with Windows 2000

Sample Code

/*++

   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
   
       Password - 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

   ********/