tfEapSetOption

Table of Contents >> Optional Protocols >> PPP Interface

#include <trsocket.h>

int tfEapSetOption	(
	ttUserInterface interfaceHandle,
	int optionName,
	const char TM_FAR * optionValuePtr,
	int optionLength
	);

Function Description

This function sets various EAP options described in the table below. For example,

ttUserInterface myInterface;
ttUser8Bit eapOpt;
int errorCode;
  . . .
/* Limit the entire EAP exchange to 25 seconds */
eapOpt = 25;
errorCode = tfEapSetOption( myInterface,
                            TM_EAP_SESSION_TIMEOUT,
                            (char *)&eapOpt,
                            sizeof(eapOpt) );
assert(errorCode == TM_ENOERROR);
 

EAP-TLS Authentication Method

The EAP-TLS method uses Treck TLS/SSL for authentication (see the EAP-TLS Authentication method for a full discussion). The EAP-TLS method is not compiled, by default, and the EAP-TLS options listed below will return an error if referenced.

To use EAP-TLS and the associated options listed below, uncomment the following compile-time macros in trsystem.h and recompile the Treck library.

#define TM_USE_EAPTLS
#define TM_USE_SSL_CLIENT  /* if you need to connect as a client (peer) */
#define TM_USE_SSL_SERVER  /* if you need to connect as a server (authenticator) */
 

Parameters

• interfaceHandle

  The interface handle to set the option on.

• optionName

  Name of the option. (See below.)

• optionValuePtr

  Value of the option. (See below.)

• optionLength

  Length of the option. (See below.)

Group	Option Name	Length	Meaning
Authenticator	TM_EAP_USE_PROTO	1	The specified EAP authentication protocol should be used when authenticating a peer. Must be one of: TM_EAP_IDENTITY TM_EAP_MD5_CHALLENGE TM_EAP_TLS
Peer	TM_EAP_REQ_PROTO	1	The specified EAP authentication protocol is required - the authenticator must use this protocol when authenticating the local host. Must be one of: TM_EAP_IDENTITY TM_EAP_MD5_CHALLENGE TM_EAP_TLS
General	TM_EAP_SESSION_TIMEOUT	1	Sets the maximum length of an EAP session in seconds. If the session has not completed in this time, authentication has failed. Default 120 seconds.
Identity method	TM_EAP_IDENT_TIMEOUT	1	Sets the Identity Request retransmission time in seconds. Default 3 seconds.
	TM_EAP_IDENT_RETRIES	1	Sets the maximum number of Identity Requests that will be sent without a response. Default 10.
	TM_EAP_IDENT_STR		Specifies the EAP identity string to send in response to an Identity Request.
MD5-Challenge method	TM_EAP_MD5_TIMEOUT	1	Sets the MD5-Challenge retransmission time in seconds. Default 3 seconds.
	TM_EAP_MD5_RETRIES	1	Sets the maximum number of MD5-Challenge Requests that will be sent without a response. Default 10.
	TM_EAP_MD5_USERNAME	Any	Sets the MD5-Challenge usernameto be used when authenticating to a peer.
	TM_EAP_MD5_PASSWORD	Any	Sets the MD5-Challenge password to be used when authenticating to a peer.
	TM_EAP_MD5_AUTHNAME	Any	Sets the MD5-Challenge name to be used when acting as an authenticator.
EAP-TLS method	TM_EAPTLS_TIMEOUT	int	(Authenticator only) Sets the EAP-TLS retransmission time in seconds. The authenticator sends requests, the peer responds. If a message is lost in either direction, the request times out and is resent—the peer responds, as before. Default: 3 seconds
	TM_EAPTLS_RETRIES	int	(Authenticator only) Sets the maximum number of EAP-TLS requests that will be sent without a response. Default: 10 attempts
	TM_EAPTLS_SESSION_INDEX	int	This is the value returned by tfSslNewSession(). It defines the TLS parameters to be used (cipher suites, certificates and other TLS options). Required
	TM_EAPTLS_SESSION_BYTES	0 - 32	From 0 to 32 random bytes supplied by the server during the TLS handshake and saved. The value may be used to shorten a subsequent TLS handshake with the same server if the server caches the session parameters. This is the Resume feature specified in the TLS/SSL RFCs. Set a zero-length value to disable the TLS resume feature for the next connection only, e.g. if you changed a session parameter since the last time you connected to the server. Default: the value from the last TLS/SSL handshake
	TM_EAPTLS_USER_PROCESS	int	Set to non-zero to defer cryptographic processing of received TLS handshake records. If you have a receive task that concurrently handles unrelated packet traffic and that traffic needs better response time, then enable this option and call tfEapTlsProcessHandshake() from a lower priority task. This option is identical to the TM_TCP_SSL_USER_PROCESS option for setsockopt(). Default: false (0)
	TM_EAPTLS_PEER_PRIVACY	int	Set to non-zero to enable the EAP-TLS Identity Privacy feature described in section 2.1.4 of RFC 5216. If set, EAP-TLS will use two successive TLS handshakes to authenticate, sending the peer's certificates in the second (encrypted) handshake and an empty certificate list in the first (unencrypted) handshake. This option will cause the authentication to fail if the other end does not support the feature. This option will return an error if you define TM_DISABLE_EAPTLS_ID_PRIVACY in trsystem.h. Default: false (0)
	TM_EAPTLS_MSK_LENGTH	int	Specify the amount of key material to export for the Master Session Key (MSK), described in section 2.3 of RFC 5216 (EAP-TLS) and in RFC 5247 (EAP Key Management Framework). Set the length to 0 to disable MSK export. Set the length to -1 to restore the default value. This option will return an error if you define TM_DISABLE_EAPTLS_KEY_GEN in trsystem.h. Default: 64 bytes
	TM_EAPTLS_EMSK_LENGTH	int	Specify the amount of key material to export for the Extended Master Session Key (EMSK), described in section 2.3 of RFC 5216 (EAP-TLS) and in RFC 5247 (EAP Key Management Framework). Set the length to 0 to disable EMSK export. Set the length to -1 to restore the default value. This option will return an error if you define TM_DISABLE_EAPTLS_KEY_GEN in trsystem.h. Default: 64 bytes
	TM_EAPTLS_IV_LENGTH	int	Specify the amount of key material to export for the cipher Initialization Vector (IV), described in section 2.3 of RFC 5216 (EAP-TLS) and in RFC 5247 (EAP Key Management Framework). Set the length to 0 to disable IV export. Set the length to -1 to restore the default value. This option will return an error if you define TM_DISABLE_EAPTLS_KEY_GEN in trsystem.h. Default: 64 bytes

Returns

• TM_ENOERROR

  Success.

• TM_EINVAL

  Invalid parameter.

• TM_ENOPROTOOPT

  The device does not support EAP.

Table of Contents >> Optional Protocols >> PPP Interface