ws_pae_controller.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_CONTROLLER_H_
00019 #define WS_PAE_CONTROLLER_H_
00020 
00021 #ifdef HAVE_WS
00022 
00023 typedef enum {
00024     AUTH_RESULT_OK = 0,                    // Successful
00025     AUTH_RESULT_ERR_NO_MEM = -1,           // No memory
00026     AUTH_RESULT_ERR_TX_NO_ACK = -2,        // No acknowledge was received
00027     AUTH_RESULT_ERR_UNSPEC = -3            // Other reason
00028 } auth_result_e;
00029 
00030 struct nvm_tlv_entry;
00031 
00032 /**
00033  * ws_pae_controller_set_target sets EAPOL target for PAE supplicant
00034  *
00035  * \param interface_ptr interface
00036  * \param target_pan_id EAPOL target PAN ID
00037  * \param target_eui_64 EAPOL target
00038  *
00039  * \return < 0 failure
00040  * \return >= 0 success
00041  *
00042  */
00043 int8_t ws_pae_controller_set_target(protocol_interface_info_entry_t *interface_ptr, uint16_t target_pan_id, uint8_t *target_eui_64);
00044 
00045 /**
00046  * ws_pae_controller_authenticate start PAE supplicant authentication
00047  *
00048  * \param interface_ptr interface
00049  *
00050  * \return < 0 failure
00051  * \return >= 0 success
00052  *
00053  */
00054 int8_t ws_pae_controller_authenticate(protocol_interface_info_entry_t *interface_ptr);
00055 
00056 /**
00057  * ws_pae_controller_bootstrap_done indicates to PAE controller that bootstrap is ready
00058  *
00059  * \param interface_ptr interface
00060  *
00061  * \return < 0 failure
00062  * \return >= 0 success
00063  *
00064  */
00065 int8_t ws_pae_controller_bootstrap_done(protocol_interface_info_entry_t *interface_ptr);
00066 
00067 /**
00068  * ws_pae_controller_authenticator_start start PAE authenticator
00069  *
00070  * \param interface_ptr interface
00071  * \param local_port local port
00072  * \param remote_addr remote address
00073  * \param remote_port remote port
00074  *
00075  * \return < 0 failure
00076  * \return >= 0 success
00077  *
00078  */
00079 int8_t ws_pae_controller_authenticator_start(protocol_interface_info_entry_t *interface_ptr, uint16_t local_port, const uint8_t *remote_addr, uint16_t remote_port);
00080 
00081 /**
00082  * ws_pae_controller_init initializes PAE controller
00083  *
00084  * \param interface_ptr interface
00085  *
00086  * \return < 0 failure
00087  * \return >= 0 success
00088  *
00089  */
00090 int8_t ws_pae_controller_init(protocol_interface_info_entry_t *interface_ptr);
00091 
00092 /**
00093  * ws_pae_controller_init initializes PAE supplicant
00094  *
00095  * \param interface_ptr interface
00096  *
00097  * \return < 0 failure
00098  * \return >= 0 success
00099  *
00100  */
00101 int8_t ws_pae_controller_supp_init(protocol_interface_info_entry_t *interface_ptr);
00102 
00103 /**
00104  * ws_pae_controller_init initializes PAE authenticator
00105  *
00106  * \param interface_ptr interface
00107  *
00108  * \return < 0 failure
00109  * \return >= 0 success
00110  *
00111  */
00112 int8_t ws_pae_controller_auth_init(protocol_interface_info_entry_t *interface_ptr);
00113 
00114 /**
00115  * ws_pae_controller_stop stop PAE controller (e.g. on interface down)
00116  *
00117  * \param interface_ptr interface
00118  *
00119  * \return < 0 failure
00120  * \return >= 0 success
00121  *
00122  */
00123 int8_t ws_pae_controller_stop(protocol_interface_info_entry_t *interface_ptr);
00124 
00125 /**
00126  * ws_pae_controller_delete delete PAE controller (e.g. failure to create interface)
00127  *
00128  * \param interface_ptr interface
00129  *
00130  * \return < 0 failure
00131  * \return >= 0 success
00132  *
00133  */
00134 int8_t ws_pae_controller_delete(protocol_interface_info_entry_t *interface_ptr);
00135 
00136 /**
00137  * ws_pae_controller_timing_adjust Adjust retries and timings of the security protocols
00138  *
00139  * Timing value is a generic number between 0 to 32 that goes from fast and
00140  * reactive network to low bandwidth and long latency.
00141  *
00142  * example value definitions:
00143  * 0-8 very fast network
00144  * 9-16 medium network
00145  * 16-24 slow network
00146  * 25-32 extremely slow network
00147  *
00148  * There is no need to have lots variations in every layer if protocol is not very active in any case.
00149  *
00150  * \param timing Timing value.
00151  *
00152  * \return < 0 failure
00153  * \return >= 0 success
00154  *
00155  */
00156 int8_t ws_pae_controller_timing_adjust(uint8_t timing);
00157 
00158 /**
00159  * ws_pae_controller_certificate_chain_set set certificate chain
00160  *
00161  * \param chain certificate chain
00162  *
00163  * \return < 0 failure
00164  * \return >= 0 success
00165  *
00166  */
00167 int8_t ws_pae_controller_certificate_chain_set(const arm_certificate_chain_entry_s *chain);
00168 
00169 /**
00170  * ws_pae_controller_own_certificate_add add own certificate to certificate chain
00171  *
00172  * \param cert own certificate
00173  *
00174  * \return < 0 failure
00175  * \return >= 0 success
00176  *
00177  */
00178 int8_t ws_pae_controller_own_certificate_add(const arm_certificate_entry_s *cert);
00179 
00180 /**
00181  * ws_pae_controller_own_certificates_remove removes own certificates
00182  *
00183  * \return < 0 failure
00184  * \return >= 0 success
00185  *
00186  */
00187 int8_t ws_pae_controller_own_certificates_remove(void);
00188 
00189 /**
00190  * ws_pae_controller_trusted_certificate_add add trusted certificate
00191  *
00192  * \param cert trusted certificate
00193  *
00194  * \return < 0 failure
00195  * \return >= 0 success
00196  *
00197  */
00198 int8_t ws_pae_controller_trusted_certificate_add(const arm_certificate_entry_s *cert);
00199 
00200 /**
00201  * ws_pae_controller_trusted_certificate_remove remove trusted certificate
00202  *
00203  * \param cert trusted certificate
00204  *
00205  * \return < 0 failure
00206  * \return >= 0 success
00207  *
00208  */
00209 int8_t ws_pae_controller_trusted_certificate_remove(const arm_certificate_entry_s *cert);
00210 
00211 /**
00212  * ws_pae_controller_trusted_certificates_remove removes trusted certificates
00213  *
00214  * \return < 0 failure
00215  * \return >= 0 success
00216  *
00217  */
00218 int8_t ws_pae_controller_trusted_certificates_remove(void);
00219 
00220 /**
00221  * ws_pae_controller_certificate_revocation_list_add add certification revocation list
00222  *
00223  * \param crl certification revocation list
00224  *
00225  * \return < 0 failure
00226  * \return >= 0 success
00227  *
00228  */
00229 int8_t ws_pae_controller_certificate_revocation_list_add(const arm_cert_revocation_list_entry_s *crl);
00230 
00231 /**
00232  * ws_pae_controller_certificate_revocation_list_remove remove certification revocation list
00233  *
00234  * \param crl certification revocation list
00235  *
00236  * \return < 0 failure
00237  * \return >= 0 success
00238  *
00239  */
00240 int8_t ws_pae_controller_certificate_revocation_list_remove(const arm_cert_revocation_list_entry_s *crl);
00241 
00242 /**
00243  * ws_pae_controller_nw_info_set set network information
00244  *
00245  * \param interface_ptr interface
00246  * \param pan_id PAD ID
00247  * \param network_name network name
00248  *
00249  * \return < 0 failure
00250  * \return >= 0 success
00251  *
00252  */
00253 int8_t ws_pae_controller_nw_info_set(protocol_interface_info_entry_t *interface_ptr, uint16_t pan_id, char *network_name);
00254 
00255 /**
00256  * ws_pae_controller_nw_key_valid network key is valid i.e. used successfully on bootstrap
00257  *
00258  * \param interface_ptr interface
00259  *
00260  * \return < 0 failure
00261  * \return >= 0 success
00262  *
00263  */
00264 int8_t ws_pae_controller_nw_key_valid(protocol_interface_info_entry_t *interface_ptr);
00265 
00266 /**
00267  * ws_pae_controller_border_router_addr_write write border router address
00268  *
00269  * \param interface_ptr interface
00270  * \param eui_64 pointer to EUI-64
00271  *
00272  * \return < 0 failure
00273  * \return >= 0 success
00274  *
00275  */
00276 int8_t ws_pae_controller_border_router_addr_write(protocol_interface_info_entry_t *interface_ptr, const uint8_t *eui_64);
00277 
00278 /**
00279  * ws_pae_controller_border_router_addr_read read border router address
00280  *
00281  * \param interface_ptr interface
00282  * \param eui_64 pointer to EUI-64
00283  *
00284  * \return < 0 failure
00285  * \return >= 0 success
00286  *
00287  */
00288 int8_t ws_pae_controller_border_router_addr_read(protocol_interface_info_entry_t *interface_ptr, uint8_t *eui_64);
00289 
00290 /**
00291  * ws_pae_controller_gtk_update update GTKs (test interface)
00292  *
00293  * \param interface_id interface identifier
00294  * \param gtk GTK array, if GTK is not set, pointer for the index shall be NULL.
00295  *
00296  * \return < 0 failure
00297  * \return >= 0 success
00298  *
00299  */
00300 int8_t ws_pae_controller_gtk_update(int8_t interface_id, uint8_t *gtk[4]);
00301 
00302 /**
00303  * ws_pae_controller_next_gtk_update update next GTKs used during GTK lifecycle (test interface)
00304  *
00305  * \param interface_id interface identifier
00306  * \param gtk GTK array, if GTK is not set, pointer for the index shall be NULL.
00307  *
00308  * \return < 0 failure
00309  * \return >= 0 success
00310  *
00311  */
00312 int8_t ws_pae_controller_next_gtk_update(int8_t interface_id, uint8_t *gtk[4]);
00313 
00314 /**
00315  * ws_pae_controller_key_lifetime_update update key lifetime
00316  *
00317  * \param interface_id interface identifier
00318  * \param gtk_lifetime GTK lifetime
00319  * \param pmk_lifetime PMK lifetime
00320  * \param ptk_lifetime PTK lifetime
00321  *
00322  * \return < 0 failure
00323  * \return >= 0 success
00324  *
00325  */
00326 int8_t ws_pae_controller_key_lifetime_update(int8_t interface_id, uint32_t gtk_lifetime, uint32_t pmk_lifetime, uint32_t ptk_lifetime);
00327 
00328 /**
00329  * ws_pae_controller_gtk_time_settings_update update GTK time settings
00330  *
00331  * \param interface_id interface identifier
00332  * \param revocat_lifetime_reduct revocation lifetime reduction
00333  * \param new_activation_time new activation time
00334  * \param new_install_req new install required
00335  * \param max_mismatch max mismatch time
00336  *
00337  * \return < 0 failure
00338  * \return >= 0 success
00339  *
00340  */
00341 int8_t ws_pae_controller_gtk_time_settings_update(int8_t interface_id, uint8_t revocat_lifetime_reduct, uint8_t new_activation_time, uint8_t new_install_req, uint32_t max_mismatch);
00342 
00343 /**
00344  * ws_pae_controller_node_keys_remove remove node's keys
00345  *
00346  * \param interface_id interface identifier
00347  * \param eui-64 EUI-64
00348  *
00349  * \return < 0 failure
00350  * \return >= 0 success
00351  *
00352  */
00353 int8_t ws_pae_controller_node_keys_remove(int8_t interface_id, uint8_t *eui_64);
00354 
00355 /**
00356  * ws_pae_controller_node_access_revoke_start start node's access revoke
00357  *
00358  * \param interface_id interface identifier
00359  *
00360  * \return < 0 failure
00361  * \return >= 0 success
00362  *
00363  */
00364 int8_t ws_pae_controller_node_access_revoke_start(int8_t interface_id);
00365 
00366 /**
00367  * ws_pae_controller_node_limit_set set node limit
00368  *
00369  * \param interface_id interface identifier
00370  * \param limit limit for nodes
00371  *
00372  * \return < 0 failure
00373  * \return >= 0 success
00374  *
00375  */
00376 int8_t ws_pae_controller_node_limit_set(int8_t interface_id, uint16_t limit);
00377 
00378 /**
00379  * ws_pae_controller_ext_certificate_validation_set enable or disable extended certificate validation
00380  *
00381  * \param interface_ptr interface
00382  * \param enabled       true to enable extended validation, false to disable
00383  *
00384  * \return < 0 failure
00385  * \return >= 0 success
00386  *
00387  */
00388 int8_t ws_pae_controller_ext_certificate_validation_set(int8_t interface_id, bool enabled);
00389 
00390 /**
00391  * ws_pae_controller_active_key_update update active key (test interface)
00392  *
00393  * \param interface_id interface identifier
00394  * \param index GTK index
00395  *
00396  * \return < 0 failure
00397  * \return >= 0 success
00398  *
00399  */
00400 int8_t ws_pae_controller_active_key_update(int8_t interface_id, uint8_t index);
00401 
00402 /**
00403  * ws_pae_controller_gtk_hash_ptr_get get pointer to GTK hash storage
00404  *
00405  * \param interface_ptr interface
00406  *
00407  * \return pointer to GTK has storage or NULL
00408  *
00409  */
00410 uint8_t *ws_pae_controller_gtk_hash_ptr_get(protocol_interface_info_entry_t *interface_ptr);
00411 
00412 /**
00413  * ws_pae_controller_gtk_hash_update GTK hash has been updated (on PAN configuration)
00414  *
00415  * \param interface_ptr interface
00416  * \param gtkhash new GTK hash
00417  *
00418  * \return < 0 failure
00419  * \return >= 0 success
00420  *
00421  */
00422 int8_t ws_pae_controller_gtk_hash_update(protocol_interface_info_entry_t *interface_ptr, uint8_t *gtkhash);
00423 
00424 /**
00425  * ws_pae_controller_nw_key_index_update key index been updated (on PAN configuration)
00426  *
00427  * \param interface_ptr interface
00428  * \param index key index
00429  *
00430  * \return < 0 failure
00431  * \return >= 0 success
00432  *
00433  */
00434 int8_t ws_pae_controller_nw_key_index_update(protocol_interface_info_entry_t *interface_ptr, uint8_t index);
00435 
00436 /**
00437  * ws_pae_controller_nw_keys_remove remove network keys
00438  *
00439  * \param interface_ptr interface
00440  *
00441  */
00442 void ws_pae_controller_nw_keys_remove(protocol_interface_info_entry_t *interface_ptr);
00443 
00444 /**
00445  * ws_pae_controller_nw_key_insert network key insert callback
00446  *
00447  * \param interface_ptr interface
00448  * \param slot key slot (MAC key descriptor), from 0 to 4
00449  * \param index index of the new network key
00450  * \param key new key
00451  *
00452  */
00453 typedef void ws_pae_controller_nw_key_set(protocol_interface_info_entry_t *interface_ptr, uint8_t slot, uint8_t index, uint8_t *key);
00454 
00455 /**
00456  * ws_pae_controller_nw_key_clear network key clear callback
00457  *
00458  * \param interface_ptr interface
00459  * \param slot key slot (MAC key descriptor), from 0 to 4
00460  *
00461  */
00462 typedef void ws_pae_controller_nw_key_clear(protocol_interface_info_entry_t *interface_ptr, uint8_t slot);
00463 
00464 /**
00465  * ws_pae_controller_nw_send_key_index_set network send key index set callback
00466  *
00467  * \param interface_ptr interface
00468  * \param index index of the key to be used on sending
00469  *
00470  */
00471 typedef void ws_pae_controller_nw_send_key_index_set(protocol_interface_info_entry_t *interface_ptr, uint8_t index);
00472 
00473 /**
00474  * ws_pae_controller_nw_frame_counter_set network frame counter set callback
00475  *
00476  * \param interface_ptr interface
00477  * \param counter frame counter
00478  * \param slot key slot (MAC key descriptor), from 0 to 4
00479  *
00480  */
00481 typedef void ws_pae_controller_nw_frame_counter_set(protocol_interface_info_entry_t *interface_ptr, uint32_t counter, uint8_t slot);
00482 
00483 /**
00484  * ws_pae_controller_nw_frame_counter_read network frame counter read callback
00485  *
00486  * \param interface_ptr interface
00487  * \param counter frame counter
00488  *
00489  */
00490 typedef void ws_pae_controller_nw_frame_counter_read(protocol_interface_info_entry_t *interface_ptr, uint32_t *counter, uint8_t slot);
00491 
00492 /**
00493  * ws_pae_controller_auth_completed authentication completed callback
00494  *
00495  * \param interface_ptr interface
00496  * \param result result, either ok or failure reason
00497  * \param target_eui_64 EAPOL target in case of failure or NULL
00498  *
00499  */
00500 typedef void ws_pae_controller_auth_completed(protocol_interface_info_entry_t *interface_ptr, auth_result_e result, uint8_t *target_eui_64);
00501 
00502 /**
00503  * ws_pae_controller_pan_ver_increment PAN version increment callback
00504  *
00505  * \param interface_ptr interface
00506  *
00507  */
00508 typedef void ws_pae_controller_pan_ver_increment(protocol_interface_info_entry_t *interface_ptr);
00509 
00510 /**
00511  * ws_pae_controller_cb_register register PEA controller callbacks
00512  *
00513  * \param interface_ptr interface
00514  * \param completed authentication completed callback
00515  * \param nw_key_set network key set callback
00516  * \param nw_key_clear network key clear callback
00517  * \param nw_send_key_index_set network send key index set callback
00518  * \param nw_frame_counter_set network frame counter set callback
00519  * \param nw_frame_counter_read network frame counter read callback
00520  * \param pan_ver_increment PAN version increment callback
00521  *
00522  * \return < 0 failure
00523  * \return >= 0 success
00524  *
00525  */
00526 int8_t ws_pae_controller_cb_register(protocol_interface_info_entry_t *interface_ptr, ws_pae_controller_auth_completed *completed, ws_pae_controller_nw_key_set *nw_key_set, ws_pae_controller_nw_key_clear *nw_key_clear, ws_pae_controller_nw_send_key_index_set *nw_send_key_index_set, ws_pae_controller_nw_frame_counter_set *nw_frame_counter_set, ws_pae_controller_nw_frame_counter_read *nw_frame_counter_read, ws_pae_controller_pan_ver_increment *pan_ver_increment);
00527 
00528 /**
00529  * ws_pae_controller_fast_timer PAE controller fast timer call
00530  *
00531  * \param ticks elapsed ticks
00532  *
00533  */
00534 void ws_pae_controller_fast_timer(uint16_t ticks);
00535 
00536 /**
00537  * ws_pae_controller_slow_timer PAE controller slow timer call
00538  *
00539  * \param seconds elapsed seconds
00540  *
00541  */
00542 void ws_pae_controller_slow_timer(uint16_t seconds);
00543 
00544 struct nvm_tlv_entry *ws_pae_controller_nvm_tlv_get(protocol_interface_info_entry_t *interface_ptr);
00545 
00546 /**
00547  * ws_pae_controller_forced_gc PAE controller garbage cleanup callback
00548  *
00549  * \param full_gc Full cleanup (true for critical garbage cleanup)
00550  *
00551  */
00552 void ws_pae_controller_forced_gc(bool full_gc);
00553 
00554 #else
00555 
00556 #define ws_pae_controller_set_target(interface_ptr, target_pan_id, target_dest_eui_64)
00557 #define ws_pae_controller_authenticate(interface_ptr)
00558 
00559 #define ws_pae_controller_authenticator_start(interface_ptr, local_port, remote_address, remote_port)
00560 
00561 #define ws_pae_controller_border_router_addr_write(interface_ptr, eui_64) -1
00562 #define ws_pae_controller_border_router_addr_read(interface_ptr, eui_64) -1
00563 
00564 #define ws_pae_controller_gtk_set(interface_id, gtk) -1
00565 #define ws_pae_controller_next_gtks_update(interface_id, gtk) -1
00566 
00567 #define ws_pae_controller_init(interface_ptr) 1
00568 #define ws_pae_controller_supp_init(interface_ptr) 1
00569 #define ws_pae_controller_auth_init(interface_ptr) 1
00570 
00571 #define ws_pae_controller_stop(interface_ptr)
00572 #define ws_pae_controller_delete(interface_ptr)
00573 #define ws_pae_controller_cb_register(interface_ptr, completed, nw_key_set, nw_key_clear, nw_send_key_index_set, pan_ver_increment) 1
00574 #define ws_pae_controller_nvm_tlv_get(interface_ptr) NULL
00575 
00576 #define ws_pae_controller_forced_gc NULL
00577 
00578 #endif
00579 
00580 #endif /* WS_PAE_CONTROLLER_H_ */