mle_service_security.h

00001 /*
00002  * Copyright (c) 2015-2017, 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 /*
00019  * \file mle_service_security.h
00020  * \brief Add short description about this file!!!
00021  *
00022  */
00023 
00024 #ifndef MLE_SERVICE_SECURITY_H_
00025 #define MLE_SERVICE_SECURITY_H_
00026 #include <ns_types.h>
00027 #include "Service_Libs/mle_service/mle_service_api.h"
00028 
00029 struct mle_security_header;
00030 
00031 #define MLE_MAX_KEY_TABLE_SIZE 2
00032 
00033 typedef struct mle_security_key {
00034     uint8_t aes_key[16]; /*!< Security key */
00035     uint8_t key_id; /*!< Key id */
00036     bool primary_key:1; /*!< define primary or secondary key */
00037     bool pending_primary:1; /*!< define key switch to primary when key is request or used first time when it is true */
00038     bool key_valid:1; /*!< Define that structure include valid data */
00039 } mle_security_key_t;
00040 
00041 
00042 typedef struct mle_security_components {
00043     mle_security_key_t mle_security_key_table[MLE_MAX_KEY_TABLE_SIZE]; /*!< Security key table */
00044     uint32_t security_frame_counter; /*!< Security frame counter */
00045     uint8_t sec_level; /*!< Security level for message*/
00046     mle_service_key_request_by_counter_cb * key_req; /*!< Security key request for 32-bit key source*/
00047     mle_service_security_notify_cb *security_notify; /*!< Security notify event call back*/
00048 } mle_security_components_t;
00049 
00050 /**
00051  * Registered mle service security class for given interface
00052  *
00053  * \param interface_id interface id
00054  *
00055  * \return 0 allocate ok
00056  * \return < 0 allocate fail
00057  */
00058 int mle_service_security_instance_allocate(int8_t interface_id);
00059 
00060 /**
00061  * Find registered service client class by given interface id
00062  *
00063  * \param interface_id interface id
00064  *
00065  * \return >0 Pointer to interface structure
00066  * \return < 0 Unknown interface id
00067  */
00068 mle_security_components_t * mle_service_security_params_get(int8_t interface_id);
00069 
00070 /**
00071  * Free mle service security class
00072  *
00073  * \param interface_id interface id
00074  *
00075  * \return 0 free ok
00076  * \return < 0 Unknown interface id
00077  */
00078 int mle_service_security_instance_delete(int8_t interface_id);
00079 
00080 /**
00081  * Init default settings to mle service security class
00082  *
00083  * Clean all keys from class
00084  *
00085  * \param sec_ptr security class pointer
00086  *
00087  */
00088 void mle_service_security_parameters_init(mle_security_components_t *sec_ptr);
00089 
00090 /**
00091  * Get default security key id
00092  *
00093  *
00094  * \param sec_ptr security class pointer
00095  *
00096  * \return key id
00097  */
00098 uint8_t mle_service_security_get_default_key_id(mle_security_components_t *sec_ptr);
00099 
00100 
00101 /**
00102  * Get security key class by given id
00103  *
00104  *
00105  * \param sec_ptr security class pointer
00106  * \param key_id key id
00107  *
00108  * \return >0 valid key class pointer
00109  * \retun NULL when key is unknown
00110  */
00111 mle_security_key_t * mle_service_security_key_get(mle_security_components_t *sec_ptr, uint8_t key_id );
00112 
00113 /**
00114  * Get / update security class mle security counter
00115  *
00116  *
00117  * \param sec_ptr security class pointer
00118  * \param increment true update counter false return current value
00119  *
00120  * \return security counter
00121  */
00122 uint32_t mle_service_security_get_framecounter(mle_security_components_t *sec_ptr, bool increment);
00123 
00124 /**
00125  * Get security key pointer
00126  *
00127  *
00128  * \param securityHeader pointer to mle message security header
00129  * \param sec_ptr security class pointer
00130  *
00131  * \return >0 Valid key pointer
00132  * \return NULL unknown key
00133  */
00134 uint8_t *mle_service_security_get_key(struct mle_security_header *securityHeader, mle_security_components_t *sec_ptr, int8_t interfaceId);
00135 
00136 /**
00137  * MLE security pending key trig by key id
00138  *
00139  * \param sec_ptr security class pointer
00140  * \param keyId pending key id
00141  *
00142  * \return true trig ok
00143  * \return false key id not valid
00144  */
00145 bool mle_service_security_key_update_trig(uint8_t interface_id, mle_security_components_t *sec_ptr, uint8_t keyId);
00146 
00147 /**
00148  * MLE security key update
00149  *
00150  * \param sec_ptr security class pointer
00151  * \param key pointer to 128-bit key
00152  * \param keyId key id
00153  * \param set_primary true Primary key false pending key
00154  *
00155  * \return true update ok
00156  * \return false update fail
00157  */
00158 bool mle_service_security_key_set(mle_security_components_t *sec_ptr, const uint8_t *key, uint8_t keyId, bool set_primary);
00159 
00160 /**
00161  * MLE security default key get
00162  *
00163  * \param sec_ptr security class pointer
00164  *
00165  * \return > 0 Pointer to default key
00166  * \return NULL no default key available
00167  */
00168 uint8_t *mle_service_security_get_default_key(mle_security_components_t *sec_ptr);
00169 
00170 /**
00171  * MLE security default key id get
00172  *
00173  * \param sec_ptr security class pointer
00174  *
00175  * \return > 0 Key id
00176  * \return 0 default key is not available
00177  */
00178 uint8_t mle_service_security_get_next_key_id(mle_security_components_t *sec_ptr);
00179 
00180 /**
00181  * MLE security Secondary key get
00182  *
00183  * \param sec_ptr security class pointer
00184  *
00185  * \return > 0 Key pointer
00186  * \return NULL key is not available
00187  */
00188 uint8_t *mle_service_security_get_next_key(mle_security_components_t *sec_ptr);
00189 
00190 #endif /* MLE_SERVICE_SECURITY_H_ */