Core Functions

Functions
MOC_EXTERN MSTATUS	EAP_buildExpandedNAK (ubyte *eapSessionHdl, ubyte4 instanceId, eapExpandedMethod_t *expMethods, ubyte expMethodCount, ubyte **eapResponse, ubyte4 *eapRespLen)
	Builds a NAK response to send to the authenticator. More...
MOC_EXTERN MSTATUS	EAP_buildExpandedResponse (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte4 expVendorId, ubyte4 expMethodId, ubyte *eapPayload, ubyte4 eapPayloadLen, ubyte **eapResponse, ubyte4 *eapRespLen)
	Builds an expanded payload response. More...
MOC_EXTERN MSTATUS	EAP_buildNAK (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte *nakMethods, ubyte4 nakMethodCount, ubyte **eapResponse, ubyte4 *eapRespLen)
	Builds a NAK response to send to the authenticator. More...
MOC_EXTERN MSTATUS	EAP_checkTimers (ubyte4 instanceId)
	Call expired timers' callbacks. More...
MOC_EXTERN MSTATUS	EAP_deleteInstance (ubyte4 instanceId)
	Delete an EAP instance. More...
MOC_EXTERN MSTATUS	EAP_generateIdReq (ubyte id, ubyte **req, ubyte4 *reqLen)
	Builds an EAP request. More...
MOC_EXTERN MSTATUS	EAP_getAuthenticationStatus (ubyte *eapSessionHdl, ubyte4 instanceId, eapAuthStatus *authStatus)
	Get an EAP session's current authentication status. More...
MOC_EXTERN MSTATUS	EAP_getIdentity (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte **identity, ubyte4 *len)
	Get EAP session's identity string. More...
MOC_EXTERN MSTATUS	EAP_getInstanceStats (ubyte4 instanceId, eapGlobalStats_t *stats)
	Get an EAP instance's statistics. More...
MOC_EXTERN MSTATUS	EAP_getKey (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte **key, ubyte *keylen)
	Get an EAP session's authentication key. More...
MOC_EXTERN MSTATUS	EAP_getMtu (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte4 *mtu)
	Get the MTU (maximum transmission unit) value. More...
MOC_EXTERN MSTATUS	EAP_getSessionStats (ubyte *eapSessionHdl, ubyte4 instanceId, eapSessionStats_t *eapStats)
	Get an EAP session's statistics. More...
MOC_EXTERN MSTATUS	EAP_getSessionStatus (ubyte *eapSessionHdl, ubyte4 instanceId, struct eapSessionStatus_s *eapStatus)
	Get an EAP session's status. More...
MOC_EXTERN MSTATUS	EAP_init (void)
	Initialize EAP structures, data, and stack. More...
MOC_EXTERN MSTATUS	EAP_initInstance (ubyte4 *instanceId)
	Create and initialize an EAP instance and get its ID. More...
MOC_EXTERN MSTATUS	EAP_llReceiveIndication (ubyte *eapSessionHdl, ubyte4 instanceId, eapAltIndication altIndication)
	Change EAP state machine's EAP_SUCCESS or EAP_FAILURE state. More...
MOC_EXTERN MSTATUS	EAP_llReceivePacket (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte *eap_pkt, ubyte4 eap_pkt_len, ubyte *opaque_data)
	Pass a received packet from the lower layer to the upper for processing. More...
MOC_EXTERN MSTATUS	EAP_resetInstanceStats (ubyte4 instanceId)
	Reset an EAP instance's global statistics. More...
MOC_EXTERN MSTATUS	EAP_resetSessionStats (ubyte *eapSessionHdl, ubyte4 instanceId)
	Reset an EAP session's statistics. More...
MOC_EXTERN MSTATUS	EAP_sessionCreate (ubyte *appSessionHandle, ubyte4 instanceId, eapMethodDef_t methodDef, eapSessionConfig_t cfgParam, ubyte **eapSessionHdl)
	Create an EAP Session. More...
MOC_EXTERN MSTATUS	EAP_sessionDelete (ubyte *eapSessionHdl, ubyte4 instanceId)
	Delete an EAP session. More...
MOC_EXTERN MSTATUS	EAP_sessionDisable (ubyte *eapSessionHdl, ubyte4 instanceId)
	Disable an EAP session. More...
MOC_EXTERN MSTATUS	EAP_sessionEnable (ubyte *eapSessionHdl, ubyte4 instanceId)
	Enable an EAP session. More...
MOC_EXTERN MSTATUS	EAP_sessionModify (ubyte *eapSessionHdl, ubyte4 instanceId, eapMethodDef_t methodDef, eapSessionConfig_t cfgParam, ubyte4 modifiedFlag)
	Modify an EAP Session. More...
MOC_EXTERN MSTATUS	EAP_sessionRestart (ubyte *eapSessionHdl, ubyte4 instanceId)
	Restart an EAP session. More...
MOC_EXTERN MSTATUS	EAP_setId_Type (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte id, ubyte type)
	Set identifier and type to the last sent identifier and the EAP packet type. More...
MOC_EXTERN MSTATUS	EAP_setIdentity (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte *identity, ubyte4 len)
	Set an EAP session's identity string. More...
MOC_EXTERN MSTATUS	EAP_setKey (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte *key, ubyte4 keylen)
	Set an EAP session's authentication key. More...
MOC_EXTERN MSTATUS	EAP_setMethodStateDecision (ubyte *eapSessionHdl, ubyte4 instanceId, ubyte methodState, ubyte methodDecision)
	Assign (place on the EAP stack) the EAP processing state machine (methodState) and decision (methodDecision) values. More...
MOC_EXTERN MSTATUS	EAP_shutdown (void)
	Clean up memory and mutexes and shut down the EAP stack. More...
MOC_EXTERN MSTATUS	EAP_ulStartReauth (ubyte *eapSessionHdl, ubyte4 instanceId)
	Start reauthorization and timer rescheduling. More...
MOC_EXTERN MSTATUS	EAP_ulTransmit (ubyte *eapSessionHdl, ubyte4 instanceId, eapMethodType method_type, eapCode code, eapMethodDecision methodDecision, eapMethodState methodState, ubyte *eap_data, ubyte4 eap_data_len)
	Pass a packet from the upper (method) layer to the EAP stack. More...

Detailed Description

Function Documentation

EAP_buildExpandedNAK()

MOC_EXTERN MSTATUS EAP_buildExpandedNAK	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		eapExpandedMethod_t *	expMethods,
		ubyte	expMethodCount,
		ubyte **	eapResponse,
		ubyte4 *	eapRespLen
	)

This function builds a NAK response for your application to send from the peer to the authenticator if the peer doesn't support the expanded method selected by the authenticator. NAK responses return a list of supported expanded methods through the eapMethods parameter.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
expMethods	Array of Expanded methods supported.
expMethodCount	Number of Expanded methods supported.
eapResponse	On return, pointer to EAP response payload.
eapRespLen	On return, pointer to number of bytes in eapResponse.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_buildExpandedResponse()

MOC_EXTERN MSTATUS EAP_buildExpandedResponse	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte4	expVendorId,
		ubyte4	expMethodId,
		ubyte *	eapPayload,
		ubyte4	eapPayloadLen,
		ubyte **	eapResponse,
		ubyte4 *	eapRespLen
	)

This function builds the expanded payload response for the peer, which is sent in response to an expanded request received from the authenticator.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
expVendorId	Vendor ID (user-defined value).
expMethodId	ID of method being negotiated (user-defined value).
eapPayload	EAP response payload.
eapPayloadLen	EAP response payload length of eapPayload.
eapResponse	On return, pointer to expanded EAP response payload.
eapRespLen	On return, pointer to number of bytes in eapResponse.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_buildNAK()

MOC_EXTERN MSTATUS EAP_buildNAK	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte *	nakMethods,
		ubyte4	nakMethodCount,
		ubyte **	eapResponse,
		ubyte4 *	eapRespLen
	)

This function builds a NAK response for your application to send from the peer to the authenticator if the peer doesn't support the method selected by the authenticator. NAK responses return a list of supported methods through the nakMethods parameter.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
nakMethods	Array of methods supported.
nakMethodCount	Number of methods supported.
eapResponse	On return, pointer to EAP response payload.
eapRespLen	On return, pointer to number of bytes in eapResponse.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_checkTimers()

MOC_EXTERN MSTATUS EAP_checkTimers

(

ubyte4

instanceId

)

This function determines whether any timers have expired, and if so then calls each expired expired timer's callback function. Your application should call this function every 300 to 500 milliseconds.

Since

1.41

Version

2.45 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

instanceId

EAP instance ID returned from EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_deleteInstance()

MOC_EXTERN MSTATUS EAP_deleteInstance

(

ubyte4

instanceId

)

This function deletes an EAP instance.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

instanceId

EAP instance ID previously returned by EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_generateIdReq()

MOC_EXTERN MSTATUS EAP_generateIdReq	(	ubyte	id,
		ubyte **	req,
		ubyte4 *	reqLen
	)

This function builds an EAP request using the provided identifier value. It is used by EAP-FAST authenticators to piggyback an identity request to a TLS Finished message received from a peer.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

id	Value of identifier to be sent in EAP packet.
req	On return, pointer to generated EAP request packet.
reqLen	On return, pointer to number of bytes in req.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_getAuthenticationStatus()

MOC_EXTERN MSTATUS EAP_getAuthenticationStatus	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		eapAuthStatus *	authStatus
	)

This function retrieves the current EAP authentication status. The lower layer uses this function if it requires an authenticated EAP session before transmitting data but hasn't received the authentication status from the upper layer.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
authStatus	On return, pointer to authentication status (an eapAuthStatus enumerated value, defined in eap_proto.h).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_getIdentity()

MOC_EXTERN MSTATUS EAP_getIdentity	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte **	identity,
		ubyte4 *	len
	)

This function retrieves the EAP session's identity string.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
identity	On return, pointer to the identity string.
len	On return, number of bytes in identity.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_getInstanceStats()

MOC_EXTERN MSTATUS EAP_getInstanceStats	(	ubyte4	instanceId,
		eapGlobalStats_t *	stats
	)

This function retrieves statistics for the specified EAP instance. The statistics are accumulated values since they were last reset via a call to EAP_resetInstanceStats.

The following statistics are returned through the stats parameter:

• Total packets sent, received, and discarded
• Number of sessions created, modified, active, failed, and restarted
• (Authenticators only) Number of successful and number of failed peer authentications
• Number of times the authenticator/peer performed a retransmission
• Number of times the peer timed out
• Number of packets dropped due to invalid session, invalid packet

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

instanceId	EAP instance ID previously returned by EAP_initInstance.
stats	On return, pointer to global statistics (see eapGlobalStats_t in eap.h).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_getSessionStatus

EAP_getSessionStats

EAP_resetSessionStats

EAP_resetInstanceStats

eap.h

EAP_getKey()

MOC_EXTERN MSTATUS EAP_getKey	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte **	key,
		ubyte *	keylen
	)

This function retrieves the EAP session's authentication key (or NULL if there's no key).

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
key	On return, pointer to the authentication key.
keylen	On return, pointer to number of bytes in key.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_setKey

eap.h

EAP_getMtu()

MOC_EXTERN MSTATUS EAP_getMtu	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte4 *	mtu
	)

This function retrieves the MTU (maximum transmission unit) value that was set at EAP session creation.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
mtu	On return, pointer to MTU.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_getSessionStats()

MOC_EXTERN MSTATUS EAP_getSessionStats	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		eapSessionStats_t *	eapStats
	)

This function retrieves statistics for the specified EAP session. The statistics are accumulated values since they were last reset via a call to EAP_resetSessionStats.

The following statistics are returned through the eapstats parameter:

• Number of lower layer packets sent and received
• Number of packets the lower layer passed to the upper layer
• Number of packets the upper layer received from the lower layer
• Number of packets retransmitted and discarded
• Number of packets dropped because no callback was registered to process them
• Number of packets dropped because of an invalid packet

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
eapStats	On return, pointer to session statistics (see eapSessionStats_t in eap.h).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_getSessionStatus

EAP_resetSessionStats

EAP_getInstanceStats

EAP_resetInstanceStats

eap.h

EAP_getSessionStatus()

MOC_EXTERN MSTATUS EAP_getSessionStatus	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		struct eapSessionStatus_s *	eapStatus
	)

This function retrieves the EAP session's status.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
eapStatus	On return, pointer to EAP session status (see eapSessionStatus_t in eap_session.h).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_init()

MOC_EXTERN MSTATUS EAP_init

(

void

)

This function initializes NanoEAP structures, data, and stack.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_initInstance()

MOC_EXTERN MSTATUS EAP_initInstance

(

ubyte4 *

instanceId

)

This function creates an EAP instance, initializes it, and returns its ID through the instanceId parameter. All subsequent function calls made for this EAP instance use this returned ID.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

instanceId

On return, pointer to instance ID.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_llReceiveIndication()

MOC_EXTERN MSTATUS EAP_llReceiveIndication	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		eapAltIndication	altIndication
	)

This function changes the standard EAP state machine progression by applying custom logic, which can be useful in cases such as when an EAP status response is dropped, but the information is available through deductive reasoning (for example, the authenticator progresses through the PPP state machine). In this example, the peer lower layer can inform the EAP stack, enabling continued EAP processing.

This function is called by the application to give alternate indications of accept or reject. EAP will proceed to the EAP_SUCCESS or EAP_FAILURE state according to the current state of the decision variable.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
altIndication	Alternate indication of success or failure — any of the eapAltIndication enumerated values: EAP_ALT_ACCEPT EAP_ALT_REJECT

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_ulTransmit

EAP_llReceivePacket

eap.h

EAP_llReceivePacket()

MOC_EXTERN MSTATUS EAP_llReceivePacket	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte *	eap_pkt,
		ubyte4	eap_pkt_len,
		ubyte *	opaque_data
	)

This function is called by the lower layer to pass a received packet to the upper EAP layer for processing. This function also looks up the session context and passes it to the upper layer.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
eap_pkt	Pointer to EAP packet
eap_pkt_len	Number of bytes in eap_pkt.
opaque_data	Pointer to opaque data — extra data that's passed from the lower layer to the upper (method) layer through the EAP stack.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_ulTransmit

EAP_llReceiveIndication

eap.h

EAP_resetInstanceStats()

MOC_EXTERN MSTATUS EAP_resetInstanceStats

(

ubyte4

instanceId

)

This function resets the specified EAP instance's global statistics to zero (0).

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

instanceId

EAP instance ID previously returned by EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_getSessionStats

EAP_resetSessionStats

EAP_getInstanceStats

eap.h

EAP_resetSessionStats()

MOC_EXTERN MSTATUS EAP_resetSessionStats	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId
	)

This function resets the specified EAP session's statistics to zero (0).

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_getSessionStatus

EAP_resetSessionStats

EAP_getInstanceStats

EAP_resetInstanceStats

eap.h

EAP_sessionCreate()

MOC_EXTERN MSTATUS EAP_sessionCreate	(	ubyte *	appSessionHandle,
		ubyte4	instanceId,
		eapMethodDef_t	methodDef,
		eapSessionConfig_t	cfgParam,
		ubyte **	eapSessionHdl
	)

This function creates an EAP session based on the specified parameters, returning the resultant session handle through the eapSessionHdl parameter.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

appSessionHandle	Cookie given by the application to identify the session.
instanceId	EAP instance ID returned from EAP_initInstance.
methodDef	Structure containing method information such as method type and callback functions.
cfgParam	Structure containing desired configuration parameters for this EAP session.
eapSessionHdl	On return, pointer to EAP session handle.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_sessionModify

EAP_sessionDelete

EAP_sessionEnable

EAP_sessionDisable

eap.h

EAP_sessionDelete()

MOC_EXTERN MSTATUS EAP_sessionDelete	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId
	)

This function deletes an existing EAP session.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_sessionCreate

EAP_sessionModify

EAP_sessionEnable

EAP_sessionDisable

eap.h

EAP_sessionDisable()

MOC_EXTERN MSTATUS EAP_sessionDisable	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId
	)

This function disables an existing EAP session. When a port is disabled (for any reason), the application should call this function for every active session on the disabled port.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_sessionCreate

EAP_sessionModify

EAP_sessionEnable

eap.h

EAP_sessionEnable()

MOC_EXTERN MSTATUS EAP_sessionEnable	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId
	)

This function enables an existing EAP session, sets its current state to EAP_INITIALIZE, and resets all remaining parameters. It cannot be called before the corresponding port is enabled, and it must be called in order for the EAP stack to process any packets.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_sessionCreate

EAP_sessionModify

EAP_sessionDisable

eap.h

EAP_sessionModify()

MOC_EXTERN MSTATUS EAP_sessionModify	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		eapMethodDef_t	methodDef,
		eapSessionConfig_t	cfgParam,
		ubyte4	modifiedFlag
	)

This function modifies an existing EAP session, based on the specified parameters.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
methodDef	Structure containing method information such as method type and callback functions.
cfgParam	Structure containing desired configuration parameters for this EAP session.
modifiedFlag	Bitmask sum of all variables to modify: EAP_MOD_METHOD_DEF EAP_MOD_SESSION_TYPE EAP_MOD_SESSION_MTU EAP_MOD_SESSION_UL_TIMEOUT EAP_MOD_SESSION_RETRANS_TIMEOUT EAP_MOD_SESSION_MAX_RETRANS

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_sessionCreate

EAP_sessionDelete

EAP_sessionEnable

EAP_sessionDisable

eap.h

EAP_sessionRestart()

MOC_EXTERN MSTATUS EAP_sessionRestart	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId
	)

This function restarts an existing EAP session, setting its current state to EAP_INITIALIZE and resetting all remaining parameters.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_sessionCreate

EAP_sessionModify

EAP_sessionDelete

EAP_sessionEnable

EAP_sessionDisable

eap.h

EAP_setId_Type()

MOC_EXTERN MSTATUS EAP_setId_Type	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte	id,
		ubyte	type
	)

This function sets the values of the identifier to the last sent identifier and the type to the type of EAP packet on the stack. This function is used for EAP-FAST when the application piggybacks the second stage packet to the previous TLS packet (which in this case is the TLS Finished message).

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
id	Identifier in EAP packet.
type	Any of the eapMethodType enumerated values (see eap_proto.h).

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_setIdentity()

MOC_EXTERN MSTATUS EAP_setIdentity	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte *	identity,
		ubyte4	len
	)

This function sets an EAP session's identity string.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
identity	Pointer to desired identity string value.
len	Pointer to number of bytes in identity.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_setKey()

MOC_EXTERN MSTATUS EAP_setKey	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte *	key,
		ubyte4	keylen
	)

This function sets the EAP session's authentication key to the specified value.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.
key	Pointer to desired key value.
keylen	Number of bytes in key.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

See also

EAP_getKey

eap.h

EAP_setMethodStateDecision()

MOC_EXTERN MSTATUS EAP_setMethodStateDecision	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		ubyte	methodState,
		ubyte	methodDecision
	)

This function assigns the specified EAP processing state machine (methodState) and decision (methodDecision) values, placing them on the EAP stack. It is particularly useful for two-phase methods: when the second stage method informs the application of the result, the application calls this function to update the EAP stack with the appropriate state machine values.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
methodState	Value to assign to methodState.
methodDecision	Value to assign to decision.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_shutdown()

MOC_EXTERN MSTATUS EAP_shutdown

(

void

)

This function performs memory and mutex cleanup, shuts down the EAP stack, and deletes all core EAP sessions and EAP instances.

Since

2.45

Version

2.45 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_ulStartReauth()

MOC_EXTERN MSTATUS EAP_ulStartReauth	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId
	)

This function checks the EAP session status, and if the status is SUCCESS, calls EAP_sessionRestart to begin the reauthorization and timer rescheduling.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID previously returned by EAP_initInstance.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h

EAP_ulTransmit()

MOC_EXTERN MSTATUS EAP_ulTransmit	(	ubyte *	eapSessionHdl,
		ubyte4	instanceId,
		eapMethodType	method_type,
		eapCode	code,
		eapMethodDecision	methodDecision,
		eapMethodState	methodState,
		ubyte *	eap_data,
		ubyte4	eap_data_len
	)

This function is called by the authenticator or peer to pass a packet from the upper (method) layer to the EAP stack. The EAP layer copies the packet sent by the application, builds the EAP header using the method_type parameter's information, and then passes the packet to the lower (physical) layer to be transmitted to the peer or authenticator, respectively.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_AUTH__

eap.h

Parameters

eapSessionHdl	EAP session handle returned from EAP_sessionCreate.
instanceId	EAP instance ID returned from EAP_initInstance.
method_type	Any of the eapMethodType enumerated values (see eap_proto.h).
code	Any of the eapCode enumerated values (see eap_proto.h).
methodDecision	Any of the eapMethodState enumerated values (refer to eap_proto.h).
methodState	Any of the eapMethodDecision enumerated values (refer to eap_proto.h).
eap_data	Pointer to EAP payload.
eap_data_len	Number of bytes in eap_data.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

eap.h