Obtaining Identity Information
The vendor that implements the authentication protocol may also provide a function interface that obtains initial identifying information for the user requesting authentication.
The vendor should implement the following functions.
These functions may be implemented in the same DLL as the authentication protocol, or in a separate DLL. Also, the DLL that implements the identity functions may support more than one authentication protocol. The path to the DLL for these functions is stored in the RAS_EAP_VALUENAME_IDENTITY registry value, under the key for the authentication protocol. For more information about creating this registry value, see EAP Installation.
The RasEapGetIdentity function typically displays a user interface (UI) to obtain identity information for the user. However, if the dwFlags parameter contains the RAS_EAP_FLAG_NON_INTERACTIVE flag, RasEapGetIdentity should not display a UI.
If RasEapGetIdentity does display a UI, the UI must support WM_COMMAND messages where the value of LOWORD (wParam) is equal to IDCANCEL.
The authentication service calls RasEapGetIdentity if the RAS_EAP_VALUENAME_INVOKE_NAMEDLG value that is in the registry for this EAP is set to zero. If RAS_EAP_VALUENAME_INVOKE_NAMEDLG is not present, or is present and is set to one, the authentication service displays the standard system user name dialog box.
In addition to RAS_EAP_VALUENAME_INVOKE_NAMEDLG, the EAP vendor may create a related value, RAS_EAP_VALUENAME_INVOKE_PWDDLG, in the registry. If this value is present and is set to zero, the service will not display the standard system password dialog. This value is useful when implementing a biometric method such as a fingerprint scan to authenticate the user. If both the RAS_EAP_VALUENAME_INVOKE_NAMEDLG and RAS_EAP_VALUENAME_INVOKE_PWDDLG values are zero, an identity UI could be used to obtain both the identity and biometric information. However, if only RAS_EAP_VALUENAME_INVOKE_PWDDLG is zero, the authentication service will not call RasEapGetIdentity. In this case, you could use the interactive user interface to obtain the biometric information.
For more information on these registry values, see Authentication Protocol Registry Values.
The information obtained by RasEapGetIdentity is passed to the authentication protocol during the call to RasEapBegin. The information is pointed to by the pszIdentity and pUserData members of the PPP_EAP_INPUT structure. To save this information in the registry on the client computer, the authentication protocol should return the information in the pEapOutput parameter of RasEapMakeMessage.
After the call to RasEapBegin, the authentication service calls RasEapFreeMemory to free the memory occupied by this data. Therefore, the authentication protocol should copy the information into a private memory buffer during the call to RasEapBegin.