RAS and Authentication Protocol Interaction During Authentication
A version of this page is also available for
4/8/2010
The RasEapMakeMessage function controls the majority of the interaction between the authentication protocol and RAS. RasEapMakeMessage processes 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 pReceivePacket parameter.
If RAS calls RasEapMakeMessage with pReceivePacket set 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 Action member of the PPP_EAP_OUTPUT structure indicates what action, if any, RAS should take. The Action member takes values from the PPP_EAP_ACTION enumerated type.
If Action is EAPACTION_Send, EAPACTION_SendAndDone, EAPACTION_SendWithTimeout, or EAPACTION_SendWithTimeoutInteractive, RAS transmits the packet that is pointed to by the pSendPacket parameter 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 Action member is EAPACTION_Done or EAPACTION_SendAndDone, RAS examines the dwAuthResultCode member of PPP_EAP_OUTPUT. If dwAuthResultCode is NO_ERROR, the authentication succeeded. If dwAuthResultCode is 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 Action is EAPACTION_Done or EAPACTION_SendAndDone, the pUserAttributes member 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 Action member in PPP_EAP_OUTPUT. In this case, the pUserAttributes pointer in PPP_EAP_OUTPUT should 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, pUserAttributes in 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 Action to 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 RasEapMakeMessage with the fSuccessPacketReceived member of the PPP_EAP_INPUT structure 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 dwSizeOfUIContextData members in the PPP_EAP_OUTPUT structure.
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, RasEapMakeMessage returns 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
Reference
RasEapMakeMessage
PPP_EAP_OUTPUT
PPP_EAP_ACTION
RasEapBegin
PPP_EAP_INPUT