EAP-TTLS Functions

Provides EAP-TTLS (EAP-tunneled transport layer security) authentication. More...

Functions
MOC_EXTERN MSTATUS	EAP_TTLSdeleteSession (void *eapTTLSSession)
	Delete a second (upper) stage EAP TTLS session. More...
MOC_EXTERN MSTATUS	EAP_TTLSFormSendPacket (void *eapTTLSCb, ubyte *pkt, ubyte4 pktLen, ubyte **eapResponse, ubyte4 *eapRespLen)
	Build the second stage payload. More...
MOC_EXTERN MSTATUS	EAP_TTLSgetKey (void *eapCb, ubyte *key, ubyte2 keyLen)
	Generate a session key. More...
MOC_EXTERN MSTATUS	EAP_TTLSgetSessionStatus (void *eapTTLSCb, ubyte *eapSessionStatus)
	Get an EAP-TTLS session's session status. More...
MOC_EXTERN MSTATUS	EAP_TTLSinitSession (ubyte *appSessionCB, ubyte **eapTTLSSession, EAP_TTLS_params *eapTTLSparams)
	Create and initialize a second stage TTLS session as a peer or passthrough authenticator. More...
MOC_EXTERN MSTATUS	EAP_TTLSProcessRadiusAuthResponse (void *eapCb, RADIUS_RqstRecord *pRadiusResp)
	Process a received RADIUS packet and respond appropriately. More...
MOC_EXTERN MSTATUS	EAP_TTLSreceiveLLPacket (void *eapTTLSCb, ubyte *pkt, ubyte4 pktLen)
	Process second stage packets. More...
MOC_EXTERN MSTATUS	EAP_TTLSsendAlert (ubyte *eapSessionHdl, sbyte4 alertClass, sbyte4 alertId)
	Build a TLS Alert Message to be sent over EAP. More...
MOC_EXTERN MSTATUS	EAP_TTLSSendData (ubyte *ttls_connection, ubyte *data, ubyte4 len, InnerAppType innerApp, ubyte **eapRespData, ubyte4 *eapRespLen)
	Send data using the TLS inner application extension. More...
MOC_EXTERN MSTATUS	EAP_TTLSulPeerTransmit (ubyte *eapSessionHdl, ubyte4 instanceId, eapMethodType methodType, eapCode code, eapMethodDecision methodDecision, eapMethodState methodState, ubyte *eap_data, ubyte4 eap_data_len)
	Transmit (send) an EAP response to the authenticator. More...

Detailed Description

Function Documentation

EAP_TTLSdeleteSession()

MOC_EXTERN MSTATUS EAP_TTLSdeleteSession

(

void *

eapTTLSSession

)

This function deletes a second (upper) stage TTLS session.

Since

2.02

Version

2.02 and later

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

• __ENABLE_MOCANA_EAP_TTLS__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

eapTTLSSession

EAP-TTLS session handle returned from EAP_TTLSinitSession.

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_TTLSSendData

EAP_TTLSreceiveLLPacket

EAP_TTLSinitSession

eap_ttls.h

EAP_TTLSFormSendPacket()

MOC_EXTERN MSTATUS EAP_TTLSFormSendPacket	(	void *	eapTTLSCb,
		ubyte *	pkt,
		ubyte4	pktLen,
		ubyte **	eapResponse,
		ubyte4 *	eapRespLen
	)

This function (typically called by the TTLS application) builds the second stage payload, including managing any required fragmentation, and then passes the result back to the calling function (which will then typically call EAP_ulTransmit to send the packet).

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_EAP_TTLS__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

eapTTLSCb	EAP-TTLS session handle returned from EAP_TTLSinitSession.
pkt	Pointer to input data (payload).
pktLen	Number of bytes of input data (payload).
eapResponse	On return, pointer to resultant EAP output packet.
eapRespLen	On return, pointer to number of bytes in EAP output packet (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.

See also

EAP_TTLSSendData

EAP_TTLSreceiveLLPacket

eap_ttls.h

EAP_TTLSgetKey()

MOC_EXTERN MSTATUS EAP_TTLSgetKey	(	void *	eapCb,
		ubyte *	key,
		ubyte2	keyLen
	)

This function (typically called by your application) generates a session key for the specified TTLS session.

The first 64 bits of the returned key represent the MSK (master session key), while the remaining bits represent the EMSK (extended master session key).

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_EAP_TTLS__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

eapCb	EAP-TTLS session handle returned from EAP_TTLSinitSession.
key	On return, pointer to generated session key.
keyLen	Length (number of bytes) of key to generate.

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_TTLSSendData

eap_ttls.h

EAP_TTLSgetSessionStatus()

MOC_EXTERN MSTATUS EAP_TTLSgetSessionStatus	(	void *	eapTTLSCb,
		ubyte *	eapSessionStatus
	)

This function retrieves an EAP-TTLS session's session status.

Since

2.02

Version

2.02 and later

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

• __ENABLE_MOCANA_EAP_TTLS__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

eapTTLSCb	EAP-TTLS session handle returned from EAP_TTLSinitSession.
eapSessionStatus	On return, pointer to the session's current status: one of the eap_ttls_eap_state enumerated values (defined in eap_ttls_pvt.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_ttls.h

EAP_TTLSinitSession()

MOC_EXTERN MSTATUS EAP_TTLSinitSession	(	ubyte *	appSessionCB,
		ubyte **	eapTTLSSession,
		EAP_TTLS_params *	eapTTLSparams
	)

This function (typically called by your application) creates and initializes the second stage TTLS session as a peer or passthrough authenticator. On success, the function returns the TTLS session handle to the application.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_EAP_TTLS__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

appSessionCB	Application-specific session identifier.
eapTTLSSession	On return, pointer to EAP-TTLS session handle.
eapTTLSparams	Pointer to structure containing desired EAP-TTLS session configuration settings and callback function pointers.

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_TTLSSendData

EAP_TTLSreceiveLLPacket

EAP_TTLSdeleteSession

eap_ttls.h

EAP_TTLSProcessRadiusAuthResponse()

MOC_EXTERN MSTATUS EAP_TTLSProcessRadiusAuthResponse	(	void *	eapCb,
		RADIUS_RqstRecord *	pRadiusResp
	)

This function (called from the TTLS passthrough server or authenticator) processes a RADIUS packet received from a RADIUS server. On receiving Access Accept or Reject, an EAP Success or Failure response is sent to the peer. On receiving other RADIUS attributes, the RADIUS packet is decapsulated and a corresponding EAP Request is sent to the peer.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_EAP_TTLS__
• __ENABLE_MOCANA_EAP_AUTH__

Additionally, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSL_ASYNC_SERVER_API__
• __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__

eap_ttls.h

Parameters

eapCb	EAP-TTLS session handle returned from EAP_TTLSinitSession.
pRadiusResp	Pointer to the received RADIUS packet.

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_TTLSSendData

EAP_TTLSreceiveLLPacket

EAP_TTLSdeleteSession

eap_ttls.h

EAP_TTLSreceiveLLPacket()

MOC_EXTERN MSTATUS EAP_TTLSreceiveLLPacket	(	void *	eapTTLSCb,
		ubyte *	pkt,
		ubyte4	pktLen
	)

This function (typically called from the TTLS application) processes second stage packets received after the first stage TLS connection is established. Second stage packet processing includes any required reassembly.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_EAP_TTLS__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

eapTTLSCb	EAP-TTLS session handle returned from EAP_TTLSinitSession.
pkt	Pointer to input data (packet).
pktLen	Number of bytes of input data (pkt).

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_TTLSFormSendPacket

EAP_TTLSSendData

eap_ttls.h

EAP_TTLSsendAlert()

MOC_EXTERN MSTATUS EAP_TTLSsendAlert	(	ubyte *	eapSessionHdl,
		sbyte4	alertClass,
		sbyte4	alertId
	)

This function builds a TLS Alert Message to be sent over EAP.

Since

2.02

Version

2.02 and later

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

• __ENABLE_MOCANA_EAP_TTLS__
• __ENABLE_MOCANA_INNER_APP__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Note

This funcitn is used during TTLS v1 negotiation.

Parameters

eapSessionHdl	EAP-TTLS session handle returned from EAP_TTLSinitSession.
alertClass	One of the following alert class definitions: SSLALERTLEVEL_WARNING or SSLALERTLEVEL_FATAL.
alertId	SSL alert ID code (see SSL Alert Codes and DigiCert® TrustCore SDK Error Codes).

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_ttls.h

EAP_TTLSSendData()

MOC_EXTERN MSTATUS EAP_TTLSSendData	(	ubyte *	ttls_connection,
		ubyte *	data,
		ubyte4	len,
		InnerAppType	innerApp,
		ubyte **	eapRespData,
		ubyte4 *	eapRespLen
	)

This function encrypts and sends data using the TLS inner application extension.

Since

2.02

Version

2.02 and later

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

• __ENABLE_MOCANA_EAP_TTLS__
• __ENABLE_MOCANA_INNER_APP__

Additionally, for each of the following flag pairs at least one of the pair must be defined in moptions.h:

• Enable EAP peer/authenticator (__ENABLE_MOCANA_EAP_PEER__, __ENABLE_MOCANA_EAP_AUTH__)
• Enable asynchronous SSL client/server (__ENABLE_MOCANA_SSL_ASYNC_SERVER_API__, __ENABLE_MOCANA_SSL_ASYNC_CLIENT_API__)

eap_ttls.h

Parameters

ttls_connection	EAP-TTLS session handle returned from EAP_TTLSinitSession.
data	Pointer to data to encrypt and send.
len	Number of bytes of data to encrypt and send (data).
innerApp	Inner application extension type; any of the eap_ttls_inner_appState enumerated values (defined in eap_ttls_pvt.h).
eapRespData	On return, pointer to encrypted data.
eapRespLen	On return, pointer to number of bytes of encrypted data (eapRespData).

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_ttls.h

EAP_TTLSulPeerTransmit()

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

This function (called by the TTLS second stage peer processing) transmits (sends) responses from the peer to the authenticator through the second stage EAP stack.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_EAP_PEER__
• __ENABLE_MOCANA_EAP_TTLS__

eap_ttls.h

Parameters

eapSessionHdl	EAP-PEAP session handle returned from EAP_PEAPinitSession.
instanceId	EAP instance ID returned from EAP_initInstance.
methodType	eapMethodType enumerated value for the second phase (refer to eap_proto.h).
code	EAP_CODE_RESPONSE (an eapCode enumerated value, defined in eap_proto.h).
methodDecision	eapMethodDecision enumerated value (refer to eap_proto.h)
methodState	eapMethodState enumerated value (refer to eap_proto.h)
eap_data	Pointer to response to be transmitted.
eap_data_len	Number of bytes in response to be transmitted (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_ttls.h