/* ipeap.h - Public API for the Wind River Extensible Authentication Protocol (EAP) */ /* ****************************************************************************** * INTERPEAK API HEADER FILE * * Document no: @(#) $Name: VXWORKS_ITER40_2019102207 $ $RCSfile: ipeap.h,v $ $Revision: 1.27 $ * $Source: /home/interpeak/CVSRoot/ipeap/include/ipeap.h,v $ * $Author: hchowdhu $ $Date: 2010-06-28 21:39:10 $ * $State: Exp $ $Locker: $ * * INTERPEAK_COPYRIGHT_STRING * Design and implementation by Roger Boden ****************************************************************************** */ #ifndef IPEAP_H #define IPEAP_H /* **************************************************************************** * 1 DESCRIPTION **************************************************************************** */ /* DESCRIPTION This library contains the APIs used for interfacing with the Wind River EAP component. */ /* **************************************************************************** * 2 CONFIGURATION **************************************************************************** */ /* **************************************************************************** * 3 INCLUDE FILES **************************************************************************** */ #include #include #include #ifdef __cplusplus extern "C" { #endif /* **************************************************************************** * 4 DEFINES **************************************************************************** */ #define IPEAP_RELEASE 60600 #define IPEAP_PKT_REQUEST 1 #define IPEAP_PKT_RESPONSE 2 #define IPEAP_PKT_SUCCESS 3 #define IPEAP_PKT_FAILURE 4 /* EAP modes */ #define IPEAP_MODE_SUPPLICANT 1 #define IPEAP_MODE_AUTHENTICATOR 2 /* EAP states */ #define IPEAP_STATE_INIT 1 #define IPEAP_STATE_HANDSHAKE 2 #define IPEAP_STATE_AUTHENTICATED 3 /* EAP mechanism IDs as defined in RFCs */ #define IPEAP_TYPE_UNDEFINED 0 #define IPEAP_TYPE_IDENTITY 1 #define IPEAP_TYPE_NOTIFICATION 2 #define IPEAP_TYPE_NAK 3 #define IPEAP_TYPE_MD5_CHALLENGE 4 #define IPEAP_TYPE_GTC 6 #define IPEAP_TYPE_TLS 13 #define IPEAP_TYPE_LEAP 17 #define IPEAP_TYPE_SIM 18 #define IPEAP_TYPE_TTLS 21 #define IPEAP_TYPE_AKA 23 #define IPEAP_TYPE_PEAP 25 #define IPEAP_TYPE_MSCHAPV2 26 #define IPEAP_TYPE_EXTENSIONS 33 #define IPEAP_TYPE_EXPANDED 254 /* Return values for ipeap_process_pkt */ #define IPEAP_PENDING_SEND_OUT_PKT 1 /* Keep in sync with IP8021X_EAP_PENDING */ #define IPEAP_DROPPED_PKT 2 /* Keep in sync with IP8021X_DROPPED_PKT */ #define IPEAP_SUCCESS 3 /* Keep in sync with IP8021X_EAP_SUCCESS */ #define IPEAP_FAILURE 4 /* Keep in sync with IP8021X_EAP_FAILURE */ #define IPEAP_PENDING_USER_INPUT 5 /* used when an EAP method requires user input (e.g. response to challenge) before proceeding */ #define IPEAP_OK_SEND_OUT_PKT 1 #define IPEAP_OK_NO_OUT_PKT 2 #define IPEAP_IDENTITY_MAX_LEN 128 #define IPEAP_USER_INPUT_STRING_MAX 128 /* Supported Vendor types for Expanded EAP */ #define IPEAP_VT_NONE 0x00000000UL #define IPEAP_VT_WSC_SIMPLE_CONFIG 0x00000001UL /* Use these instead of sizeof(Ipeap_pkt_hdr) and sizeof(Ipeap_expanded_pkt_hdr) */ #define IPEAP_PKT_HDR_LEN 5 #define IPEAP_EXP_PKT_HDR_LEN 12 /* Use these instead of sizeof(Ipeap_vendor_id) and sizeof(Ipeap_vendor_type) */ #define IPEAP_VENDOR_ID_LEN 3 #define IPEAP_VENDOR_TYPE_LEN 4 /* **************************************************************************** * 5 TYPES **************************************************************************** */ struct Ipeap_ctx_st; struct Ipeap_pkt_st; struct Ipeap_mech_entry_st; struct Ipeap_user_input_st; typedef Ip_err (*Ipeap_process_pkt)(struct Ipeap_ctx_st* ctx, struct Ipeap_pkt_st* in_pkt, struct Ipeap_pkt_st* reply_pkt); typedef Ip_err (*Ipeap_init)(struct Ipeap_ctx_st* ctx); typedef Ip_err (*Ipeap_free)(struct Ipeap_ctx_st* ctx); typedef Ip_err (*Ipeap_get_key)(struct Ipeap_ctx_st* ctx, Ip_u8 *key, int key_len); typedef Ip_err (*Ipeap_handle_user_input)(struct Ipeap_ctx_st* ctx, struct Ipeap_user_input_st* ui, struct Ipeap_pkt_st* reply_pkt); typedef Ip_err (*Ipeap_display_status)(struct Ipeap_ctx_st* ctx, char *str); typedef Ip_err (*Ipeap_get_eap_session_id)(struct Ipeap_ctx_st* ctx, Ip_u8 *session_id, Ip_u32 *session_id_len); /* Vendor-Id and Vendor-Type types for expanded EAP types */ struct Ipeap_vendor_id_st { Ip_u8 smi[3]; }; typedef struct Ipeap_vendor_id_st Ipeap_vendor_id; typedef Ip_u32 Ipeap_vendor_type; typedef struct Ipeap_methods_st { Ipeap_process_pkt process_pkt; Ipeap_init init; Ipeap_free free; Ipeap_get_key get_key; Ipeap_handle_user_input handle_user_input; Ipeap_display_status display_status; Ipeap_get_eap_session_id get_eap_session_id; } Ipeap_methods; typedef struct Ipeap_pkt_hdr_st { Ip_u8 code; Ip_u8 id; Ip_u16 len; Ip_u8 type; /* Only present in requests and responses */ } Ipeap_pkt_hdr; #include typedef IP_PACKED1 struct Ipeap_expanded_pkt_hdr_st { Ip_u8 code; Ip_u8 id; Ip_u16 len; Ip_u8 type; /* Only present in requests and responses */ Ipeap_vendor_id vendor_id; Ipeap_vendor_type vendor_type; } IP_PACKED2 Ipeap_expanded_pkt_hdr; #include struct Ipeap_pkt_st { int start; int end; int max_len; Ip_u8* data; }; typedef struct Ipeap_pkt_st Ipeap_pkt; /* Some EAP types (such as EAP-GTC) require user input to respond to an auth challenge. */ typedef enum { IPEAP_UI_CHALLENGE_RESP_STRING = 0 } Ipeap_user_input_type; typedef struct Ipeap_user_input_st { Ipeap_user_input_type ui_type; union { char challenge_resp_str[IPEAP_USER_INPUT_STRING_MAX]; /* NULL terminated string */ } ui_data; } Ipeap_user_input; /* **************************************************************************** * 6 FUNCTIONS **************************************************************************** */ IP_PUBLIC struct Ipeap_ctx_st* ipeap_ctx_new(int mode); IP_PUBLIC void ipeap_ctx_free(struct Ipeap_ctx_st* ctx); IP_PUBLIC Ip_err ipeap_handle_user_input(struct Ipeap_ctx_st* ctx, Ipeap_user_input* ui, Ipeap_pkt* out_pkt); IP_PUBLIC Ip_err ipeap_process_pkt(struct Ipeap_ctx_st* ctx, Ipeap_pkt* in_pkt, Ipeap_pkt* out_pkt); IP_PUBLIC Ip_err ipeap_get_key(struct Ipeap_ctx_st* ctx, Ip_u8 *key, int key_len); IP_PUBLIC Ipeap_pkt* ipeap_get_last_sent_pkt(struct Ipeap_ctx_st* ctx); IP_PUBLIC void ipeap_reset_last_id(struct Ipeap_ctx_st* ctx); IP_PUBLIC Ip_err ipeap_mech_type_register(Ip_u8 type, Ipeap_methods* callbacks); IP_PUBLIC Ip_err ipeap_mech_type_register_expanded(Ipeap_vendor_id vendor_id, Ipeap_vendor_type vendor_type, Ipeap_methods* callbacks); #ifdef IPEAP_USE_EAP_MD5 IP_PUBLIC Ipeap_methods* ipeap_md5_methods_get(void); #endif #ifdef IPEAP_USE_EAP_GTC IP_PUBLIC Ipeap_methods* ipeap_gtc_methods_get(void); #endif #ifdef IPEAP_USE_EAP_LEAP IP_PUBLIC Ipeap_methods* ipeap_leap_methods_get(void); #endif #ifdef IPEAP_USE_EAP_TLS IP_PUBLIC Ipeap_methods* ipeap_tls_suppl_methods_get(void); #endif #ifdef IPEAP_USE_EAP_TTLS IP_PUBLIC Ipeap_methods* ipeap_ttls_suppl_methods_get(void); #endif #ifdef IPEAP_USE_EAP_PEAP IP_PUBLIC Ipeap_methods* ipeap_peap_suppl_methods_get(void); #endif #ifdef IPEAP_USE_EAP_SIM IP_PUBLIC Ipeap_methods* ipeap_sim_methods_get(void); #endif #ifdef IPEAP_USE_EAP_AKA IP_PUBLIC Ipeap_methods* ipeap_aka_methods_get(void); #endif #ifdef IPEAP_USE_EAP_MSCHAPV2 IP_PUBLIC Ipeap_methods* ipeap_mschapv2_suppl_methods_get(void); #endif #ifdef IPEAP_USE_EAP_WSC IP_PUBLIC Ipeap_methods* ipeap_wsc_methods_get(void); #endif IP_PUBLIC Ip_err ipeap_ctx_set_identity(struct Ipeap_ctx_st *ctx, const char* identity); IP_PUBLIC Ip_err ipeap_ctx_set_identity_from_sysvar(struct Ipeap_ctx_st *ctx); IP_PUBLIC Ip_err ipeap_mech_type_set_enabled(struct Ipeap_ctx_st* ctc, int mech_id, Ip_bool enabled); IP_PUBLIC Ip_err ipeap_exp_mech_type_set_enabled(struct Ipeap_ctx_st* ctc, Ipeap_vendor_id vendor_id, Ipeap_vendor_type vendor_type, Ip_bool enabled); IP_PUBLIC void ipeap_ctx_set_mech_enabled_from_sysvar(struct Ipeap_ctx_st *ctx); IP_PUBLIC Ip_err ipeap_display_status(struct Ipeap_ctx_st* ctx, char *str); #ifdef __cplusplus } #endif /******************************************************************************* * * ipeap_ctx_new - Create a new EAP context * * This routine creates a new EAP context using the supported EAP types. * * PARAMETERS: * \is * \i * IPEAP_MODE_SUPPLICANT is the only supported mode. * \ie * * RETURNS: * A pointer to the EAP context upon success, or IP_NULL upon failure. * */ IP_PUBLIC struct Ipeap_ctx_st* ipeap_ctx_new ( int mode ); /******************************************************************************* * * ipeap_ctx_free - Free an existing EAP context * * This routine frees a valid EAP context. * * PARAMETERS: * \is * \i * A valid pointer to the EAP context to be freed. * \ie * * RETURNS: * None * */ IP_PUBLIC void ipeap_ctx_free ( struct Ipeap_ctx_st* ctx ); /******************************************************************************* * * ipeap_mech_type_set_enabled - Enable/Disable an EAP mechanism * * This routine Enables/Disables a supported EAP mechanism for the specified EAP context. * This setting overrides the default EAP mechanism setting that was initialized * at context creation time. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A supported EAP mechanism, which can be one of the following: * IPEAP_TYPE_MD5_CHALLENGE: Requires IPEAP_USE_EAP_MD5 to be defined. * IPEAP_TYPE_GTC: Requires IPEAP_USE_EAP_GTC to be defined. * IPEAP_TYPE_TLS: Requires IPEAP_USE_EAP_TLS to be defined. * IPEAP_TYPE_LEAP: Requires IPEAP_USE_EAP_LEAP to be defined. * IPEAP_TYPE_SIM: Requires IPEAP_USE_EAP_SIM to be defined. * IPEAP_TYPE_TTLS: Requires IPEAP_USE_EAP_TTLS to be defined. * IPEAP_TYPE_AKA: Requires IPEAP_USE_EAP_AKA to be defined. * IPEAP_TYPE_PEAP: Requires IPEAP_USE_EAP_PEAP to be defined. * IPEAP_TYPE_MSCHAPV2: Requires IPEAP_USE_EAP_MSCHAPV2 to be defined. * * \i * 0: Disable * 1: Enable * \ie * * RETURNS: * IPCOM_SUCCESS upon success, or IPCOM_ERR_FAILED if the specified EAP mechanism is not supported. * */ IP_PUBLIC Ip_err ipeap_mech_type_set_enabled ( struct Ipeap_ctx_st* ctx, int mech_id, Ip_bool enabled ); /******************************************************************************* * * ipeap_exp_mech_type_set_enabled - Enable/Disable an Expanded EAP mechanism * * This routine Enables/Disables a supported Expanded EAP mechanism for the * specified EAP context using the supported Expanded EAP vendor-id and vendor-type. * This setting overrides the default EAP mechanism setting that was initialized * at context creation time. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A supported Expanded EAP mechanism, which can be one of the following: * for EAP WSC: vendor id = 0x00372A (WFA SMI) * * \i * A supported vendor type for the specified vendor_id: * for EAP WSC: vendor-type = 0x00000001 (Cimple-Config) * * \i * 0: Disable * 1: Enable * \ie * * RETURNS: * IPCOM_SUCCESS upon success, or IPCOM_ERR_FAILED if the specified EAP mechanism is not supported. * */ IP_PUBLIC Ip_err ipeap_exp_mech_type_set_enabled ( struct Ipeap_ctx_st* ctx, Ipeap_vendor_id vendor_id, Ipeap_vendor_type vendor_type, Ip_bool enabled ); /******************************************************************************* * * ipeap_ctx_set_identity - Sets the EAP Identity * * This routine sets the EAP identity used in the EAP Identity Request messages. * This setting overrides the default identity value initialized at context creation. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A valid pointer to a NULL terminated identity string. * * \ie * * RETURNS: * IPCOM_SUCCESS upon success, or IPCOM_ERR_INVALID_ARG if the is invalid. * */ IP_PUBLIC Ip_err ipeap_ctx_set_identity ( struct Ipeap_ctx_st *ctx, const char* identity ); /******************************************************************************* * * ipeap_ctx_set_method - Set the EAP Method for the specified context * * This routine is used to set the EAP method for the specified context so that the context * is bound to this method. This means no other method can be nogotiated for this context * unless the context is deleted and recreated. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A supported EAP mechanism, which can be one of the following: * IPEAP_TYPE_MD5_CHALLENGE: Requires IPEAP_USE_EAP_MD5 to be defined. * IPEAP_TYPE_GTC: Requires IPEAP_USE_EAP_GTC to be defined. * IPEAP_TYPE_TLS: Requires IPEAP_USE_EAP_TLS to be defined. * IPEAP_TYPE_LEAP: Requires IPEAP_USE_EAP_LEAP to be defined. * IPEAP_TYPE_SIM: Requires IPEAP_USE_EAP_SIM to be defined. * IPEAP_TYPE_TTLS: Requires IPEAP_USE_EAP_TTLS to be defined. * IPEAP_TYPE_AKA: Requires IPEAP_USE_EAP_AKA to be defined. * IPEAP_TYPE_PEAP: Requires IPEAP_USE_EAP_PEAP to be defined. * IPEAP_TYPE_MSCHAPV2: Requires IPEAP_USE_EAP_MSCHAPV2 to be defined. * IPEAP_TYPE_EXPANDED: For Expanded EAP Types. * * \i * Used ONLY if == IPEAP_TYPE_EXPANDED. * Specifies a supported Expanded EAP mechanism, which can be one of the following: * for EAP WSC: vendor id = 0x00372A (WFA SMI) - Requires INCLUDE_IPEAP_USE_EAP_WSC to be defined. * * \i * Used ONLY if == IPEAP_TYPE_EXPANDED. * A supported vendor type for the specified vendor_id: * for EAP WSC: vendor-type = 0x00000001 (Cimple-Config) - Requires INCLUDE_IPEAP_USE_EAP_WSC to be defined. * * \ie * * RETURNS: * IPCOM_SUCCESS upon success, or IPCOM_ERR_FAILED if the specified EAP mechanism is not supported. * */ IP_PUBLIC Ip_err ipeap_ctx_set_method ( struct Ipeap_ctx_st *ctx, Ip_u8 mech_id, Ipeap_vendor_id vendor_id, Ipeap_vendor_type vendor_type ); /******************************************************************************* * * ipeap_process_pkt - Process an EAP packet * * This routine processes a received EAP packet. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A valid pointer to a received EAP packet. * * \i * A valid pointer to an allocated EAP packet to be used for possible responses to the peer. * (See RETURNS for more details on handling ). * * \ie * * RETURNS: * This routine may return any of the following codes, each requiring a different way to handle . * \is * \i IPEAP_PENDING_SEND_OUT_PKT: * was successfully processed and now contains an EAP packet to be sent * to the peer by the caller (after prepending any protocol headers if applicable, e.g. EAPOL header). * * \i IPEAP_PENDING_USER_INPUT: * was successfully processed and contains a prompt message from the peer which * should be handled by the caller. * ipeap_handle_user_input() is usually called afterwards to complete the EAP exchange. * * \i IPEAP_DROPPED_PKT: * contained an invalid or unexpected EAP packet and is to be dropped. is to * be ignored and freed. * * \i IPEAP_SUCCESS * contained an EAP SUCCESS indication and the EAP exchange is now complete. * is to be ignored and freed. * * \i IPEAP_FAILURE * An EAP exchange failure or an EAP failure indication from the peer. * is to be ignored and freed. * * \i IPCOM_ERR_INVALID_ARG * An invalid argument was passed. is to be ignored and freed. * * \i IPCOM_ERR_NO_MEMORY * An out of memory condition occured. is to be ignored and freed. * * \i IPCOM_ERR_FAILED * An unexpected failure. is to be ignored and freed. * \ie * It is the caller's responsibility to free and after this routine returns. * */ IP_PUBLIC Ip_err ipeap_process_pkt ( struct Ipeap_ctx_st* ctx, Ipeap_pkt* in_pkt, Ipeap_pkt* out_pkt ); /******************************************************************************* * * ipeap_handle_user_input - Handle user input in response to peer prompt * * This routine is called to handle the input provided by the EAP user in response * to a prompt by the authentication server. This only applies to certain EAP mechanisms * that require prompting the user for a response during the EAP exchange (e.g. EAP-GTC). * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A valid pointer to a user input structure containing the user response. * * \i * A valid pointer to an allocated EAP packet to be used for possible responses * to the peer (See RETURNS for more details on handling ). * * \ie * * RETURNS: * This routine may return any of the following codes, each requiring a different way to handle . * \is * \i IPEAP_PENDING_SEND_OUT_PKT: * was successfully processed and now contains an EAP packet to be sent * to the peer by the caller (after prepending any protocol headers if applicable, e.g. EAPOL header). * * \i IPEAP_DROPPED_PKT: * The EAP exchange could not proceed. is to be ignored and freed. * * \i IPCOM_ERR_INVALID_ARG * An invalid argument was passed. is to be ignored and freed. * * \i IPCOM_ERR_NOT_SUPPORTED * This routine (and user input handling) is not supported by the negotiated EAP mechanism. * is to be ignored and freed. * * \i IPCOM_ERR_NO_MEMORY * An out of memory condition occured. is to be ignored and freed. * * \i IPCOM_ERR_FAILED * An unexpected failure. is to be ignored and freed. * \ie * It is the caller's responsibility to free and after this routine returns. * */ IP_PUBLIC Ip_err ipeap_handle_user_input ( struct Ipeap_ctx_st* ctx, Ipeap_user_input* ui, Ipeap_pkt* out_pkt ); /******************************************************************************* * * ipeap_get_key - Generate Keying material * * This routine retrieves the generated keying material for EAP mechanisms that support it. * This routine should only be called after the EAP exchange is successfully completed. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A valid pointer to an buffer allocated by the caller which will be * populated with the keying material upon this routine returning successfully. * * \i * The length of the allocated buffer. MUST BE LARGE ENOUGH TO CONTAIN THE KEYING MATERIAL. * * \ie * * RETURNS: * \is * \i IPCOM_SUCCESS * Successfully populated the keying material in buffer. * * \i IPCOM_ERR_NOT_SUPPORTED * This negotiated EAP mechanism does not support generating keying material. * * \i IPCOM_ERR_INVALID_ARG * An invalid argument was passed. * * \i IPCOM_ERR_FAILED * An failure occurred due to an invalid or uninitialized context. * \ie * */ IP_PUBLIC Ip_err ipeap_get_key ( struct Ipeap_ctx_st* ctx, Ip_u8 *key, int key_len ); /******************************************************************************* * * ipeap_get_eap_session_id - Generate Eap-Session-Id * * This routine retrieves the generated Eap-Session-Id for EAP mechanisms that support it. * This routine should only be called after the EAP exchange is successfully completed. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A valid pointer to a buffer allocated by the caller which will be * populated with the Eap-Session-Id material upon this routine returning successfully. * * \i * pointer to the length of buffer. MUST BE LARGE ENOUGH TO CONTAIN THE SESSION-ID. * will be set to actual length of Eap-Session-Id upon successful return of * this routine. * * \ie * * RETURNS: * \is * \i IPCOM_SUCCESS * Successfully populated the Session-ID in buffer. * will be set to actual length of Eap-Session-Id. * * \i IPCOM_ERR_NOT_SUPPORTED * This negotiated EAP mechanism does not support generating Eap-Session-Id. * * \i IPCOM_ERR_INVALID_ARG * An invalid argument was passed. * * \i IPCOM_ERR_FAILED * An failure occurred due to an invalid or uninitialized context. * \ie * */ IP_PUBLIC Ip_err ipeap_get_eap_session_id ( struct Ipeap_ctx_st* ctx, Ip_u8 *session_id, Ip_u32 *session_id_len ); /******************************************************************************* * * ipeap_display_status - Display EAP status * * This routine displays information about the current EAP context. * * PARAMETERS: * \is * \i * A valid pointer to an EAP context. * * \i * A valid pointer to a string to be prepended to the EAP output display, * or IP_NULL for no pre-pend . * \ie * * RETURNS: * \is * \i IPCOM_SUCCESS * Successfully displayed the context information. * * \i IPCOM_ERR_INVALID_ARG * An invalid argument was passed. * * \i IPCOM_ERR_FAILED * An failure occurred due to an invalid or uninitialized context. * \ie * */ IP_PUBLIC Ip_err ipeap_display_status ( struct Ipeap_ctx_st* ctx, char *str ); #endif /* **************************************************************************** * END OF FILE **************************************************************************** */