An authentication mechanism that plugs into LASS is called a Local Authentication Plugin (LAP). Access to a plugin is governed by an Authentication Event (AE) that represents the point at which a predefined policy (or rule) is applied to determine if a user needs to be authenticated.

Creating a LAP

The password LAP that is available by default in Windows CE can be replaced by a customized LAP if you want to have an alternate mechanism to authenticate the user. The custom LAP will be called exclusively by LASS on behalf of applications that need to authenticate a user.

To create a LAP, you must create a DLL with the following entry points:
• InitLAP (function)
• DeinitLAP
• LAPCreateEnrollmentConfigDialog
• VerifyUser (LAP)
• VerifyUserStart
• VerifyUserStop
• VerifyUserToTop

In addition, the LAP should support the following optional entry points:
• LAPCancelVerifySequence
• LAPDisplayCodeword
• LAPDisplayPreWipe
• LAPLockoutUser

In Windows Mobile-based devices, the LAP DLL must run privileged. The DLL must be signed with a privileged certificate.

LASS will call InitLap before the LAP is ever used. The active LAP is loaded on startup, and will remain loaded until it is changed. LASS will call DeinitLAP prior to unloading the LAP. No more calls can be made to the LAP after this call is made.

An application call to the LASS function VerifyUser is passed on to VerifyUser (LAP) if the AE policy requires it. When it receives this call, the LAP should validate the user. Note that if the flag VUNOUI is set, the LAP must not display UI.
LAPCreateEnrollmentConfigDialog is called when the application calls CreateEnrollmentConfigDialog.. In general, only the Shell will call this function.

LAP Implementation Details

When creating a LAP, keep in mind the following implementation issues:
• Often LAPs require a fallback mechanisim. For example, in the case of a fingerprint LAP, there is often an ability to enter a strong password if the fingerprint recognition engine fails. Such mechanisms are LAP-dependent, and must be implemented in the LAP itself.
• When LASS makes the following calls, a global LASS lock is held. As a result, LAPs should not block any longer than necessary when implementing these calls:
• VerifyUserStart
• VerifyUserStop
• VerifyUser with VUNOUI flag set
• LAPCancelVerifySequence
• If a LAP spawns a new thread, the newly created thread should not make any calls back into LASS. If it does, it is possible to cause a deadlock.
• When you implement a LAP, it is important to consider what the behavior should be when VerifyUser is called before the user has been enrolled. The two recommended behaviors are:
• VerifyUser returns TRUE until the user enrolls.
• Enrollment is forced on the first call to VerifyUser.
The default password LAP implements the first option.
• When implementing the LAP-exported function LAPCancelVerifySequence, it is important to ensure the function always returns a failure whenever the LAP has determined the verification was unsuccessful
Applies to Windows Mobile 5.0 AKU2.0 and later
• LAP must use the startup flag for all windows.
All dialogs and other windows used in a LAP must have the WSEXABOVESTARTUP flag set in the window's EXSTYLE. This flag is defined in \public\shellw\oak\inc\wpcpriv.h. An enrollment window must have this flag if you are going to show it while the device is locked. For information on setting this style, see GWL_EXSTYLE in SetWindowLong.
• On devices with phone capabilities, LAP must enable emergency calls and DTMF.
To determine if a device has phone capabilities, you should query the registry key HKLM\System\State\Phone. The "Status" value will have bit 32 set if a phone is present. You should use the defined names for the registry value in \public\ossvcs\sdk\inc\snapi.h:
• SNPHONERADIOPRESENTROOT
• SNPHONERADIOPRESENTPATH
• SNPHONERADIOPRESENTVALUE
• SNPHONERADIOPRESENTBITMASK
To recognize when an emergency number is entered, you can use SHGetEmergencyCallList.
To place calls, you can use PhoneMakeCall.
To send DTMF tones during the call, you should post the WMCPROGSENDVKEYDTMF message to the CProg window. The CProg window can be found by looking for a window with class "MSCprog". The message is defined in \public\shellw\oak\inc\wpcpriv.h. The WPARAM for the message should be a TCHAR representing the DTMF character.
If you implement LAPDisplayCodeword or LAPLockoutUser, emergency dialing must also be available from those functions.
• LAP must set the registry entry for ActiveSync on-device authentication policy.
You must set the registry value HKLM\Security\Policies\Policies to 00001025 = 0 during installation or during the first enrollment. This is the Desktop Unlock policy (Security Policy ID 4133) and disallows users from authenticating with a password using desktop ActiveSync. When this policy is set to 0, the user will be required to authenticate using the installed LAP on the device. For more information, see the Security Policy Settings.
• LAP must set the lock timeout in the registry.
You must provide a way for the user to set the lock timeout. To enable the timeout, set values in the registry key HKLM\Comm\Security\LASSD\AE\{50C13377-C66D-400C-889E-C316FC4AB374}. The REGAEAUTHFREQTYPE value must be set to FTMinutesIdle to turn the timeout on, or FTEveryFV to turn the timeout off. The REGAEAUTHFREQVALUE should be set to the number of minutes until timeout. These values are defined in \public\common\sdk\inc\lass.h. For more information, see Setting an AE Policy.
You should show consideration for the timeout policies. You can find these policies in the registry key HKLM\Comm\Security\Policy\LASSD\AE\{50C13377-C66D-400C-889E-C316FC4AB374}. The same values are used in the same way to define the policy. If the timeout policy is type FTMinutesIdle, the policy is enforced and the user should not be allowed to change the timeout. You should only read the policies and not modify them.
• LAP should broadcast a WM_SETTINGS message when changing the timeout.
To notify the device that timeout settings have changed, the you must call PostMessage(HWNDBROADCAST, WMSETTINGCHANGE, 0, 0).
• LAP should implement a timer on VerifyUser (LAP) to prevent accidental attempts and emergency calls.
You should use a timer to cancel verification or clear any entered information after a period of idle time. This prevents random keypresses from accidentally dialing emergency phone numbers, and prevents accidental authentication attempts.
If you implement LAPDisplayCodeword or LAPLockoutUser, you should also use a timer to clear the entered information after a period of idle time.
The LAP may check for the "PasswordTimeout" value in the HKEYLOCALMACHINE\Security\Policies\Shell registry key to use for this timer.
• LAP should implement a mechanism in LAPCreateEnrollmentConfigDialog to prevent this dialog from staying up unnecessarily.
This prevents a user from leaving the enrollment window open and a malicious user entering new authentication data when the user is not paying attention.
• LAP should have a way to force enrollment if the auth required policy is set.
The "Password Required Policy" (Security Policy ID 4131) determines if a user must be enrolled for authentication on the device. When this policy changes, LASS will unload and reload the active LAP. When necessary, the LAP can call SHDeviceLockAndPrompt to lock the device and allow the LAP to force enrollment.
• LAP can implement their own policies and policy listener.
You can implement additional policies that are unique to your authentication mechanism. The sample password LAP uses "MinimumPasswordLength" and "ComplexElements" policies to set constraints on the password set by the user. A picture LAP could choose to have a policy that determines the picture file to be used for authentication. Policies can be set by IT Administrators. In this example, if the policy is not set the user can choose the picture to use. If the policy is set, this option would be disabled during enrollment and the user would not have a choice. Policies pertaining to a specific LAP should be set in the registry under HKLM\Comm\Security\Policy\LASSD inside a key specific to the LAP.
When you add LAP-specific policies, you may want to add them to the policy listener. The policy listener is a Shell feature that takes action when specific registry keys are updated, added, or deleted. It may copy the value to another location, remove the value from another location, reload the timeout settings, or reload the LASS/LAP settings based on configuration.
To add a registry key to the policy listener
1. Create a new registry key under HKEYLOCALMACHINE\Comm\Security\Policy\Listener. It must not overwrite an existing key, and the keys must be sequential integers.
2. Set the following values within this key.
Value Description
Key : REG_DWORD Location of the registry value to monitor. Valid values are 0 (zero) and 1.
• 0 - HKEYLOCALMACHINE
• 1 - HKEYCURRENTUSER
If the value does not exist, the application uses HKEYLOCALMACHINE.
Subkey : REG_SZ Registry path to monitor, such as "Comm\Security\Policy\LASSD\LAP\SampleLap."
ValueName : REG_SZ Name of registry value to monitor, such as "SamplePolicy."
CopyKey : REG_DWORD Location to copy the registry value to. Valid values are 0 (zero) and 1.
• 0 - HKEYLOCALMACHINE
• 1 - HKEYCURRENTUSER
If the value does not exist, the application uses the Key value.
CopySubKey : REG_SZ Registry path to copy the value to when changed. If this value does not exist, the application uses the SubKey value.
CopyValueName : REG_SZ Name of registry value to copy to when changed. If the value does not exist, the application uses the ValueName value.
PolicyType : REG_DWORD Type of policy that determines the action to take when changed.
• 0 - Standard (default if not present). Copy key is updated if master policy is on.
• 1 - Idle. Idle configuration is refreshed. In all other policy types, the standard configuration is refreshed.
• 2 - Master. Reserved for use by the master policy.
PolicyAttributes : REG_DWORD Combination of flags.
0 - Normal (default if not present).
1 - PolicyDelete. CopyKey is updated if master policy is on and deleted if master policy is off.
2 - PolicyIgnore. CopyKey is updated if master policy is on but not deleted if the original policy is deleted.
If CopyKey, CopySubKey, or CopyValueName are present, the value will be copied when it is changed with the exceptions in PolicyDelete and PolicyIgnore.
Applies to Windows Mobile 5.0 AKU2.0 and later
The password enrollment screen of the default LAP has two text entry fields for the user to enter a new password and confirm the password, and therefore requires the use of the d-pad. Because the default LAP cannot be removed from the device, it must work; you should allow the user to navigate using the d-pad even when the device is in locked state.