Enterprise Security Library
•All Data Structures Functions Variables Typedefs Enumerations Enumerator Modules Pages
Overview

Enterprise Security library provides the capability for Infineon's best-in-class Wi-Fi enabled PSoC™ 6 devices to connect to enterprise Wi-Fi networks. This library implements a collection of the most commonly used Extensible Authentication Protocols (EAP) that are commonly used in enterprise networks. This library is an embedded variant of the Wi-Fi supplicant (minimal features) that runs on an RTOS and provides the ability to securely join enterprise security networks (802.1x) using various EAP authentication protocols.

Features and Functionality

  • Supports the following EAP security protocols:
    • EAP-TLS
    • PEAPv0 with MSCHAPv2
    • EAP-TTLS with EAP-MSCHAPv2 (Phase 2 tunnel authentication supports only EAP methods)
  • Supports TLS session (session ID based) resumption
  • Supports 'PEAP Fast reconnect' (applicable only for PEAP protocol)
  • Supports roaming across APs in the enterprise network (vanilla roaming)
  • Supports TLS versions 1.0, 1.1, and 1.2

Note: Deviations for Threadx :

  • Does not support TLS session resumption.
  • Supports TLS1.3 in addition to TLS 1.0, 1.1 and 1.2. Only ECDSA key and certificate is supported with TLS1.3.

This library provides application developers an easy-to-use, unified interface for quickly enabling enterprise security in their applications. The library provides a single interface to join and leave 802.1x networks using different protocols.

Supported Enterprise Security Modes

  • WPA
  • WPA2
  • WPA3 Transition
  • WPA3 Enterprise only
  • WPA3 192Bit

Note: WPA3 Enterprise Modes are supported for Threadx only.

Supported Frameworks

  • ModusToolbox™ environment: In this environment the Enterprise Security library uses the abstraction-rtos library that provides the RTOS abstraction API and the wcm library for network functions.

Supported Platforms

ModusToolbox™

Dependent Libraries

ModusToolbox™

RADIUS Servers

This library has been verified with enterprise Wi-Fi networks configured using the following RADIUS server(s):

  • FreeRadius 3.0.15

Quick Start

This library is supported on ModusToolbox™ environments. Enterprise security library supports 2 combinations "FreeRTOS, lwIP, Mbed TLS" and "Threadx, NetxDuo, NetxSecure". The section below provides information on how to build the library in these environments.

FreeRTOS, lwIP, and Mbed TLS

  • To use enterprise-security library on Wi-Fi kits with FreeRTOS, lwIP, and Mbed TLS combination, the application should pull wifi-core-freertos-lwip-mbedtls library which will internally pull all dependent modules. To pull wifi-core-freertos-lwip-mbedtls create the following *.mtb* file in deps folder.

A set of pre-defined configuration files for FreeRTOS, lwIP, and Mbed TLS combination is bundled in wifi-core-freertos-lwip-mbedtls library for Wi-Fi kits. The developer is expected to review the configuration and make adjustments.

  • Make the following changes to the default mbed TLS configurations in mbedtls_user_config.h:
    • Enable the following flags:
      MBEDTLS_DES_C, MBEDTLS_MD4_C, MBEDTLS_MD5_C, MBEDTLS_SHA1_C, MBEDTLS_SSL_PROTO_TLS1, MBEDTLS_SSL_PROTO_TLS1_1, and MBEDTLS_SSL_EXPORT_KEYS
    • Disable the following flags:
      MBEDTLS_POLY1305_C, MBEDTLS_CHACHAPOLY_C, and MBEDTLS_CHACHA20_C
  • Define the following COMPONENTS in the application's Makefile for the Enterprise Security library.
    COMPONENTS=FREERTOS PSOC6HAL MBEDTLS LWIP WCM
  • By default, the macro MBEDTLS_HAVE_TIME_DATE is undefined in mbedtls_user_config.h. If application wishes to perform time and date validation on the certificate, then define the MBEDTLS_HAVE_TIME_DATE flag in mbedtls_user_config.h.

Threadx, NetxDuo, and NetxSecure

  • To use enterprise-security library with Wi-Fi kits on Threadx, NetxDuo, and NetxSecure combination, the application should pull wifi-core-threadx-netxduo-netxsecure library which will internall pull all dependent modules except nx-secure-wpa3.
  • To pull wifi-core-threadx-netxduo-netxsecure create the following *.mtb* file in deps folder.
    • wifi-core-threadx-netxduo-netxsecure.mtb: mtb://wifi-core-threadx-netxduo-netxsecure#latest-v1.X#$$ASSET_REPO$$/wifi-core-threadx-netxduo-netxsecure/latest-v1.X
  • To pull nx-secure-wpa3 create the following *.mtb* file in deps folder.
    • nx-secure-wpa3.mtb: mtb://nx-secure-wpa3#latest-v1.X#$$ASSET_REPO$$/nx-secure-wpa3/latest-v1.X
  • A set of pre-defined configuration files is bundled in wifi-core-threadx-netxduo-netxsecure library for Wi-Fi kits. The developer is expected to review the configuration and make adjustments.
  • Define the following COMPONENTS in the application's Makefile for the Enterprise Security library.
    COMPONENTS=THREADX NETXDUO NETXSECURE NETXSECURE_WPA3
    DISABLE_COMPONENTS+=NETXSECURE_ROM

Logging

Enterprise Security library disables all the debug log messages by default. To enable log messages, the application must perform the following:

  • Add ENABLE_ENTERPRISE_SECURITY_LOGS macro to the DEFINES in the application's Makefile. The Makefile entry would look as follows:
    DEFINES+=ENABLE_ENTERPRISE_SECURITY_LOGS
  • Call the cy_log_init() function provided by the cy-log module. cy-log is part of the connectivity-utilities library. See connectivity-utilities library API documentation for cy-log details.

Code Snippets

This section provides code snippets for this library on ModusToolbox™ environement. The code snippets given under the ModusToolbox™ section uses C APIs

  • ModusToolbox™ - Snippets for Enterprise security create, join, leave, and delete (C implementation).

ModusToolbox™

Code Snippet 1: Enterprise Security Join and Leave (EAP-TLS)

Creates an Enterprise Security instance and performs join and leave using cy_enterprise_security_join and cy_enterprise_security_leave APIs respectively with EAP-TLS.

#include <stdio.h>
#include "cy_enterprise_security.h"
#include "certificate.h"
/******************************************************
* Macros
******************************************************/
#define RADIUS_SERVER_IDENTITY "svtuser"
#define RADIUS_SERVER_PASSWORD "hnd@123"
#define ENTERPRISE_SECURITY_NW_SSID "ENT_SEC_NW_2G"
#define APP_INFO( x ) printf x
/************************************************************
* Global Variables *
************************************************************/
/* Enterprise Security parameters */
static cy_enterprise_security_parameters_t ent_parameters;
/* Enterprise Security instance handle */
static cy_enterprise_security_t handle;
cy_rslt_t ent_sec_join_leave_eap_tls()
{
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Set the Enterprise Security parameters. */
ent_parameters.ca_cert = (char*) WIFI_ROOT_CERTIFICATE_STRING; /* Defined in certificate.h */
ent_parameters.client_cert = (char*) WIFI_USER_CERTIFICATE_STRING; /* Defined in certificate.h */
ent_parameters.client_key = (char*) WIFI_USER_PRIVATE_KEY_STRING; /* Defined in certificate.h */
memcpy(ent_parameters.ssid, (char *)ENTERPRISE_SECURITY_NW_SSID, strlen(ENTERPRISE_SECURITY_NW_SSID) + 1);
memcpy(ent_parameters.outer_eap_identity, (char *)RADIUS_SERVER_IDENTITY, strlen(RADIUS_SERVER_IDENTITY) + 1);
ent_parameters.eap_type = CY_ENTERPRISE_SECURITY_EAP_TYPE_TLS;
ent_parameters.auth_type = CY_ENTERPRISE_SECURITY_AUTH_TYPE_WPA2_MIXED;
/* Create the Enterprise Security instance and get the handle. */
result = cy_enterprise_security_create(&handle, &ent_parameters);
if( result != CY_RSLT_SUCCESS )
{
APP_INFO(("Failed to create Enterprise Security instance with error %u\n", (unsigned int)result));
return CY_RSLT_ERROR;
}
/* Join the enterprise security network. */
result = cy_enterprise_security_join(handle);
if( result == CY_RSLT_SUCCESS )
{
APP_INFO(("Joining an Enterprise Security network is successful.\n"));
}
else
{
APP_INFO(("Joining an Enterprise Security network failed with error %u\n", (unsigned int)result));
goto cleanup;
}
/* Enterprise Security join is successful. Insert other logic here. */
/* Leave the enterprise security network. */
result = cy_enterprise_security_leave(handle);
if( result == CY_RSLT_SUCCESS )
{
APP_INFO(("Leaving an Enterprise Security network is successful.\n"));
}
else
{
APP_INFO(("Leaving an Enterprise Security network failed with error %u\n", (unsigned int)result));
goto cleanup;
}
cleanup:
/* Dispose the Enterprise Security instance. */
cy_enterprise_security_delete(&handle);
if( result != CY_RSLT_SUCCESS )
{
APP_INFO(("Failed to delete Enterprise Security instance with error %u\n", (unsigned int)result));
return CY_RSLT_ERROR;
}
return result;
}
CY_ENTERPRISE_SECURITY_AUTH_TYPE_WPA2_MIXED
@ CY_ENTERPRISE_SECURITY_AUTH_TYPE_WPA2_MIXED
WPA2 Enterprise Security with AES and TKIP.
Definition: cy_enterprise_security.h:62
CY_ENTERPRISE_SECURITY_EAP_TYPE_TLS
@ CY_ENTERPRISE_SECURITY_EAP_TYPE_TLS
EAP-TLS type refer to RFC 2716.
Definition: cy_enterprise_security.h:103
cy_enterprise_security_join
cy_rslt_t cy_enterprise_security_join(cy_enterprise_security_t handle)
Joins an enterprise security network (802.1x Access point)
cy_enterprise_security_leave
cy_rslt_t cy_enterprise_security_leave(cy_enterprise_security_t handle)
Leaves an enterprise security network (802.1x Access point)
cy_enterprise_security_create
cy_rslt_t cy_enterprise_security_create(cy_enterprise_security_t *handle, cy_enterprise_security_parameters_t *ent_parameters)
Creates an Enterprise Security instance.
cy_enterprise_security_delete
cy_rslt_t cy_enterprise_security_delete(cy_enterprise_security_t *handle)
Deletes the given Enterprise Security instance and resources allocated by the cy_enterprise_security_...
cy_enterprise_security_t
void * cy_enterprise_security_t
Enterprise Security instance.
Definition: cy_enterprise_security.h:129
cy_enterprise_security_parameters_t
Enterprise Security parameters.
Definition: cy_enterprise_security.h:163
cy_enterprise_security_parameters_t::eap_type
cy_enterprise_security_eap_type_t eap_type
Authentication mechanism to be used.
Definition: cy_enterprise_security.h:165
cy_enterprise_security_parameters_t::ssid
char ssid[CY_ENTERPRISE_SECURITY_MAX_SSID_LENGTH]
Wi-Fi SSID.
Definition: cy_enterprise_security.h:164
cy_enterprise_security_parameters_t::client_cert
char * client_cert
Client certificate in PEM format.
Definition: cy_enterprise_security.h:167
cy_enterprise_security_parameters_t::auth_type
cy_enterprise_security_auth_t auth_type
Security auth type used.
Definition: cy_enterprise_security.h:169
cy_enterprise_security_parameters_t::ca_cert
char * ca_cert
CA certificate in PEM format.
Definition: cy_enterprise_security.h:166
cy_enterprise_security_parameters_t::outer_eap_identity
char outer_eap_identity[CY_ENTERPRISE_SECURITY_MAX_IDENTITY_LENGTH]
Outer EAP identity.
Definition: cy_enterprise_security.h:170
cy_enterprise_security_parameters_t::client_key
char * client_key
Client private key in PEM format.
Definition: cy_enterprise_security.h:168

Code Snippet 2: Enterprise Security Join and Leave (PEAP)

Creates an Enterprise Security instance and performs join and leave using cy_enterprise_security_join and cy_enterprise_security_leave APIs respectively with PEAP.

#include <stdio.h>
#include "cy_enterprise_security.h"
#include "certificate.h"
/******************************************************
* Macros
******************************************************/
#define RADIUS_SERVER_IDENTITY "svtuser"
#define RADIUS_SERVER_PASSWORD "hnd@123"
#define ENTERPRISE_SECURITY_NW_SSID "ENT_SEC_NW_2G"
#define APP_INFO( x ) printf x
/************************************************************
* Global Variables *
************************************************************/
/* Enterprise Security parameters */
static cy_enterprise_security_parameters_t ent_parameters;
/* Enterprise Security instance handle */
static cy_enterprise_security_t handle;
cy_rslt_t ent_sec_join_leave_peap()
{
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Set the Enterprise Security parameters. */
ent_parameters.ca_cert = (char*) WIFI_ROOT_CERTIFICATE_STRING; /* Defined in certificate.h */
ent_parameters.client_cert = (char*) WIFI_USER_CERTIFICATE_STRING; /* Defined in certificate.h */
ent_parameters.client_key = (char*) WIFI_USER_PRIVATE_KEY_STRING; /* Defined in certificate.h */
memcpy(ent_parameters.ssid, (char *)ENTERPRISE_SECURITY_NW_SSID, strlen(ENTERPRISE_SECURITY_NW_SSID) + 1);
memcpy(ent_parameters.outer_eap_identity, (char *)RADIUS_SERVER_IDENTITY, strlen(RADIUS_SERVER_IDENTITY) + 1);
ent_parameters.eap_type = CY_ENTERPRISE_SECURITY_EAP_TYPE_PEAP;
ent_parameters.auth_type = CY_ENTERPRISE_SECURITY_AUTH_TYPE_WPA2_MIXED;
memcpy(ent_parameters.phase2.inner_identity, (char *)RADIUS_SERVER_IDENTITY, strlen(RADIUS_SERVER_IDENTITY) + 1);
memcpy(ent_parameters.phase2.inner_password, (char *)RADIUS_SERVER_PASSWORD, strlen(RADIUS_SERVER_PASSWORD) + 1);
ent_parameters.phase2.inner_eap_type = CY_ENTERPRISE_SECURITY_EAP_TYPE_MSCHAPV2;
ent_parameters.phase2.tunnel_auth_type = CY_ENTERPRISE_SECURITY_TUNNEL_TYPE_MSCHAPV2;
/* Create the Enterprise Security instance and get the handle. */
result = cy_enterprise_security_create(&handle, &ent_parameters);
if( result != CY_RSLT_SUCCESS )
{
APP_INFO(("Failed to create Enterprise Security instance with error %u\n", (unsigned int)result));
return CY_RSLT_ERROR;
}
/* Join the enterprise security network. */
result = cy_enterprise_security_join(handle);
if( result == CY_RSLT_SUCCESS )
{
APP_INFO(("Joining an Enterprise Security network is successful.\n"));
}
else
{
APP_INFO(("Joining an Enterprise Security network failed with error %u\n", (unsigned int)result));
goto cleanup;
}
/* Enterprise Security join is successful. Insert other logic here. */
/* Leave the enterprise security network. */
result = cy_enterprise_security_leave(handle);
if( result == CY_RSLT_SUCCESS )
{
APP_INFO(("Leaving an Enterprise Security network is successful.\n"));
}
else
{
APP_INFO(("Leaving an Enterprise Security network failed with error %u\n", (unsigned int)result));
goto cleanup;
}
cleanup:
/* Dispose the Enterprise Security instance. */
cy_enterprise_security_delete(&handle);
if( result != CY_RSLT_SUCCESS )
{
APP_INFO(("Failed to delete Enterprise Security instance with error %u\n", (unsigned int)result));
return CY_RSLT_ERROR;
}
return result;
}
CY_ENTERPRISE_SECURITY_TUNNEL_TYPE_MSCHAPV2
@ CY_ENTERPRISE_SECURITY_TUNNEL_TYPE_MSCHAPV2
MSCHAPv2 as tunnel EAP type.
Definition: cy_enterprise_security.h:85
CY_ENTERPRISE_SECURITY_EAP_TYPE_MSCHAPV2
@ CY_ENTERPRISE_SECURITY_EAP_TYPE_MSCHAPV2
MSCHAPv2 type refer to draft-kamath-pppext-eap-mschapv2-00.txt.
Definition: cy_enterprise_security.h:109
CY_ENTERPRISE_SECURITY_EAP_TYPE_PEAP
@ CY_ENTERPRISE_SECURITY_EAP_TYPE_PEAP
PEAP type refer to draft-josefsson-pppext-eap-tls-eap-06.txt.
Definition: cy_enterprise_security.h:108
cy_enterprise_security_parameters_t::phase2
cy_enterprise_security_phase2_params_t phase2
Phase2 authentication parameters.
Definition: cy_enterprise_security.h:172
cy_enterprise_security_phase2_params_t::tunnel_auth_type
cy_enterprise_security_tunnel_t tunnel_auth_type
Tunnel authentication type.
Definition: cy_enterprise_security.h:150
cy_enterprise_security_phase2_params_t::inner_eap_type
cy_enterprise_security_eap_type_t inner_eap_type
Inner EAP type.
Definition: cy_enterprise_security.h:151
cy_enterprise_security_phase2_params_t::inner_password
char inner_password[CY_ENTERPRISE_SECURITY_MAX_PASSWORD_LENGTH]
Inner user password.
Definition: cy_enterprise_security.h:153
cy_enterprise_security_phase2_params_t::inner_identity
char inner_identity[CY_ENTERPRISE_SECURITY_MAX_IDENTITY_LENGTH]
Inner user identity.
Definition: cy_enterprise_security.h:152

Code Snippet 3: Enterprise Security Join and Leave (EAP-TTLS)

Creates an Enterprise Security instance and performs join and leave using cy_enterprise_security_join and cy_enterprise_security_leave APIs respectively with EAP-TTLS.

#include <stdio.h>
#include "cy_enterprise_security.h"
#include "certificate.h"
/******************************************************
* Macros
******************************************************/
#define RADIUS_SERVER_IDENTITY "svtuser"
#define RADIUS_SERVER_PASSWORD "hnd@123"
#define ENTERPRISE_SECURITY_NW_SSID "ENT_SEC_NW_2G"
#define APP_INFO( x ) printf x
/************************************************************
* Global Variables *
************************************************************/
/* Enterprise Security parameters */
static cy_enterprise_security_parameters_t ent_parameters;
/* Enterprise Security instance handle */
static cy_enterprise_security_t handle;
cy_rslt_t ent_sec_join_leave_eap_ttls()
{
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Set the Enterprise Security parameters. */
ent_parameters.ca_cert = (char*) WIFI_ROOT_CERTIFICATE_STRING; /* Defined in certificate.h */
ent_parameters.client_cert = (char*) WIFI_USER_CERTIFICATE_STRING; /* Defined in certificate.h */
ent_parameters.client_key = (char*) WIFI_USER_PRIVATE_KEY_STRING; /* Defined in certificate.h */
memcpy(ent_parameters.ssid, (char *)ENTERPRISE_SECURITY_NW_SSID, strlen(ENTERPRISE_SECURITY_NW_SSID) + 1);
memcpy(ent_parameters.outer_eap_identity, (char *)RADIUS_SERVER_IDENTITY, strlen(RADIUS_SERVER_IDENTITY) + 1);
ent_parameters.eap_type = CY_ENTERPRISE_SECURITY_EAP_TYPE_TTLS;
ent_parameters.auth_type = CY_ENTERPRISE_SECURITY_AUTH_TYPE_WPA2_MIXED;
memcpy(ent_parameters.phase2.inner_identity, (char *)RADIUS_SERVER_IDENTITY, strlen(RADIUS_SERVER_IDENTITY) + 1);
memcpy(ent_parameters.phase2.inner_password, (char *)RADIUS_SERVER_PASSWORD, strlen(RADIUS_SERVER_PASSWORD) + 1);
ent_parameters.phase2.inner_eap_type = CY_ENTERPRISE_SECURITY_EAP_TYPE_MSCHAPV2;
ent_parameters.phase2.tunnel_auth_type = CY_ENTERPRISE_SECURITY_TUNNEL_TYPE_EAP;
/* Create the Enterprise Security instance and get the handle. */
result = cy_enterprise_security_create(&handle, &ent_parameters);
if( result != CY_RSLT_SUCCESS )
{
APP_INFO(("Failed to create Enterprise Security instance with error %u\n", (unsigned int)result));
return CY_RSLT_ERROR;
}
/* Join the enterprise security network. */
result = cy_enterprise_security_join(handle);
if( result == CY_RSLT_SUCCESS )
{
APP_INFO(("Joining an Enterprise Security network is successful.\n"));
}
else
{
APP_INFO(("Joining an Enterprise Security network failed with error %u\n", (unsigned int)result));
goto cleanup;
}
/* Enterprise Security join is successful. Insert other logic here. */
/* Leave the enterprise security network. */
result = cy_enterprise_security_leave(handle);
if( result == CY_RSLT_SUCCESS )
{
APP_INFO(("Leaving an Enterprise Security network is successful.\n"));
}
else
{
APP_INFO(("Leaving an Enterprise Security network failed with error %u\n", (unsigned int)result));
goto cleanup;
}
cleanup:
/* Dispose the Enterprise Security instance. */
cy_enterprise_security_delete(&handle);
if( result != CY_RSLT_SUCCESS )
{
APP_INFO(("Failed to delete Enterprise Security instance with error %u\n", (unsigned int)result));
return CY_RSLT_ERROR;
}
return result;
}
CY_ENTERPRISE_SECURITY_TUNNEL_TYPE_EAP
@ CY_ENTERPRISE_SECURITY_TUNNEL_TYPE_EAP
EAP as tunnel EAP type.
Definition: cy_enterprise_security.h:82
CY_ENTERPRISE_SECURITY_EAP_TYPE_TTLS
@ CY_ENTERPRISE_SECURITY_EAP_TYPE_TTLS
EAP-TTLS type refer to draft-ietf-pppext-eap-ttls-02.txt.
Definition: cy_enterprise_security.h:106