ws_eapol_pdu.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef WS_EAPOL_PDU_H_
00019 #define WS_EAPOL_PDU_H_
00020 
00021 /*
00022  * EAPOL PDU module transfers EAPOL PDUs to/from MPX. Several users
00023  * (e.g. supplicant PAE and EAPOL relay) can register to incoming
00024  * EAPOL PDUs. When registering, users need to define priority that
00025  * defines in which order incoming EAPOL PDUs are offered to them.
00026  *
00027  * Incoming EAPOL PDU user callbacks form a pair on EAPOL PDU module:
00028  * address check callback is called first, and if it returns match
00029  * then incoming EAPOL PDU callback is called.
00030  *
00031  */
00032 
00033 /**
00034  *  ws_eapol_pdu_init initialize EAPOL PDU module
00035  *
00036  * \param interface_ptr interface
00037  *
00038  * \return < 0 failure
00039  * \return >= 0 success
00040  *
00041  */
00042 int8_t ws_eapol_pdu_init(protocol_interface_info_entry_t *interface_ptr);
00043 
00044 /**
00045  *  ws_eapol_pdu_mpx_register register EAPOL PDU module to MPX
00046  *
00047  * \param interface_ptr interface
00048  * \param mpx_api MPX API
00049  * \param mpx_user_id MPX user id
00050  *
00051  * \return < 0 failure
00052  * \return >= 0 success
00053  *
00054  */
00055 int8_t ws_eapol_pdu_mpx_register(protocol_interface_info_entry_t *interface_ptr, struct mpx_api_s *mpx_api, uint16_t mpx_user_id);
00056 
00057 /**
00058  *  ws_eapol_pdu_delete delete EAPOL PDU module
00059  *
00060  * \param interface_ptr interface
00061  *
00062  * \return < 0 failure
00063  * \return >= 0 success
00064  *
00065  */
00066 int8_t ws_eapol_pdu_delete(protocol_interface_info_entry_t *interface_ptr);
00067 
00068 /**
00069  *  ws_eapol_pdu_address_check check incoming EAPOL PDU address
00070  *
00071  * \param interface_ptr interface
00072  * \param eui_64 source EUI-64
00073  *
00074  * \return < 0 address does not match
00075  * \return >= 0 address matches, call the PDU receive callback
00076  *
00077  */
00078 typedef int8_t ws_eapol_pdu_address_check(protocol_interface_info_entry_t *interface_ptr, const uint8_t *eui_64);
00079 
00080 /**
00081  *  ws_eapol_pdu_receive receive EAPOL PDU
00082  *
00083  * \param interface_ptr interface
00084  * \param eui_64 source EUI-64
00085  * \param data EAPOL PDU
00086  * \param size PDU size
00087  *
00088  * \return < 0 failure
00089  * \return >= 0 success
00090  *
00091  */
00092 typedef int8_t ws_eapol_pdu_receive(protocol_interface_info_entry_t *interface_ptr, const uint8_t *eui_64, void *data, uint16_t size);
00093 
00094 typedef enum {
00095     EAPOL_PDU_RECV_HIGH_PRIORITY = 0,
00096     EAPOL_PDU_RECV_MEDIUM_PRIORITY = 100,
00097     EAPOL_PDU_RECV_LOW_PRIORITY = 200
00098 } eapol_pdu_recv_prior_t;
00099 
00100 typedef struct {
00101     eapol_pdu_recv_prior_t priority;           /**< Priority: high, medium or low */
00102     ws_eapol_pdu_address_check *addr_check;    /**< Address check callback */
00103     ws_eapol_pdu_receive *receive;             /**< PDU receive callback */
00104 } eapol_pdu_recv_cb_data_t;
00105 
00106 /**
00107  *  ws_eapol_pdu_cb_register register an incoming EAPOL PDU callback
00108  *
00109  * \param interface_ptr interface
00110  * \param cb_data callback data
00111  *
00112  * \return < 0 failure
00113  * \return >= 0 success
00114  *
00115  */
00116 int8_t ws_eapol_pdu_cb_register(protocol_interface_info_entry_t *interface_ptr, const eapol_pdu_recv_cb_data_t *cb_data);
00117 
00118 /**
00119  *  ws_eapol_pdu_cb_unregister unregister an incoming EAPOL PDU callback
00120  *
00121  * \param interface_ptr interface
00122  * \param cb_data callback data
00123  *
00124  * \return < 0 failure
00125  * \return >= 0 success
00126  *
00127  */
00128 int8_t ws_eapol_pdu_cb_unregister(protocol_interface_info_entry_t *interface_ptr, const eapol_pdu_recv_cb_data_t *cb_data);
00129 
00130 typedef enum {
00131     EAPOL_PDU_TX_OK = 0,                 // Successful
00132     EAPOL_PDU_TX_ERR_TX_NO_ACK  = -1,    // No acknowledge was received
00133     EAPOL_PDU_TX_ERR_UNSPEC = -2,        // Other reason
00134 } eapol_pdu_tx_status_e;
00135 
00136 /**
00137  * ws_eapol_pdu_tx_status will be called when TX status is known
00138  *
00139  * \param interface_ptr interface
00140  * \param tx_status tx status
00141  * \param tx_identifier tx identifier
00142  *
00143  */
00144 typedef int8_t ws_eapol_pdu_tx_status(protocol_interface_info_entry_t *interface_ptr, eapol_pdu_tx_status_e tx_status, uint8_t tx_identifier);
00145 
00146 /**
00147  *  ws_eapol_pdu_send_to_mpx send EAPOL PDU to MPX
00148  *
00149  * \param interface_ptr interface
00150  * \param eui_64 destination EUI-64
00151  * \param data EAPOL PDU
00152  * \param size PDU size
00153  * \param buffer pointer to allocated buffer
00154  * \param tx_status tx status callback
00155  * \param tx_identifier tx identifier
00156  *
00157  * \return < 0 failure
00158  * \return >= 0 success
00159  *
00160  */
00161 int8_t ws_eapol_pdu_send_to_mpx(protocol_interface_info_entry_t *interface_ptr, const uint8_t *eui_64, void *data, uint16_t size, void *buffer, ws_eapol_pdu_tx_status tx_status, uint8_t tx_identifier);
00162 
00163 #endif /* WS_EAPOL_PDU_H_ */