ws_pae_auth.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_AUTH_H_
00019 #define WS_PAE_AUTH_H_
00020 
00021 #ifdef HAVE_PAE_AUTH
00022 
00023 /*
00024  * Authenticator port access entity controls key security protocols using KMP API.
00025  *
00026  * Configures KMP service network access and provides timing and callback services
00027  * for it. Registers needed security protocols to KMP service.
00028  *
00029  * PAE Maintains security keys that are internal to port access entity for
00030  * each supplicant and maintains supplicant security registration state.
00031  *
00032  * Autenticator PAE controls network access keys and provides new network
00033  * access keys to supplicants when they are changed. When supplicant
00034  * network keys are updated, also other keys (master key, pairwise key)
00035  * are updated as needed.
00036  *
00037  */
00038 
00039 /**
00040  * ws_pae_auth_init initializes PAE authenticator
00041  *
00042  * \param interface_ptr interface
00043  * \param local_port local port
00044  * \param remote_addr remote address
00045  * \param remote_port remote port
00046  * \param gtks group keys
00047  * \param next_gtks next group keys to be used
00048  * \param cert_chain certificate chain
00049  * \param timer_settings timer settings
00050  *
00051  * \return < 0 failure
00052  * \return >= 0 success
00053  *
00054  */
00055 int8_t ws_pae_auth_init(protocol_interface_info_entry_t *interface_ptr, sec_prot_gtk_keys_t *gtks, sec_prot_gtk_keys_t *next_gtks, const sec_prot_certs_t *certs, timer_settings_t *timer_settings);
00056 
00057 /**
00058  * ws_pae_auth_timing_adjust Adjust retries and timings of the security protocols
00059  *
00060  * Timing value is a generic number between 0 to 32 that goes from fast and
00061  * reactive network to low bandwidth and long latency.
00062  *
00063  * example value definitions:
00064  * 0-8 very fast network
00065  * 9-16 medium network
00066  * 16-24 slow network
00067  * 25-32 extremely slow network
00068  *
00069  * There is no need to have lots variations in every layer if protocol is not very active in any case.
00070  *
00071  * \param timing Timing value.
00072  *
00073  * \return < 0 failure
00074  * \return >= 0 success
00075  *
00076  */
00077 int8_t ws_pae_auth_timing_adjust(uint8_t timing);
00078 
00079 /**
00080  * ws_pae_auth_addresses_set set relay addresses
00081  *
00082  * \param interface_ptr interface
00083  * \param local_port local port
00084  * \param remote_addr remote address
00085  * \param remote_port remote port
00086  *
00087  * \return < 0 failure
00088  * \return >= 0 success
00089  *
00090  */
00091 int8_t ws_pae_auth_addresses_set(protocol_interface_info_entry_t *interface_ptr, uint16_t local_port, const uint8_t *remote_addr, uint16_t remote_port);
00092 
00093 /**
00094  * ws_pae_auth_delete deletes PAE authenticator
00095  *
00096  * \param interface_ptr interface
00097  *
00098  * \return < 0 failure
00099  * \return >= 0 success
00100  *
00101  */
00102 int8_t ws_pae_auth_delete(protocol_interface_info_entry_t *interface_ptr);
00103 
00104 /**
00105  * ws_pae_auth_fast_timer PAE authenticator fast timer call
00106  *
00107  * \param ticks elapsed ticks
00108  *
00109  */
00110 void ws_pae_auth_fast_timer(uint16_t ticks);
00111 
00112 /**
00113  * ws_pae_auth_slow_timer PAE authenticator slow call
00114  *
00115  * \param seconds elapsed seconds
00116  *
00117  */
00118 void ws_pae_auth_slow_timer(uint16_t seconds);
00119 
00120 /**
00121  * ws_pae_auth_start start PAE authenticator
00122  *
00123  * \param interface_ptr interface
00124  *
00125  */
00126 void ws_pae_auth_start(protocol_interface_info_entry_t *interface_ptr);
00127 
00128 /**
00129  * ws_pae_auth_gtks_updated indicates that GTKs has been updated
00130  *
00131  * \param interface_ptr interface
00132  *
00133  */
00134 void ws_pae_auth_gtks_updated(protocol_interface_info_entry_t *interface_ptr);
00135 
00136 /**
00137  * ws_pae_auth_gtks_updated indicates that key index has been updated
00138  *
00139  * \param interface_ptr interface
00140  * \param index key index
00141  *
00142  * \return < 0 failure
00143  * \return >= 0 success
00144  *
00145  */
00146 int8_t ws_pae_auth_nw_key_index_update(protocol_interface_info_entry_t *interface_ptr, uint8_t index);
00147 
00148 /**
00149  * ws_pae_auth_node_keys_remove removes nodes keys
00150  *
00151  * \param interface_ptr interface
00152  * \param eui64 node's EUI-64
00153  *
00154  * \return < 0 failure
00155  * \return >= 0 success
00156  *
00157  */
00158 int8_t ws_pae_auth_node_keys_remove(protocol_interface_info_entry_t *interface_ptr, uint8_t *eui64);
00159 
00160 /**
00161  * ws_pae_auth_node_access_revoke_start start node's access revoke
00162  *
00163  * \param interface_ptr interface
00164  *
00165  * \return < 0 failure
00166  * \return >= 0 success
00167  *
00168  */
00169 int8_t ws_pae_auth_node_access_revoke_start(protocol_interface_info_entry_t *interface_ptr);
00170 
00171 /**
00172  * ws_pae_auth_node_limit_set set node limit
00173  *
00174  * \param interface_ptr interface
00175  * \param limit limit for nodes
00176  *
00177  * \return < 0 failure
00178  * \return >= 0 success
00179  *
00180  */
00181 int8_t ws_pae_auth_node_limit_set(protocol_interface_info_entry_t *interface_ptr, uint16_t limit);
00182 
00183 /**
00184  * ws_pae_auth_forced_gc garbage cleanup call
00185  *
00186  * \param interface_ptr interface
00187  *
00188  */
00189 void ws_pae_auth_forced_gc(protocol_interface_info_entry_t *interface_ptr);
00190 
00191 /**
00192  * ws_pae_auth_gtk_hash_set GTK hash set callback
00193  *
00194  * \param interface_ptr interface
00195  * \param gtkhash GTK hash, 32 bytes
00196  *
00197  */
00198 typedef void ws_pae_auth_gtk_hash_set(protocol_interface_info_entry_t *interface_ptr, uint8_t *gtkhash);
00199 
00200 /**
00201  * ws_pae_auth_nw_key_insert network key insert callback
00202  *
00203  * \param interface_ptr interface
00204  * \param gtks group keys
00205  *
00206  * \return < 0 failure
00207  * \return >= 0 success
00208  *
00209  */
00210 typedef int8_t ws_pae_auth_nw_key_insert(protocol_interface_info_entry_t *interface_ptr, sec_prot_gtk_keys_t *gtks);
00211 
00212 /**
00213  * ws_pae_auth_nw_key_index_set network send key index set callback
00214  *
00215  * \param interface_ptr interface
00216  * \param index network send key index
00217  *
00218  */
00219 typedef void ws_pae_auth_nw_key_index_set(protocol_interface_info_entry_t *interface_ptr, uint8_t index);
00220 
00221 /**
00222  *  ws_pae_auth_cb_register register PAE authenticator callbacks
00223  *
00224  * \param interface_ptr interface
00225  * \param hash_set GTK hash set callback
00226  * \param nw_key_insert network key index callback
00227  * \param nw_key_index_set network send key index callback
00228  *
00229  */
00230 void ws_pae_auth_cb_register(protocol_interface_info_entry_t *interface_ptr, ws_pae_auth_gtk_hash_set *hash_set, ws_pae_auth_nw_key_insert *nw_key_insert, ws_pae_auth_nw_key_index_set *nw_key_index_set);
00231 
00232 #else
00233 
00234 #define ws_pae_auth_init(interface_ptr, gtks, next_gtks, certs, timer_settings) 1
00235 #define ws_pae_auth_timing_adjust(timing) 1
00236 #define ws_pae_auth_addresses_set(interface_ptr, local_port, remote_addr, remote_port) 1
00237 #define ws_pae_auth_delete NULL
00238 #define ws_pae_auth_cb_register(interface_ptr, hash_set, nw_key_insert, nw_key_index_set) {(void) hash_set;}
00239 #define ws_pae_auth_start(interface_ptr)
00240 #define ws_pae_auth_gtks_updated NULL
00241 #define ws_pae_auth_nw_key_index_update NULL
00242 #define ws_pae_auth_node_keys_remove(interface_ptr, eui64) -1
00243 #define ws_pae_auth_node_access_revoke_start(interface_ptr)
00244 #define ws_pae_auth_node_limit_set(interface_ptr, limit)
00245 #define ws_pae_auth_forced_gc(interface_ptr)
00246 #define ws_pae_auth_fast_timer NULL
00247 #define ws_pae_auth_slow_timer NULL
00248 
00249 #endif
00250 
00251 #endif /* WS_PAE_AUTH_H_ */