[This is preliminary documentation and subject to change.]
The RasEapMakeMessage function, is where the majority of the interaction takes place between the authentication protocol and the RAS Connection Manager Service. RasEapMakeMessage is used to process incoming EAP packets and to create EAP packets for transmission to the remote peer. It is also used to process events such as timeouts and authentication completion.
If a message is received from the remote peer, RAS will call RasEapMakeMessage, with the pReceivePacket parameter pointing to the received message.
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 is the case from its state and from the message context.
On return from the RasEapMakeMessage call, the value of the Action member of the PPP_EAP_OUTPUT structure indicates what action, if any, the RAS Connection Manager 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, the RAS Connection Manager will transmit the packet pointed to by the pSendPacket parameter to the remote peer.
If Action is EAPACTION_SendWithTimeout, or EAPACTION_SendWithTimeoutInteractive, the authentication protocol should set the dwIdExpected member of the PPP_EAP_OUTPUT structure to the identifier of the next packet expected from the remote peer. Regardless of whether the next packet received from the peer matches this value, RAS will pass the packet to the authentication protocol in a subsequent call to RasEapMakeMessage. The authentication protocol may silently discard the packet by simply returning ERROR_PPP_INVALID_PACKET. If a packet with the expected identifier, is not received within the configured timeout period, RAS will call RasEapMakeMessage with pReceivePacket set to NULL, to indicate that the previous packet needs to be resent.
The EAPACTION_SendWithTimeout value allows for a timeout, after which the RAS Connection Manager Service will assume the link was lost, and the session will be disconnected. The EAPACTION_SendWithTimeoutInteractive value allows an infinite amount of timeout to occur. The authenticator should use this value when expecting user input on the client. This timeout allows the user an unspecified amount of time to complete the required input.
If the Action member is EAPACTION_Done or EAPACTION_SendAndDone, RAS will examine 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 aren't limited to): ERROR_NO_DIALIN_PERMISSION, ERROR_PASSWD_EXPIRED, ERROR_ACCT_DISABLED, ERROR_RESTRICTED_LOGON_HOURS or ERROR_AUTH_INTERNAL.
The EAP success packet is a non-acknowledged packet. Therefore, it may be lost and not resent by the server. If the RAS Connection Manager on the client receives an NCP packet, RAS will assume that authentication was successful, but that the EAP success packet was lost, since the server has moved on to the NCP phase of PPP. In this case, RAS will call RasEapMakeMessage with the fSuccessPacketReceived member of the PPP_EAP_INPUT structure to TRUE.
Upon successful authentication, the authentication protocol on the server (the authenticator) should set the value of the szIdentity member of the PPP_EAP_OUTPUT structure. This value represents the identity of the authenticated user on the server.
During the course of the authentication session, the authentication protocol may need to interact directly with the user on the client. The authentication protocol vendor can provide an interactive user interface for this purpose. 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. For more information on using an interactive UI, see Interactive User Interface.
If during the authentication process, RasEapMakeMessage returns any value other than NO_ERROR or ERROR_PPP_INVALID_PACKET, the session will be disconnected and the error will be logged (on the server) or displayed to the user (on the client).