ws_pae_lib.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_LIB_H_
00019 #define WS_PAE_LIB_H_
00020 
00021 /*
00022  * Port access entity library functions.
00023  *
00024  */
00025 
00026 typedef struct {
00027     kmp_api_t *kmp;                    /**< KMP API */
00028     bool timer_running;                /**< Timer running inside KMP */
00029     ns_list_link_t link;               /**< Link */
00030 } kmp_entry_t;
00031 
00032 typedef NS_LIST_HEAD (kmp_entry_t, link) kmp_list_t;
00033 
00034 typedef struct {
00035     kmp_list_t kmp_list;               /**< Ongoing KMP negotiations */
00036     kmp_addr_t addr;                   /**< EUI-64 (Relay IP address, Relay port) */
00037     sec_prot_keys_t sec_keys;          /**< Security keys */
00038     uint32_t ticks;                    /**< Ticks */
00039     uint16_t retry_ticks;              /**< Retry ticks */
00040     bool active : 1;                   /**< Is active */
00041     bool access_revoked : 1;           /**< Nodes access is revoked */
00042     ns_list_link_t link;               /**< Link */
00043 } supp_entry_t;
00044 
00045 typedef NS_LIST_HEAD (supp_entry_t, link) supp_list_t;
00046 
00047 /**
00048  * ws_pae_lib_kmp_list_init initializes KMP list
00049  *
00050  * \param kmp_list KMP list
00051  *
00052  * \return < 0 failure
00053  * \return >= 0 success
00054  *
00055  */
00056 void ws_pae_lib_kmp_list_init(kmp_list_t *kmp_list);
00057 
00058 /**
00059  * ws_pae_lib_kmp_list_add adds KMP to KMP list
00060  *
00061  * \param kmp_list KMP list
00062  * \param kmp KMP
00063  *
00064  * \return KMP list entry on success
00065  * \return NULL on failure
00066  *
00067  */
00068 kmp_entry_t *ws_pae_lib_kmp_list_add(kmp_list_t *kmp_list, kmp_api_t *kmp);
00069 
00070 /**
00071  * ws_pae_lib_kmp_list_delete deletes KMP from KMP list
00072  *
00073  * \param kmp_list KMP list
00074  * \param kmp KMP
00075  *
00076  * \return < 0 failure
00077  * \return >= 0 success
00078  *
00079  */
00080 int8_t ws_pae_lib_kmp_list_delete(kmp_list_t *kmp_list, kmp_api_t *kmp);
00081 
00082 /**
00083  * ws_pae_lib_kmp_list_free frees KMP list
00084  *
00085  * \param kmp_list KMP list
00086  *
00087  */
00088 void ws_pae_lib_kmp_list_free(kmp_list_t *kmp_list);
00089 
00090 /**
00091  * ws_pae_lib_kmp_list_type_get gets KMP from KMP list based on KMP type
00092  *
00093  * \param kmp_list KMP list
00094  * \param type type
00095  *
00096  * \return KMP on success
00097  * \return NULL on failure
00098  *
00099  */
00100 kmp_api_t *ws_pae_lib_kmp_list_type_get(kmp_list_t *kmp_list, kmp_type_e type);
00101 
00102 /**
00103  * ws_pae_lib_kmp_list_instance_id_get gets KMP from KMP list based on instance identifier
00104  *
00105  * \param kmp_list KMP list
00106  * \param instance_id instance identifier
00107  *
00108  * \return KMP on success
00109  * \return NULL on failure
00110  *
00111  */
00112 kmp_api_t *ws_pae_lib_kmp_list_instance_id_get(kmp_list_t *kmp_list, uint8_t instance_id);
00113 
00114 /**
00115  * ws_pae_lib_kmp_list_entry_get gets KMP entry from KMP list based on KMP
00116  *
00117  * \param kmp_list KMP list
00118  * \param kmp KMP
00119  *
00120  * \return KMP list entry on success
00121  * \return NULL on failure
00122  *
00123  */
00124 kmp_entry_t *ws_pae_lib_kmp_list_entry_get(kmp_list_t *kmp_list, kmp_api_t *kmp);
00125 
00126 /**
00127  * ws_pae_lib_kmp_timer_start starts KMP timer
00128  *
00129  * \param kmp_list KMP list
00130  * \param entry KMP list entry
00131  *
00132  */
00133 void ws_pae_lib_kmp_timer_start(kmp_list_t *kmp_list, kmp_entry_t *entry);
00134 
00135 /**
00136  * ws_pae_lib_kmp_timer_stop stops KMP timer
00137  *
00138  * \param kmp_list KMP list
00139  * \param entry KMP list entry
00140  *
00141  */
00142 void ws_pae_lib_kmp_timer_stop(kmp_list_t *kmp_list, kmp_entry_t *entry);
00143 
00144 /**
00145  * ws_pae_lib_kmp_timer_timeout KMP timer timeout callback
00146  *
00147  * \param kmp KMP
00148  * \param ticks timer ticks
00149  *
00150  */
00151 typedef void ws_pae_lib_kmp_timer_timeout(kmp_api_t *kmp, uint16_t ticks);
00152 
00153 /**
00154  *  ws_pae_lib_kmp_timer_update updates KMP timers on KMP list
00155  *
00156  * \param kmp_list KMP list
00157  * \param ticks timer ticks
00158  * \param timeout callback to call on timeout
00159  *
00160  * \return true KMP list has KMPs
00161  * \return false no KMPs on KMP list
00162  *
00163  */
00164 bool ws_pae_lib_kmp_timer_update(kmp_list_t *kmp_list, uint16_t ticks, ws_pae_lib_kmp_timer_timeout timeout);
00165 
00166 /**
00167  *  ws_pae_lib_supp_list_init initiates supplicant list
00168  *
00169  * \param supp_list supplicant list
00170  *
00171  */
00172 void ws_pae_lib_supp_list_init(supp_list_t *supp_list);
00173 
00174 /**
00175  *  ws_pae_lib_supp_list_add adds entry to supplicant list
00176  *
00177  * \param supp_list supplicant list
00178  * \param addr address
00179  *
00180  * \return supplicant list entry on success
00181  * \return NULL on failure
00182  */
00183 supp_entry_t *ws_pae_lib_supp_list_add(supp_list_t *supp_list, const kmp_addr_t *addr);
00184 
00185 /**
00186  *  ws_pae_lib_supp_list_add removes entry from supplicant list
00187  *
00188  * \param supp_list supplicant list
00189  * \param entry entry
00190  *
00191  * \return < 0 failure
00192  * \return >= 0 success
00193  */
00194 int8_t ws_pae_lib_supp_list_remove(supp_list_t *supp_list, supp_entry_t *entry);
00195 
00196 /**
00197  *  ws_pae_lib_supp_list_entry_eui_64_get gets entry from supplicant list based on EUI-64
00198  *
00199  * \param supp_list supplicant list
00200  * \param eui_64 EUI-64
00201  *
00202  * \return supplicant list entry on success
00203  * \return NULL on failure
00204  */
00205 supp_entry_t *ws_pae_lib_supp_list_entry_eui_64_get(const supp_list_t *supp_list, const uint8_t *eui_64);
00206 
00207 /**
00208  *  ws_pae_lib_supp_list_delete deletes supplicant list
00209  *
00210  * \param supp_list supplicant list
00211  *
00212  */
00213 void ws_pae_lib_supp_list_delete(supp_list_t *supp_list);
00214 
00215 /**
00216  *  ws_pae_lib_supp_list_timer_update updates timers on supplicant list
00217  *
00218  * \param active_supp_list list of active supplicants
00219  * \param inactive_supp_list list of inactive supplicants
00220  * \param ticks timer ticks
00221  * \param timeout callback to call on timeout
00222  *
00223  * \return true timer needs still to be running
00224  * \return false timer can be stopped
00225  */
00226 bool ws_pae_lib_supp_list_timer_update(supp_list_t *active_supp_list, supp_list_t *inactive_supp_list, uint16_t ticks, ws_pae_lib_kmp_timer_timeout timeout);
00227 
00228 /**
00229  *  ws_pae_lib_supp_list_slow_timer_update updates slow timer on supplicant list
00230  *
00231  * \param supp_list list of supplicants
00232  * \param timer_settings timer settings
00233  * \param seconds seconds
00234  *
00235  */
00236 void ws_pae_lib_supp_list_slow_timer_update(supp_list_t *supp_list, timer_settings_t *timer_settings, uint16_t seconds);
00237 
00238 /**
00239  *  ws_pae_lib_supp_list_timer_update updates supplicant timers
00240  *
00241  * \param entry supplicant entry
00242  * \param ticks timer ticks
00243  * \param timeout callback to call on timeout
00244  *
00245  * \return true timer needs still to be running
00246  * \return false timer can be stopped
00247  */
00248 bool ws_pae_lib_supp_timer_update(supp_entry_t *entry, uint16_t ticks, ws_pae_lib_kmp_timer_timeout timeout);
00249 
00250 /**
00251  *  ws_pae_lib_supp_init initiates supplicant entry
00252  *
00253  * \param entry supplicant entry
00254  *
00255  */
00256 void ws_pae_lib_supp_init(supp_entry_t *entry);
00257 
00258 /**
00259  *  ws_pae_lib_supp_delete deletes supplicant entry
00260  *
00261  * \param entry supplicant entry
00262  *
00263  */
00264 void ws_pae_lib_supp_delete(supp_entry_t *entry);
00265 
00266 /**
00267  *  ws_pae_lib_supp_timer_ticks_set sets supplicant timer ticks
00268  *
00269  * \param entry supplicant entry
00270  * \param ticks ticks
00271  *
00272  */
00273 void ws_pae_lib_supp_timer_ticks_set(supp_entry_t *entry, uint32_t ticks);
00274 
00275 /**
00276  *  ws_pae_lib_supp_list_to_active move supplicant to active supplicants list
00277  *
00278  * \param active_supp_list list of active supplicants
00279  * \param inactive_supp_list list of inactive supplicants
00280  * \param entry supplicant entry
00281  *
00282  */
00283 void ws_pae_lib_supp_list_to_active(supp_list_t *active_supp_list, supp_list_t *inactive_supp_list, supp_entry_t *entry);
00284 
00285 /**
00286  *  ws_pae_lib_supp_list_to_inactive move supplicant to inactive supplicants list
00287  *
00288  * \param active_supp_list list of active supplicants
00289  * \param inactive_supp_list list of inactive supplicants
00290  * \param entry supplicant entry
00291  *
00292  */
00293 void ws_pae_lib_supp_list_to_inactive(supp_list_t *active_supp_list, supp_list_t *inactive_supp_list, supp_entry_t *entry);
00294 
00295 /**
00296  *  ws_pae_lib_supp_list_purge purge inactive supplicants list
00297  *
00298  * \param active_supp_list list of active supplicants
00299  * \param inactive_supp_list list of inactive supplicants
00300  * \param max_number maximum number of supplicant entries, can be set to 0 in combination with max_purge
00301  *                   to free list entries even when maximum number supplicant entries has not been reached
00302  * \param max_purge maximum number of supplicants to purge in one call, 0 means not limited
00303  *
00304  */
00305 void ws_pae_lib_supp_list_purge(supp_list_t *active_supp_list, supp_list_t *inactive_supp_list, uint16_t max_number, uint8_t max_purge);
00306 
00307 /**
00308  *  ws_pae_lib_supp_list_kmp_count counts the number of KMPs of a certain type in a list of supplicants
00309  *
00310  * \param supp_list list of supplicants
00311  * \param type KMP type
00312  *
00313  * \return number of KMPs in the supplicant list
00314  *
00315  */
00316 uint16_t ws_pae_lib_supp_list_kmp_count(supp_list_t *supp_list, kmp_type_e type);
00317 
00318 /**
00319  *  ws_pae_lib_supp_list_entry_retry_timer_get checks if some supplicant has retry timer running
00320  *
00321  * \param supp_list list of supplicants
00322  *
00323  * \return supplicant with retry timer running or NULL if no supplicants with timer running
00324  *
00325  */
00326 supp_entry_t *ws_pae_lib_supp_list_entry_retry_timer_get(supp_list_t *supp_list);
00327 
00328 #endif /* WS_PAE_AUTH_H_ */