sec_prot_lib.h

00001 /*
00002  * Copyright (c) 2016-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 SEC_PROT_LIB_H_
00019 #define SEC_PROT_LIB_H_
00020 
00021 /*
00022  * Library functions used by security protocols. These include helper functions
00023  * related to different hash functions, common message handling functions, and
00024  * common timer and state machine functions.
00025  *
00026  */
00027 
00028 #define EUI64_LEN                     8
00029 #define SEC_TOTAL_TIMEOUT             30 * 60 * 10 // 30 minutes
00030 #define SEC_FINISHED_TIMEOUT          5 * 10       // 5 seconds
00031 
00032 #define FWH_NONCE_LENGTH              32
00033 #define EUI64_LEN                     8
00034 #define SEC_TOTAL_TIMEOUT             30 * 60 * 10 // 30 minutes
00035 #define SEC_INIT_TIMEOUT              60 * 10      // 60 seconds
00036 #define SEC_FINISHED_TIMEOUT          5 * 10       // 5 seconds
00037 
00038 
00039 // Common data shared between security protocols needing general timers and state machines
00040 typedef struct {
00041     trickle_t                     trickle_timer;    /**< Trickle timer for re-sending */
00042     uint16_t                      ticks;            /**< Timer ticks */
00043     int8_t                        state;            /**< Protocol state machine state */
00044     sec_prot_result_e             result;           /**< Result for ongoing negotiation */
00045     bool                          trickle_running;  /**< Trickle running */
00046 } sec_prot_common_t;
00047 
00048 /**
00049  * sec_prot_lib_nonce_init init nonce
00050  *
00051  * \param nonce nonce
00052  * \param eui64 EUI-64
00053  * \param time current time
00054  *
00055  */
00056 void sec_prot_lib_nonce_init(uint8_t *nonce, uint8_t *eui64, uint64_t time);
00057 
00058 /**
00059  * sec_prot_lib_nonce_generate generates nonce
00060  *
00061  * \param nonce nonce
00062  *
00063  */
00064 void sec_prot_lib_nonce_generate(uint8_t *nonce);
00065 
00066 /**
00067  * sec_prot_lib_pmkid_calc calculates PKMID from PMK
00068  *
00069  * \param pmk PMK
00070  * \param auth_eui64 authenticator EUI-64
00071  * \param supp_eui64 supplicant EUI-64
00072  * \param pmkid PMKID
00073  *
00074  * \return < 0 failure
00075  * \return >= 0 success
00076  */
00077 int8_t sec_prot_lib_pmkid_calc(const uint8_t *pmk, const uint8_t *auth_eui64, const uint8_t *supp_eui64, uint8_t *pmkid);
00078 
00079 /**
00080  * sec_prot_lib_ptkid_calc calculates PTMID from PTK
00081  *
00082  * \param pmk PTK
00083  * \param auth_eui64 authenticator EUI-64
00084  * \param supp_eui64 supplicant EUI-64
00085  * \param pmkid PTKID
00086  *
00087  * \return < 0 failure
00088  * \return >= 0 success
00089  */
00090 int8_t sec_prot_lib_ptkid_calc(const uint8_t *ptk, const uint8_t *auth_eui64, const uint8_t *supp_eui64, uint8_t *ptkid);
00091 
00092 /**
00093  * sec_prot_lib_ptk_calc calculates PTK from KMP, EUI-64s and nonces
00094  *
00095  * \param pmk PMK
00096  * \param eui64_1 first EUI-64
00097  * \param eui64_2 second EUI-64
00098  * \param nonce1 first nonce
00099  * \param nonce2 second nonce
00100  * \param ptk PTK
00101  *
00102  * \return < 0 failure
00103  * \return >= 0 success
00104  */
00105 int8_t sec_prot_lib_ptk_calc(const uint8_t *pmk, const uint8_t *eui64_1, const uint8_t *eui64_2, const uint8_t *nonce1, const uint8_t *nonce2, uint8_t *ptk);
00106 
00107 /**
00108  * sec_prot_lib_message_build builds a message
00109  *
00110  * \param ptk PTK for MIC calculation and encryption
00111  * \param kde KDEs
00112  * \param kde_len length of the KDEs
00113  * \param eapol_pdu EAPOL PDU
00114  * \param eapol_pdu_size EAPOL PDU size
00115  * \param header_size lower level header size
00116  *
00117  * \return < 0 failure
00118  * \return >= 0 success
00119  */
00120 uint8_t *sec_prot_lib_message_build(uint8_t *ptk, uint8_t *kde, uint16_t kde_len, eapol_pdu_t *eapol_pdu, uint16_t eapol_pdu_size, uint8_t header_size);
00121 
00122 /**
00123  * sec_prot_lib_message_handle handles a message
00124  *
00125  * \param ptk PTK for decryption
00126  * \param kde_len length of the KDEs
00127  * \param eapol_pdu EAPOL PDU
00128  *
00129  * \return pointer to start of the KDEs
00130  * \return NULL failure
00131  */
00132 uint8_t *sec_prot_lib_message_handle(uint8_t *ptk, uint16_t *kde_len, eapol_pdu_t *eapol_pdu);
00133 
00134 /**
00135  * sec_prot_lib_gtk_read reads GTK, GTKL and lifetime KDEs
00136  *
00137  * \param kde KDEs
00138  * \param kde_len length of the KDEs
00139  * \param sec_keys security keys
00140  *
00141  * \return < 0 failure
00142  * \return >= 0 success
00143  */
00144 int8_t sec_prot_lib_gtk_read(uint8_t *kde, uint16_t kde_len, sec_prot_keys_t *sec_keys);
00145 
00146 /**
00147  * sec_prot_lib_mic_validate validates MIC
00148  *
00149  * \param ptk PTK for MIC validation
00150  * \param kde_len length of the KDEs
00151  * \param pdu pointer to message
00152  * \param pdu_size message size
00153  *
00154  * \return < 0 failure
00155  * \return >= 0 success
00156  */
00157 int8_t sec_prot_lib_mic_validate(uint8_t *ptk, uint8_t *mic, uint8_t *pdu, uint8_t pdu_size);
00158 
00159 /**
00160  *  sec_prot_lib_pmkid_generate generate PMK ID from PMK
00161  *
00162  * \param prot security protocol
00163  * \param pmkid PMK ID
00164  * \param is_auth set for authenticator
00165  *
00166  * \return < 0 failure
00167  * \return >= 0 success
00168  */
00169 int8_t sec_prot_lib_pmkid_generate(sec_prot_t *prot, uint8_t *pmkid, bool is_auth);
00170 
00171 /**
00172  *  sec_prot_lib_ptkid_generate generate PTK ID from PTK
00173  *
00174  * \param prot security protocol
00175  * \param ptkid PTK ID
00176  * \param is_auth set for authenticator
00177  *
00178  * \return < 0 failure
00179  * \return >= 0 success
00180  */
00181 int8_t sec_prot_lib_ptkid_generate(sec_prot_t *prot, uint8_t *ptkid, bool is_auth);
00182 
00183 /**
00184  *  sec_prot_lib_gtkhash_generate generate GTK hash from GTK
00185  *
00186  * \param gtk GTK
00187  * \param gtk_hash GTK hash
00188  *
00189  * \return < 0 failure
00190  * \return >= 0 success
00191  */
00192 int8_t sec_prot_lib_gtkhash_generate(uint8_t *gtk, uint8_t *gtk_hash);
00193 
00194 /**
00195  * sec_prot_remote_eui_64_addr_get get remote EUI-64 (trusted EUI-64 from security keys)
00196  *
00197  * \param prot security protocol
00198  *
00199  * \return pointer to EUI-64 or NULL
00200  */
00201 uint8_t *sec_prot_remote_eui_64_addr_get(sec_prot_t *prot);
00202 
00203 /**
00204  * sec_prot_init initiates common data
00205  *
00206  * \param data common data
00207  *
00208  */
00209 void sec_prot_init(sec_prot_common_t *data);
00210 
00211 /**
00212  * sec_prot_init timeout handler
00213  *
00214  * \param prot protocol
00215  * \param data common data
00216  * \param trickle_params trickle parameters
00217  *
00218  */
00219 void sec_prot_timer_timeout_handle(sec_prot_t *prot, sec_prot_common_t *data, const trickle_params_t *trickle_params, uint16_t ticks);
00220 
00221 /**
00222  * sec_prot_timer_trickle_start starts trickle timer
00223  *
00224  * \param data common data
00225  * \param trickle_params trickle parameters
00226  *
00227  */
00228 void sec_prot_timer_trickle_start(sec_prot_common_t *data, const trickle_params_t *trickle_params);
00229 
00230 /**
00231  * sec_prot_timer_trickle_stop stops trickle timer
00232  *
00233  * \param data common data
00234  *
00235  */
00236 void sec_prot_timer_trickle_stop(sec_prot_common_t *data);
00237 
00238 /**
00239  * sec_prot_state_set sets state machine state
00240  *
00241  * \param prot protocol
00242  * \param data common data
00243  * \param state new state
00244  *
00245  */
00246 void sec_prot_state_set(sec_prot_t *prot, sec_prot_common_t *data, uint8_t state);
00247 
00248 /**
00249  * sec_prot_state_get gets state machine state
00250  *
00251  * \param data common data
00252  *
00253  * \return state
00254  *
00255  */
00256 uint8_t sec_prot_state_get(sec_prot_common_t *data);
00257 
00258 /**
00259  * sec_prot_result_set sets result for operation
00260  *
00261  * \param data common data
00262  * \param result result
00263  *
00264  */
00265 void sec_prot_result_set(sec_prot_common_t *data, sec_prot_result_e result);
00266 
00267 /**
00268  * sec_prot_result_get gets result for operation
00269  *
00270  * \param data common data
00271  *
00272  * \return result
00273  *
00274  */
00275 sec_prot_result_e sec_prot_result_get(sec_prot_common_t *data);
00276 
00277 /**
00278  * sec_prot_result_timeout_check checks if result is timeout
00279  *
00280  * \param data common data
00281  *
00282  * \return true result is timeout
00283  * \return false result is not timeout
00284  *
00285  */
00286 bool sec_prot_result_timeout_check(sec_prot_common_t *data);
00287 
00288 /**
00289  * sec_prot_result_ok_check checks if result is ok
00290  *
00291  * \param data common data
00292  *
00293  * \return true result is ok
00294  * \return false result is not ok
00295  *
00296  */
00297 bool sec_prot_result_ok_check(sec_prot_common_t *data);
00298 
00299 /**
00300  * sec_prot_default_timeout_set sets default timeout for protocol
00301  *
00302  * \param data common data
00303  *
00304  */
00305 void sec_prot_default_timeout_set(sec_prot_common_t *data);
00306 
00307 #endif /* SEC_PROT_LIB_H_ */