tls.h File Reference

Generic EAP over TLS API. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/tcp.h>
#include <netdb.h>
#include <fcntl.h>
#include <signal.h>
#include <ctype.h>
#include <sys/time.h>
#include <arpa/inet.h>
#include <freeradius-devel/server/base.h>
#include <freeradius-devel/tls/base.h>
#include <freeradius-devel/eap/base.h>

Include dependency graph for tls.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	eap_tls_data_t
struct	eap_tls_prf_label_t
struct	eap_tls_session_t
	Tracks the state of an EAP-TLS session. More...

Macros
#define	SET_LENGTH_INCLUDED(x)   ((x) | (0x80))
#define	SET_MORE_FRAGMENTS(x)   ((x) | (0x40))
#define	SET_START(x)   ((x) | (0x20))
#define	TLS_ALERT(x)   (((x) & 0x0015) == 0x0015)
#define	TLS_CHANGE_CIPHER_SPEC(x)   (((x) & 0x0014) == 0x0014)
#define	TLS_HANDSHAKE(x)   (((x) & 0x0016) == 0x0016)
#define	TLS_HEADER_LEN   4
#define	TLS_HEADER_LENGTH_FIELD_LEN   4
#define	TLS_LENGTH_INCLUDED(x)   (((x) & 0x80) != 0)
#define	TLS_MORE_FRAGMENTS(x)   (((x) & 0x40) != 0)
#define	TLS_RESERVED0(x)   (((x) & 0x10) != 0)
#define	TLS_RESERVED1(x)   (((x) & 0x08) != 0)
#define	TLS_RESERVED2(x)   (((x) & 0x04) != 0)
#define	TLS_RESERVED3(x)   (((x) & 0x02) != 0)
#define	TLS_RESERVED4(x)   (((x) & 0x01) != 0)
#define	TLS_START(x)   (((x) & 0x20) != 0)

Enumerations
enum	eap_tls_status_t {   EAP_TLS_INVALID = 0 ,   EAP_TLS_ESTABLISHED ,   EAP_TLS_FAIL ,   EAP_TLS_HANDLED ,   EAP_TLS_START_SEND ,   EAP_TLS_RECORD_SEND ,   EAP_TLS_ACK_SEND ,   EAP_TLS_RECORD_RECV_FIRST ,   EAP_TLS_RECORD_RECV_MORE ,   EAP_TLS_RECORD_RECV_COMPLETE }

Functions
int	eap_crypto_mppe_keys (request_t *request, SSL *ssl, eap_tls_prf_label_t *prf_label)
	Generate keys according to RFC 5216 and add to the reply. More...
void	eap_crypto_prf_label_init (eap_tls_prf_label_t *prf_label, eap_session_t *eap_session, char const *keying_prf_label, size_t keying_prf_label_len)
	Initialize the PRF label fields. More...
int	eap_crypto_tls_session_id (TALLOC_CTX *ctx, request_t *request, SSL *ssl, eap_tls_prf_label_t *prf_label, uint8_t **out, uint8_t eap_type)
int	eap_tls_compose (request_t *request, eap_session_t *eap_session, eap_tls_status_t status, uint8_t flags, fr_tls_record_t *record, size_t record_len, size_t frag_len)
	Convert the EAP-TLS reply packet into an EAP packet. More...
fr_tls_conf_t *	eap_tls_conf_parse (CONF_SECTION *cs, char const *key)
	Parse TLS configuration. More...
int	eap_tls_fail (request_t *request, eap_session_t *eap_session)
	Send an EAP-TLS failure. More...
unlang_action_t	eap_tls_process (request_t *request, eap_session_t *eap_session)
	Process an EAP TLS request. More...
int	eap_tls_request (request_t *request, eap_session_t *eap_session)
	Frames the OpenSSL data that needs to be sent to the client in an EAP-Request. More...
eap_tls_session_t *	eap_tls_session_init (request_t *request, eap_session_t *eap_session, SSL_CTX *ssl_ctx, bool client_cert)
	Create a new fr_tls_session_t associated with an eap_session_t. More...
int	eap_tls_start (request_t *request, eap_session_t *eap_session)
	Send an initial EAP-TLS request to the peer. More...
int	eap_tls_success (request_t *request, eap_session_t *eap_session, eap_tls_prf_label_t *prf_label))
	Send an EAP-TLS success. More...

Variables
fr_table_num_ordered_t const	eap_tls_status_table []
size_t	eap_tls_status_table_len

Detailed Description

Generic EAP over TLS API.

Id

5d63710780e3beabd8dcb6610f7c4a32fca5ef58

Copyright

2001 hereUare Communications, Inc. (raghu.nosp@m.d@he.nosp@m.reuar.nosp@m.e.co.nosp@m.m)

2003 Alan DeKok (aland.nosp@m.@fre.nosp@m.eradi.nosp@m.us.o.nosp@m.rg)

2006 The FreeRADIUS server project

Definition in file tls.h.

---

Data Structure Documentation

eap_tls_data_t

struct eap_tls_data_t

Definition at line 114 of file tls.h.

Data Fields
uint8_t	data[1]
uint8_t	flags

eap_tls_prf_label_t

struct eap_tls_prf_label_t

Definition at line 154 of file tls.h.

Data Fields
uint8_t	context[1]	for TLS 1.3 context, is the EAP Type code
size_t	context_len	length of the context
char const *	keying_prf_label	PRF label to use for generating keying material. If NULL, no MPPE keys will be generated.
size_t	keying_prf_label_len	length of the keying PRF label.
char const *	sessid_prf_label	PRF label to use when generating the session ID. If NULL, session ID will be based on client/server randoms.
size_t	sessid_prf_label_len	Length of the session ID PRF label.
int	use_context	for SSL_export_keying_material().

eap_tls_session_t

struct eap_tls_session_t

Tracks the state of an EAP-TLS session.

Contains any EAP-TLS specific state information, such as whether we're sending/receiving fragments, and the progress of those operations.

TLS session state is stored in a fr_tls_session_t accessed via the tls_session field.

Definition at line 126 of file tls.h.

Data Fields
bool	authentication_success
int	base_flags	Some protocols use the reserved bits of the EAP-TLS flags (such as PEAP). This allows the base flags to be set.
bool	include_length	A flag to include length in every TLS Data/Alert packet. If set to no then only the first fragment contains length.
bool	phase2	Whether we're in phase 2.
size_t	record_in_recvd_len	How much of the record we've received so far.
bool	record_in_started	Whether a record transfer from the peer is currently in progress.
size_t	record_in_total_len	How long the peer indicated the complete tls record would be.
bool	record_out_started	for methods with inner auth, if the inner auth succeeded. Whether a record transfer to the peer is currently in progress.
size_t	record_out_total_len	Actual/Total TLS message length we're sending.
eap_tls_status_t	state	The state of the EAP-TLS session.
fr_tls_session_t *	tls_session	TLS session used to authenticate peer or tunnel sensitive data.

Macro Definition Documentation

SET_LENGTH_INCLUDED

#define SET_LENGTH_INCLUDED

(

x

)

((x) | (0x80))

Definition at line 88 of file tls.h.

SET_MORE_FRAGMENTS

#define SET_MORE_FRAGMENTS

(

x

)

((x) | (0x40))

Definition at line 87 of file tls.h.

SET_START

#define SET_START

(

x

)

((x) | (0x20))

Definition at line 86 of file tls.h.

TLS_ALERT

#define TLS_ALERT

(

x

)

(((x) & 0x0015) == 0x0015)

Definition at line 83 of file tls.h.

TLS_CHANGE_CIPHER_SPEC

#define TLS_CHANGE_CIPHER_SPEC

(

x

)

(((x) & 0x0014) == 0x0014)

Definition at line 82 of file tls.h.

TLS_HANDSHAKE

#define TLS_HANDSHAKE

(

x

)

(((x) & 0x0016) == 0x0016)

Definition at line 84 of file tls.h.

TLS_HEADER_LEN

#define TLS_HEADER_LEN   4

Definition at line 55 of file tls.h.

TLS_HEADER_LENGTH_FIELD_LEN

#define TLS_HEADER_LENGTH_FIELD_LEN   4

Definition at line 56 of file tls.h.

TLS_LENGTH_INCLUDED

#define TLS_LENGTH_INCLUDED

(

x

)

(((x) & 0x80) != 0)

Definition at line 80 of file tls.h.

TLS_MORE_FRAGMENTS

#define TLS_MORE_FRAGMENTS

(

x

)

(((x) & 0x40) != 0)

Definition at line 79 of file tls.h.

TLS_RESERVED0

#define TLS_RESERVED0

(

x

)

(((x) & 0x10) != 0)

Definition at line 77 of file tls.h.

TLS_RESERVED1

#define TLS_RESERVED1

(

x

)

(((x) & 0x08) != 0)

Definition at line 76 of file tls.h.

TLS_RESERVED2

#define TLS_RESERVED2

(

x

)

(((x) & 0x04) != 0)

Definition at line 75 of file tls.h.

TLS_RESERVED3

#define TLS_RESERVED3

(

x

)

(((x) & 0x02) != 0)

Definition at line 74 of file tls.h.

TLS_RESERVED4

#define TLS_RESERVED4

(

x

)

(((x) & 0x01) != 0)

Definition at line 73 of file tls.h.

TLS_START

#define TLS_START

(

x

)

(((x) & 0x20) != 0)

Definition at line 78 of file tls.h.

Enumeration Type Documentation

eap_tls_status_t

enum eap_tls_status_t

Enumerator
EAP_TLS_INVALID	Invalid, don't reply.
EAP_TLS_ESTABLISHED	Session established, send success (or start phase2).
EAP_TLS_FAIL	Fail, send fail.
EAP_TLS_HANDLED	TLS code has handled it.
EAP_TLS_START_SEND	We're starting a new TLS session.
EAP_TLS_RECORD_SEND	We're sending a record.
EAP_TLS_ACK_SEND	Acknowledge receipt of a record or record fragment.
EAP_TLS_RECORD_RECV_FIRST	Received first fragment of a record.
EAP_TLS_RECORD_RECV_MORE	Received additional fragment of a record.
EAP_TLS_RECORD_RECV_COMPLETE	Received final fragment of a record.

Definition at line 90 of file tls.h.

Function Documentation

eap_crypto_mppe_keys()

int eap_crypto_mppe_keys	(	request_t *	request,
		SSL *	ssl,
		eap_tls_prf_label_t *	prf_label
	)

Generate keys according to RFC 5216 and add to the reply.

Definition at line 85 of file crypto.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_crypto_prf_label_init()

void eap_crypto_prf_label_init	(	eap_tls_prf_label_t *	prf_label,
		eap_session_t *	eap_session,
		char const *	keying_prf_label,
		size_t	keying_prf_label_len
	)

Initialize the PRF label fields.

Definition at line 48 of file crypto.c.

Here is the caller graph for this function:

eap_crypto_tls_session_id()

int eap_crypto_tls_session_id	(	TALLOC_CTX *	ctx,
		request_t *	request,
		SSL *	ssl,
		eap_tls_prf_label_t *	prf_label,
		uint8_t **	out,
		uint8_t	eap_type
	)

Definition at line 132 of file crypto.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_compose()

int eap_tls_compose	(	request_t *	request,
		eap_session_t *	eap_session,
		eap_tls_status_t	status,
		uint8_t	flags,
		fr_tls_record_t *	record,
		size_t	record_len,
		size_t	frag_len
	)

Convert the EAP-TLS reply packet into an EAP packet.

The EAP packet will be written to eap_round->request, with the original reply being untouched.

Parameters

[in]	request	The current subrequest.
[in]	eap_session	to continue.
[in]	status	What type of packet we're sending.
[in]	flags	to set. This is checked to determine if we need to include a length field.
[in]	record	The record buffer to read from. This most only be set for EAP_TLS_RECORD_SEND packets.
[in]	record_len	the length of the record we're sending.
[in]	frag_len	the length of the fragment we're sending.

Returns

• 0 on success.
• -1 on failure.

Definition at line 114 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_conf_parse()

fr_tls_conf_t* eap_tls_conf_parse	(	CONF_SECTION *	cs,
		char const *	attr
	)

Parse TLS configuration.

If the option given by 'attr' is set, we find the config section of that name and use that for the TLS configuration. If not, we fall back to compatibility mode and read the TLS options from the 'tls' section.

Parameters

cs	to derive the configuration from.
attr	identifier for common TLS configuration.

Returns

• NULL on error.
• A new fr_tls_conf_t on success.

Definition at line 1231 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_fail()

int eap_tls_fail	(	request_t *	request,
		eap_session_t *	eap_session
	)

Send an EAP-TLS failure.

Composes an EAP-TLS-Failure. This is a message with code EAP_TLS_FAILURE. It contains no cryptographic material, and is not protected.

In addition to sending the failure, will destroy any cached session data.

Parameters

[in]	request	The current subrequest.
[in]	eap_session	that failed.

Returns

• 0 on success.
• -1 on failure (to compose a valid packet).

Definition at line 322 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_process()

unlang_action_t eap_tls_process	(	request_t *	request,
		eap_session_t *	eap_session
	)

Process an EAP TLS request.

Here we implement a basic state machine. The state machine is implicit and is driven by the state of the TLS session and the flags sent. INCOMING DATA:

1. EAP-TLS should get the complete TLS data from the peer.
2. Store that data in a data structure with any other required info
3. Hand this data structure to the TLS module.
4. TLS module will perform its operations on the data and hands back to EAP-TLS OUTGOING DATA:

1. EAP-TLS if necessary will fragment it and send it to the destination.

During EAP-TLS initialization, TLS Context object will be initialised and stored. For every new authentication request, TLS will open a new session object and that session object SHOULD be maintained even after the session is completed, for session resumption.

Parameters

request	the request
eap_session	to continue.

Returns

• EAP_TLS_ESTABLISHED
• EAP_TLS_HANDLED

Definition at line 963 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_request()

int eap_tls_request	(	request_t *	request,
		eap_session_t *	eap_session
	)

Frames the OpenSSL data that needs to be sent to the client in an EAP-Request.

A single TLS record may be up to 16384 octets in length, but a TLS message may span multiple TLS records, and a TLS certificate message may theoretically, be as big as 16MB.

In EAP-TLS with no inner method, this is used primarily to send our certificate chain to the peer.

In other methods this function is also called to package up application data for the inner tunnel method.

The eap_tls_session->length_included flag determines whether we include the extra four byte length field in the request and set the L flag.

If present, the tls_length field indicates the total length of the reassembled TLS record.

If eap_tls_session->length_included this means we include L flag and the tls_length field in EVERY packet we send out.

If !eap_tls_session->length_included this means we include L flag and tls_length field ONLY in First packet of a fragment series. We do not use it anywhere else.

Parameters

request	the request
eap_session	that's continuing.

Returns

• 0 on success.
• -1 on failure.

Definition at line 372 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_session_init()

eap_tls_session_t* eap_tls_session_init	(	request_t *	request,
		eap_session_t *	eap_session,
		SSL_CTX *	ssl_ctx,
		bool	client_cert
	)

Create a new fr_tls_session_t associated with an eap_session_t.

Creates a new server fr_tls_session_t and associates it with an eap_session_t adding EAP specific opaque data to the SSL session created during fr_tls_session_t initialisation.

Parameters

[in]	request	The current subrequest.
[in]	eap_session	to use as a context for the eap_tls_session_t
[in]	ssl_ctx	to use to configure the fr_tls_session_t.
[in]	client_cert	Whether we require the peer to prevent a certificate.

Returns

• A new eap_tls_session on success.
• NULL on error.

Definition at line 1131 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_start()

int eap_tls_start	(	request_t *	request,
		eap_session_t *	eap_session
	)

Send an initial EAP-TLS request to the peer.

Once having received the peer's Identity, the EAP server MUST respond with an EAP-TLS/Start packet, which is an EAP-Request packet with EAP-Type = EAP-TLS, the Start (S) bit set, and no data.

The EAP-TLS conversation will then begin, with the peer sending an EAP-Response packet with EAP-Type = EAP-TLS. The data field of that packet will be the TLS data.

The S flag is set only within the EAP-TLS start message sent from the EAP server to the peer.

• len = header + type + tls_typedata
• tls_typedata = flags(Start (S) bit set, and no data)

Fragment length is Framed-MTU - 4.

Parameters

[in]	request	The current subrequest.
[in]	eap_session	to initiate.

Returns

• 0 on success.
• -1 on failure.

Definition at line 239 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

eap_tls_success()

int eap_tls_success	(	request_t *	request,
		eap_session_t *	eap_session,
		eap_tls_prf_label_t *	prf_label
	)

Send an EAP-TLS success.

Composes an EAP-TLS-Success. This is a message with code EAP_TLS_ESTABLISHED. It contains no cryptographic material, and is not protected.

We add the MPPE keys here. These are used by the NAS. The supplicant will derive the same keys separately.

Parameters

[in]	request	The current subrequest.
[in]	eap_session	that completed successfully.
[in]	prf_label	PRF label struct

Returns

• 0 on success.
• -1 on failure.

Definition at line 264 of file tls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

eap_tls_status_table

fr_table_num_ordered_t const eap_tls_status_table[]

extern

Definition at line 80 of file tls.c.

eap_tls_status_table_len

size_t eap_tls_status_table_len

extern

Definition at line 94 of file tls.c.