EAP peer: EAP-TLS/PEAP/TTLS/FAST common functions. More...

#include "includes.h"
#include "common.h"
#include "crypto/sha1.h"
#include "crypto/tls.h"
#include "eap_i.h"
#include "eap_tls_common.h"
#include "eap_config.h"

Functions
int	eap_peer_tls_ssl_init (struct eap_sm sm, struct eap_ssl_data data, struct eap_peer_config *config, u8 eap_type)
	Initialize shared TLS functionality. More...

void	eap_peer_tls_ssl_deinit (struct eap_sm sm, struct eap_ssl_data data)
	Deinitialize shared TLS functionality. More...

u8 *	eap_peer_tls_derive_key (struct eap_sm sm, struct eap_ssl_data data, const char *label, size_t len)
	Derive a key based on TLS session data. More...

u8 *	eap_peer_tls_derive_session_id (struct eap_sm sm, struct eap_ssl_data data, u8 eap_type, size_t *len)
	Derive a Session-Id based on TLS data. More...

int	eap_peer_tls_process_helper (struct eap_sm sm, struct eap_ssl_data data, EapType eap_type, int peap_version, u8 id, const struct wpabuf in_data, struct wpabuf *out_data)
	Process TLS handshake message. More...

struct wpabuf *	eap_peer_tls_build_ack (u8 id, EapType eap_type, int peap_version)
	Build a TLS ACK frame. More...

int	eap_peer_tls_reauth_init (struct eap_sm sm, struct eap_ssl_data data)
	Re-initialize shared TLS for session resumption. More...

int	eap_peer_tls_status (struct eap_sm sm, struct eap_ssl_data data, char *buf, size_t buflen, int verbose)
	Get TLS status. More...

const u8 *	eap_peer_tls_process_init (struct eap_sm sm, struct eap_ssl_data data, EapType eap_type, struct eap_method_ret ret, const struct wpabuf reqData, size_t len, u8 flags)
	Initial validation/processing of EAP requests. More...

void	eap_peer_tls_reset_input (struct eap_ssl_data *data)
	Reset input buffers. More...

void	eap_peer_tls_reset_output (struct eap_ssl_data *data)
	Reset output buffers. More...

int	eap_peer_tls_decrypt (struct eap_sm sm, struct eap_ssl_data data, const struct wpabuf in_data, struct wpabuf *in_decrypted)
	Decrypt received phase 2 TLS message. More...

int	eap_peer_tls_encrypt (struct eap_sm sm, struct eap_ssl_data data, EapType eap_type, int peap_version, u8 id, const struct wpabuf in_data, struct wpabuf *out_data)
	Encrypt phase 2 TLS message. More...

int	eap_peer_select_phase2_methods (struct eap_peer_config config, const char prefix, struct eap_method_type *types, size_t num_types)
	Select phase 2 EAP method. More...

int	eap_peer_tls_phase2_nak (struct eap_method_type types, size_t num_types, struct eap_hdr hdr, struct wpabuf **resp)
	Generate EAP-Nak for Phase 2. More...

Detailed Description

EAP peer: EAP-TLS/PEAP/TTLS/FAST common functions.

Function Documentation

int eap_peer_select_phase2_methods	(	struct eap_peer_config *	config,
		const char *	prefix,
		struct eap_method_type **	types,
		size_t *	num_types
	)

Select phase 2 EAP method.

Parameters

config	Pointer to the network configuration
prefix	'phase2' configuration prefix, e.g., "auth="
types	Buffer for returning allocated list of allowed EAP methods
num_types	Buffer for returning number of allocated EAP methods

Returns: 0 on success, -1 on failure

This function is used to parse EAP method list and select allowed methods for Phase2 authentication.

struct wpabuf* eap_peer_tls_build_ack	(	u8	id,
		EapType	eap_type,
		int	peap_version
	)

Build a TLS ACK frame.

Parameters

id	EAP identifier for the response
eap_type	EAP type (EAP_TYPE_TLS, EAP_TYPE_PEAP, ...)
peap_version	Version number for EAP-PEAP/TTLS

Returns: Pointer to the allocated ACK frame or NULL on failure

int eap_peer_tls_decrypt	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		const struct wpabuf *	in_data,
		struct wpabuf **	in_decrypted
	)

Decrypt received phase 2 TLS message.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
in_data	Message received from the server
in_decrypted	Buffer for returning a pointer to the decrypted message

Returns: 0 on success, 1 if more input data is needed, or -1 on failure

u8* eap_peer_tls_derive_key	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		const char *	label,
		size_t	len
	)

Derive a key based on TLS session data.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
label	Label string for deriving the keys, e.g., "client EAP encryption"
len	Length of the key material to generate (usually 64 for MSK)

Returns: Pointer to allocated key on success or NULL on failure

This function uses TLS-PRF to generate pseudo-random data based on the TLS session data (client/server random and master key). Each key type may use a different label to bind the key usage into the generated material.

The caller is responsible for freeing the returned buffer.

u8* eap_peer_tls_derive_session_id	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		u8	eap_type,
		size_t *	len
	)

Derive a Session-Id based on TLS data.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
eap_type	EAP method used in Phase 1 (EAP_TYPE_TLS/PEAP/TTLS/FAST)
len	Pointer to length of the session ID generated

Returns: Pointer to allocated Session-Id on success or NULL on failure

This function derive the Session-Id based on the TLS session data (client/server random and method type).

The caller is responsible for freeing the returned buffer.

int eap_peer_tls_encrypt	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		EapType	eap_type,
		int	peap_version,
		u8	id,
		const struct wpabuf *	in_data,
		struct wpabuf **	out_data
	)

Encrypt phase 2 TLS message.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
eap_type	EAP type (EAP_TYPE_TLS, EAP_TYPE_PEAP, ...)
peap_version	Version number for EAP-PEAP/TTLS
id	EAP identifier for the response
in_data	Plaintext phase 2 data to encrypt or NULL to continue fragments
out_data	Buffer for returning a pointer to the encrypted response message

Returns: 0 on success, -1 on failure

int eap_peer_tls_phase2_nak	(	struct eap_method_type *	types,
		size_t	num_types,
		struct eap_hdr *	hdr,
		struct wpabuf **	resp
	)

Generate EAP-Nak for Phase 2.

Parameters

types	Buffer for returning allocated list of allowed EAP methods
num_types	Buffer for returning number of allocated EAP methods
hdr	EAP-Request header (and the following EAP type octet)
resp	Buffer for returning the EAP-Nak message

Returns: 0 on success, -1 on failure

int eap_peer_tls_process_helper	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		EapType	eap_type,
		int	peap_version,
		u8	id,
		const struct wpabuf *	in_data,
		struct wpabuf **	out_data
	)

Process TLS handshake message.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
eap_type	EAP type (EAP_TYPE_TLS, EAP_TYPE_PEAP, ...)
peap_version	Version number for EAP-PEAP/TTLS
id	EAP identifier for the response
in_data	Message received from the server
out_data	Buffer for returning a pointer to the response message

Returns: 0 on success, 1 if more input data is needed, 2 if application data is available, or -1 on failure

This function can be used to process TLS handshake messages. It reassembles the received fragments and uses a TLS library to process the messages. The response data from the TLS library is fragmented to suitable output messages that the caller can send out.

out_data is used to return the response message if the return value of this function is 0, 2, or -1. In case of failure, the message is likely a TLS alarm message. The caller is responsible for freeing the allocated buffer if *out_data is not NULL.

This function is called for each received TLS message during the TLS handshake after eap_peer_tls_process_init() call and possible processing of TLS Flags field. Once the handshake has been completed, i.e., when tls_connection_established() returns 1, EAP method specific decrypting of the tunneled data is used.

const u8* eap_peer_tls_process_init	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		EapType	eap_type,
		struct eap_method_ret *	ret,
		const struct wpabuf *	reqData,
		size_t *	len,
		u8 *	flags
	)

Initial validation/processing of EAP requests.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
eap_type	EAP type (EAP_TYPE_TLS, EAP_TYPE_PEAP, ...)
ret	Return values from EAP request validation and processing
reqData	EAP request to be processed (eapReqData)
len	Buffer for returning length of the remaining payload
flags	Buffer for returning TLS flags

Returns: Pointer to payload after TLS flags and length or NULL on failure

This function validates the EAP header and processes the optional TLS Message Length field. If this is the first fragment of a TLS message, the TLS reassembly code is initialized to receive the indicated number of bytes.

EAP-TLS, EAP-PEAP, EAP-TTLS, and EAP-FAST methods are expected to use this function as the first step in processing received messages. They will need to process the flags (apart from Message Length Included) that are returned through the flags pointer and the message payload that will be returned (and the length is returned through the len pointer). Return values (ret) are set for continuation of EAP method processing. The caller is responsible for setting these to indicate completion (either success or failure) based on the authentication result.

int eap_peer_tls_reauth_init	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data
	)

Re-initialize shared TLS for session resumption.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing

Returns: 0 on success, -1 on failure

void eap_peer_tls_reset_input ( struct eap_ssl_data * data )

Reset input buffers.

Parameters

data	Data for TLS processing

This function frees any allocated memory for input buffers and resets input state.

void eap_peer_tls_reset_output ( struct eap_ssl_data * data )

Reset output buffers.

Parameters

data	Data for TLS processing

This function frees any allocated memory for output buffers and resets output state.

void eap_peer_tls_ssl_deinit	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data
	)

Deinitialize shared TLS functionality.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing

This function deinitializes shared TLS functionality that was initialized with eap_peer_tls_ssl_init().

int eap_peer_tls_ssl_init	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		struct eap_peer_config *	config,
		u8	eap_type
	)

Initialize shared TLS functionality.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
config	Pointer to the network configuration
eap_type	EAP method used in Phase 1 (EAP_TYPE_TLS/PEAP/TTLS/FAST)

Returns: 0 on success, -1 on failure

This function is used to initialize shared TLS functionality for EAP-TLS, EAP-PEAP, EAP-TTLS, and EAP-FAST.

int eap_peer_tls_status	(	struct eap_sm *	sm,
		struct eap_ssl_data *	data,
		char *	buf,
		size_t	buflen,
		int	verbose
	)

Get TLS status.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
data	Data for TLS processing
buf	Buffer for status information
buflen	Maximum buffer length
verbose	Whether to include verbose status information

Returns: Number of bytes written to buf.

Functions

Detailed Description

Function Documentation