1 /* 2 * Copyright (c) 2021, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright notice, this 11 * list of conditions and the following disclaimer. 12 * 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE 24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 * POSSIBILITY OF SUCH DAMAGE. 32 * 33 */ 34 35 #ifndef NRF_802154_SECURITY_PIB_H__ 36 #define NRF_802154_SECURITY_PIB_H__ 37 38 #include "nrf_802154_types.h" 39 40 /** 41 * @brief Initialises the Key Storage inside the nRF 802.15.4 Radio Driver. 42 * 43 * @return NRF_802154_SECURITY_ERROR_NONE if no error, otherwise the corresponding 44 * error code. 45 */ 46 nrf_802154_security_error_t nrf_802154_security_pib_init(void); 47 48 /** 49 * @brief Deinitialises the Key Storage inside the nRF 802.15.4 Radio Driver. 50 * 51 * @return NRF_802154_SECURITY_ERROR_NONE if no error, otherwise the corresponding 52 * error code. 53 */ 54 nrf_802154_security_error_t nrf_802154_security_pib_deinit(void); 55 56 /** 57 * @brief Stores the 802.15.4 MAC Security Key inside the nRF 802.15.4 Radio Driver. 58 * 59 * @param[in] p_key Pointer to the key to store. Refer to @ref nrf_802154_key_t for details. 60 * Storing the key copies the content of the key into the Radio Driver. 61 * This input parameter can be destroyed after the call. 62 * 63 * @note This function is not reentrant and must be called from thread context only. 64 * 65 * @retval NRF_802154_SECURITY_ERROR_NONE Storing of key is successful. 66 * @retval NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED Type of the key is not supported. 67 * @retval NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED ID mode of the key is not supported. 68 * @retval NRF_802154_SECURITY_ERROR_ALREADY_PRESENT Failed to store the key - key of such id is already 69 * present. Remove the key first to overwrite. 70 * @retval NRF_802154_SECURITY_ERROR_STORAGE_FULL Failed to store the key - storage full. 71 */ 72 nrf_802154_security_error_t nrf_802154_security_pib_key_store(nrf_802154_key_t * p_key); 73 74 /** 75 * @brief Removes the 802.15.4 MAC Security Key from the nRF 802.15.4 Radio Driver. 76 * 77 * @param[in] p_id Pointer to the ID of the key to remove. 78 * 79 * @note This function is not reentrant and must be called from thread context only. 80 * 81 * @retval NRF_802154_SECURITY_ERROR_NONE Removal of key is successful. 82 * @retval NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND Failed to remove the key - no such key found. 83 */ 84 nrf_802154_security_error_t nrf_802154_security_pib_key_remove(nrf_802154_key_id_t * p_id); 85 86 /** 87 * @brief Removes all stored 802.15.4 MAC Security Keys from the nRF 802.15.4 Radio Driver. 88 * 89 * @note This function is not reentrant and must be called from thread context only. 90 */ 91 void nrf_802154_security_pib_key_remove_all(void); 92 93 /** 94 * @brief Uses the 802.15.4 MAC Security Key stored previously in the nRF 802.15.4 Radio Driver. 95 * 96 * @param[in] p_id Pointer to the ID of the key to use. 97 * @param[out] destination Destination where the key must be copied. In case of 98 * hardware accelerated solutions this parameter is ignored. 99 * 100 * @retval NRF_802154_SECURITY_ERROR_NONE Usage of key is successful. 101 * @retval NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND Failed to use the key - no such key found. 102 */ 103 nrf_802154_security_error_t nrf_802154_security_pib_key_use(nrf_802154_key_id_t * p_id, 104 void * destination); 105 106 /** 107 * @brief Sets nRF 802.15.4 Radio Driver MAC Global Frame Counter. 108 * 109 * @param[in] frame_counter Frame counter to set. 110 */ 111 void nrf_802154_security_pib_global_frame_counter_set(uint32_t frame_counter); 112 113 /** 114 * @brief Sets nRF 802.15.4 Radio Driver MAC Global Frame Counter if the value passed is larger than current. 115 * 116 * @param[in] frame_counter Frame counter to set. 117 */ 118 void nrf_802154_security_pib_global_frame_counter_set_if_larger(uint32_t frame_counter); 119 120 /** 121 * @brief Get the next 802.15.4 global frame counter. 122 * 123 * @param[out] p_frame_counter Pointer to the frame counter to populate. 124 * @param[in] p_id Pointer to the ID of the key to get the frame counter for. 125 * 126 * @retval NRF_802154_SECURITY_ERROR_NONE The p_frame_counter field was 127 * successfully populated. 128 * @retval NRF_802154_SECURITY_ERROR_FRAME_COUNTER_OVERFLOW No more available frame counters, 129 * they must be reset. 130 * @retval NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND The associated key was not found. 131 */ 132 nrf_802154_security_error_t nrf_802154_security_pib_frame_counter_get_next( 133 uint32_t * p_frame_counter, 134 nrf_802154_key_id_t * p_id); 135 136 #endif // NRF_802154_SECURITY_PIB_H__ 137
