ws_pae_supp.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_PAE_SUPP_H_
00019 #define WS_PAE_SUPP_H_
00020 
00021 #define PAE_SUPP_NOT_ENABLED 5
00022 
00023 #ifdef HAVE_PAE_SUPP
00024 
00025 /*
00026  * Supplicant port access entity controls key security protocols using KMP API.
00027  *
00028  * Configures KMP service network access and provides timing and callback services
00029  * for it. Registers needed security protocols to KMP service.
00030  *
00031  * PAE maintains security keys that are internal to port access entity. After
00032  * (re-)authentication provides network access keys to application.
00033  *
00034  */
00035 
00036 /**
00037  * ws_pae_supp_init initializes PAE supplicant
00038  *
00039  * \param interface_ptr interface
00040  * \param cert_chain certificate chain
00041  * \param timer_settings timer settings
00042  *
00043  * \return < 0 failure
00044  * \return >= 0 success
00045  *
00046  */
00047 int8_t ws_pae_supp_init(protocol_interface_info_entry_t *interface_ptr, const sec_prot_certs_t *certs, timer_settings_t *timer_settings);
00048 
00049 /**
00050  * ws_pae_supp_delete deletes PAE supplicant
00051  *
00052  * \param interface_ptr interface
00053  *
00054  * \return < 0 failure
00055  * \return >= 0 success
00056  *
00057  */
00058 int8_t ws_pae_supp_delete(protocol_interface_info_entry_t *interface_ptr);
00059 
00060 
00061 /**
00062  * ws_pae_supp_timing_adjust Adjust retries and timings of the 4WH protocol
00063  *
00064  * Timing value is a generic number between 0 to 32 that goes from fast and
00065  * reactive network to low bandwidth and long latency.
00066  *
00067  * example value definitions:
00068  * 0-8 very fast network
00069  * 9-16 medium network
00070  * 16-24 slow network
00071  * 25-32 extremely slow network
00072  *
00073  * There is no need to have lots variations in every layer if protocol is not very active in any case.
00074  *
00075  * \param timing Timing value.
00076  *
00077  * \return < 0 failure
00078  * \return >= 0 success
00079  *
00080  */
00081 int8_t ws_pae_supp_timing_adjust(uint8_t timing);
00082 
00083 /**
00084  * ws_pae_supp_fast_timer PAE supplicant fast timer call
00085  *
00086  * \param ticks elapsed ticks
00087  *
00088  */
00089 void ws_pae_supp_fast_timer(uint16_t ticks);
00090 
00091 /**
00092  * ws_pae_supp_slow_timer PAE supplicant slow timer call
00093  *
00094  * \param ticks elapsed seconds
00095  *
00096  */
00097 void ws_pae_supp_slow_timer(uint16_t seconds);
00098 
00099 /**
00100  * ws_pae_supp_authenticate start EAPOL authentication
00101  *
00102  * \param interface_ptr interface
00103  * \param dest_pan_id EAPOL target PAN ID
00104  * \param dest_eui_64 EAPOL target
00105  *
00106  * \return < 0 failure
00107  * \return 0 authentication done, continue
00108  * \return > 0 authentication started
00109  *
00110  */
00111 int8_t ws_pae_supp_authenticate(protocol_interface_info_entry_t *interface_ptr, uint16_t dest_pan_id, uint8_t *dest_eui_64);
00112 
00113 /**
00114  * ws_pae_supp_nw_info_set set network information
00115  *
00116  * \param interface_ptr interface
00117  * \param pan_id PAD ID
00118  * \param network_name network name
00119  *
00120  * \return < 0 failure
00121  * \return >= 0 success
00122  *
00123  */
00124 int8_t ws_pae_supp_nw_info_set(protocol_interface_info_entry_t *interface_ptr, uint16_t pan_id, char *network_name);
00125 
00126 /**
00127  * ws_pae_supp_border_router_addr_write write border router address
00128  *
00129  * \param interface_ptr interface
00130  * \param eui_64 pointer to EUI-64
00131  *
00132  * \return < 0 failure
00133  * \return >= 0 success
00134  *
00135  */
00136 int8_t ws_pae_supp_border_router_addr_write(protocol_interface_info_entry_t *interface_ptr, const uint8_t *eui_64);
00137 
00138 /**
00139  * ws_pae_supp_border_router_addr_read read border router address
00140  *
00141  * \param interface_ptr interface
00142  * \param eui_64 pointer to EUI-64
00143  *
00144  * \return < 0 failure
00145  * \return >= 0 success
00146  *
00147  */
00148 int8_t ws_pae_supp_border_router_addr_read(protocol_interface_info_entry_t *interface_ptr, uint8_t *eui_64);
00149 
00150 /**
00151  * ws_pae_supp_nw_key_valid network key is valid i.e. used successfully on bootstrap
00152  *
00153  * \param interface_ptr interface
00154  *
00155  * \return < 0 failure
00156  * \return >= 0 success
00157  *
00158  */
00159 int8_t ws_pae_supp_nw_key_valid(protocol_interface_info_entry_t *interface_ptr);
00160 
00161 /**
00162  * ws_pae_supp_gtk_hash_update GTK hash has been updated (on PAN configuration)
00163  *
00164  * \param interface_ptr interface
00165  * \param gtkhash GTK hash, 32 bytes
00166  *
00167  * \return < 0 failure
00168  * \return >= 0 success
00169  *
00170  */
00171 int8_t ws_pae_supp_gtk_hash_update(protocol_interface_info_entry_t *interface_ptr, uint8_t *gtkhash);
00172 
00173 /**
00174  * ws_pae_supp_nw_key_index_update key index been updated (on PAN configuration)
00175  *
00176  * \param interface_ptr interface
00177  * \param index key index
00178  *
00179  * \return < 0 failure
00180  * \return >= 0 success
00181  *
00182  */
00183 int8_t ws_pae_supp_nw_key_index_update(protocol_interface_info_entry_t *interface_ptr, uint8_t index);
00184 
00185 /**
00186  *  ws_pae_supp_gtks_set set supplicant GTKs
00187  *
00188  * \param interface_ptr interface
00189  * \param gtks GTKs
00190  *
00191  * \return < 0 failure
00192  * \return >= 0 success
00193  *
00194  */
00195 int8_t ws_pae_supp_gtks_set(protocol_interface_info_entry_t *interface_ptr, sec_prot_gtk_keys_t *gtks);
00196 
00197 /**
00198  * ws_pae_supp_eapol_target_remove remove EAPOL target set using authentication start
00199  *
00200  * \param interface_ptr interface
00201  *
00202  * \return < 0 failure
00203  * \return >= 0 success
00204  *
00205  */
00206 int8_t ws_pae_supp_eapol_target_remove(protocol_interface_info_entry_t *interface_ptr);
00207 
00208 /**
00209  * ws_pae_supp_nw_key_index_set network send key index set callback
00210  *
00211  * \param interface_ptr interface
00212  * \param index network send key index
00213  *
00214  */
00215 typedef void ws_pae_supp_nw_key_index_set(protocol_interface_info_entry_t *interface_ptr, uint8_t index);
00216 
00217 /**
00218  * ws_pae_supp_auth_completed authentication completed callback
00219  *
00220  * \param interface_ptr interface
00221  * \param result result, either ok or failure reason
00222  * \param target_eui_64 EAPOL target in case of failure or NULL
00223  *
00224  */
00225 typedef void ws_pae_supp_auth_completed(protocol_interface_info_entry_t *interface_ptr, auth_result_e result, uint8_t *target_eui_64);
00226 
00227 /**
00228  * ws_pae_supp_nw_key_insert network key insert callback
00229  *
00230  * \param interface_ptr interface
00231  * \param gtks group keys
00232  *
00233  * \return < 0 failure
00234  * \return >= 0 success
00235  *
00236  */
00237 typedef int8_t ws_pae_supp_nw_key_insert(protocol_interface_info_entry_t *interface_ptr, sec_prot_gtk_keys_t *gtks);
00238 
00239 /**
00240  * ws_pae_supp_cb_register register PEA supplicant callbacks
00241  *
00242  * \param interface_ptr interface
00243  * \param completed authentication completed callback
00244  * \param nw_key_insert network key index callback
00245  * \param nw_key_index_set network send key index callback
00246  *
00247  */
00248 void ws_pae_supp_cb_register(protocol_interface_info_entry_t *interface_ptr, ws_pae_supp_auth_completed *completed, ws_pae_supp_nw_key_insert *nw_key_insert, ws_pae_supp_nw_key_index_set *nw_key_index_set);
00249 
00250 #else
00251 
00252 #define ws_pae_supp_init(interface_ptr, certs, timer_settings) 1
00253 #define ws_pae_supp_delete NULL
00254 #define ws_pae_supp_timing_adjust(timing) 1
00255 #define ws_pae_supp_cb_register(interface_ptr, completed, nw_key_insert, nw_key_index_set)
00256 #define ws_pae_supp_nw_info_set(interface_ptr, pan_id, network_name) -1
00257 #define ws_pae_supp_nw_key_valid(interface_ptr) -1
00258 #define ws_pae_supp_fast_timer NULL
00259 #define ws_pae_supp_slow_timer NULL
00260 #define ws_pae_supp_authenticate(interface_ptr, dest_pan_id, dest_eui_64) PAE_SUPP_NOT_ENABLED
00261 #define ws_pae_supp_border_router_addr_write NULL
00262 #define ws_pae_supp_border_router_addr_read NULL
00263 #define ws_pae_supp_gtk_hash_update NULL
00264 #define ws_pae_supp_nw_key_index_update NULL
00265 #define ws_pae_supp_gtks_set(interface_ptr, gtks)
00266 #define ws_pae_supp_eapol_target_remove(interface_ptr)
00267 
00268 #endif
00269 
00270 #endif /* WS_PAE_SUPP_H_ */