The RasEapMakeMessagefunction controls the majority of the interaction between the authentication protocol and RAS. RasEapMakeMessageprocesses incoming EAP packets and creates EAP packets for transmission to the remote peer. It also processes events such as time outs and authentication completion.

If a message is received from the remote peer, RAS calls RasEapMakeMessage, passing a pointer to the received message in the pReceivePacketparameter.

If RAS calls RasEapMakeMessagewith pReceivePacketset to NULL, RAS is either initiating the dialog with the authentication protocol, or requesting that the protocol resend the last packet. The authentication protocol should determine which action RAS is taking based on its state and from the message context.

On return from RasEapMakeMessage, the value of the Actionmember of the PPP_EAP_OUTPUTstructure indicates what action, if any, RAS should take. The Actionmember takes values from the PPP_EAP_ACTIONenumerated type.

If Actionis EAPACTION_Send, EAPACTION_SendAndDone, EAPACTION_SendWithTimeout, or EAPACTION_SendWithTimeoutInteractive, RAS transmits the packet that is pointed to by the pSendPacketparameter to the remote peer.

The EAPACTION_SendWithTimeout value allows for a time out, after which time RAS assumes the link was lost, and disconnects the session.

The EAPACTION_SendWithTimeoutInteractive value allows an infinite amount of time out to occur. The authenticator should use this value when expecting user input on the client. This time out allows the user an unspecified amount of time to complete the required input.

If the Actionmember is EAPACTION_Done or EAPACTION_SendAndDone, RAS examines the dwAuthResultCodemember of PPP_EAP_OUTPUT. If dwAuthResultCodeis NO_ERROR, the authentication succeeded. If dwAuthResultCodeis a value other than NO_ERROR, the authentication failed. The error code returned for the failure case should come from Raserror.h, Mprerror.h, or Winerror.h. Possible return codes include, but are not limited to, the following:

• ERROR_NO_DIALIN_PERMISSION
  
  
• ERROR_PASSWD_EXPIRED
  
  
• ERROR_ACCT_DISABLED
  
  
• ERROR_RESTRICTED_LOGON_HOURS
  
  
• ERROR_AUTH_INTERNAL
  
  

In the case where Actionis EAPACTION_Done or EAPACTION_SendAndDone, the pUserAttributesmember should point to attributes that override attributes of the same type that were passed to the server in the call to RasEapBegin.

The authentication protocol can request that RAS invoke the current authentication provider by returning EAPACTION_Authenticate in the Actionmember in PPP_EAP_OUTPUT. In this case, the pUserAttributespointer in PPP_EAP_OUTPUTshould point only to attributes that were generated by the authentication protocol on the server. It need not include any of the attributes that were passed to the server in the call to RasEapBegin. When RAS responds to the EAPACTION_Authenticate action, pUserAttributesin PPP_EAP_INPUT, will point to all attributes generated during authentication. These attributes will also be returned to the authentication protocol on the client.

If the authentication protocol authenticates the user without relying on an authentication provider, there is no need for the protocol to ever set Actionto EAPACTION_Authenticate. An example of this case is EAP-Transport Layer Security (TLS).

The EAP success packet is not acknowledged. Therefore, it may be lost and not resent by the server. If RAS on the client receives a Network Control Protocol (NCP) packet, RAS is programmed to proceed as though the authentication was successful, but the EAP success packet was lost. This is because the server has moved on to the NCP phase of PPP. Accordingly, RAS calls RasEapMakeMessagewith the fSuccessPacketReceivedmember of the PPP_EAP_INPUTstructure set to TRUE.

During the course of the authentication session, the authentication protocol may need to interact directly with the user on the client. The authentication protocol can request that RAS display the interactive UI by setting the fInvokeInteractiveUI, pUIContextData, and dwSizeOfUIContextDatamembers in the PPP_EAP_OUTPUTstructure.

The authentication protocol should display a UI only through the mechanism described under Interactive User Interface. If the authentication protocol itself displays the UI, the PPP thread blocks until the UI is dismissed.

If during the authentication process, RasEapMakeMessagereturns any value other than NO_ERROR or ERROR_PPP_INVALID_PACKET, the session is disconnected and the error is logged (on the server) or displayed to the user (on the client).

See Also