net_nvm_api.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 /**
00015  * \file net_nvm_api.h
00016  * \brief Library PANA NVM API for Client and Server.
00017  *
00018  * \section server-api Server NVM API
00019  *
00020  * PANA server security material is crypted always and if you change the border router RF module
00021  * decrypt does not work properly.
00022  *
00023  *  - pana_server_nvm_callback_set(),  Initialize PANA server NVM functionality.
00024  *  - pana_server_restore_from_nvm(), Load crypted PANA server base and security material from NVM.
00025  *  - pana_server_nvm_client_session_load(), Load crypted client session from NVM.
00026  *
00027  * \section client-api Client NVM API
00028  *
00029  * nw_nvm.c use already this API and the application can just use net_nvm_api.h.
00030  *
00031  * - pana_client_nvm_callback_set(), Initialize PANA session NVM.
00032  * - net_read_persistent_data(), Read NWK ID & MAC 16-bit address.
00033  * - net_nvm_data_load(), Load PANA session, NWK-ID and short address to stack for re-use.
00034  * - net_pana_client_session_nvm_data_load(), Load saved PANA session with specific address or not.
00035  *
00036  */
00037 #ifndef PANA_NVM_API_H_
00038 #define PANA_NVM_API_H_
00039 
00040 #include "ns_types.h"
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 #define PANA_CLIENT_NVM_SESSION_BUF_SIZE 70
00047 #define PANA_CLIENT_NVM_SESSION_BUF_SIZE_WITH_ADDRESS 86
00048 #define NET_NVM_SESSION_BUF_SIZE_WITH_NET_PARAMS_AND_PANA 88
00049 
00050 #define PANA_SERVER_CLIENT_NVM_SESSION_UNCRYPTED_DATA_SIZE 20
00051 #define PANA_SERVER_CLIENT_NVM_SESSION_FULL_ENCRYPTED_DATA_SIZE 96
00052 #define PANA_SERVER_CLIENT_NVM_SESSION_SEQUENCY_STATE_ENCRYPTED_DATA_SIZE 33
00053 #define PANA_SERVER_CLIENT_NVM_SESSION_BUF_SIZE (PANA_SERVER_CLIENT_NVM_SESSION_UNCRYPTED_DATA_SIZE + PANA_SERVER_CLIENT_NVM_SESSION_FULL_ENCRYPTED_DATA_SIZE)
00054 
00055 
00056 #define PANA_SERVER_MATERIAL_BUF_SIZE 90
00057 /*!
00058  * \enum pana_nvm_update_process_t
00059  * \brief PANA server NVM update states.
00060  */
00061 typedef enum pana_nvm_update_process_t {
00062     PANA_SERVER_MATERIAL_UPDATE,                /**< PANA server security material update. */
00063     PANA_SERVER_CLIENT_SESSION_UPDATE,          /**< PANA client session update. */
00064     PANA_SERVER_CLIENT_SESSION_SEQ_UPDATE,      /**< PANA client session sequence number update. */
00065     PANA_SERVER_CLIENT_SESSION_REMOVE_UPDATE,   /**< PANA client session remove. */
00066 } pana_nvm_update_process_t;
00067 
00068 /*!
00069  * \enum pana_client_nvm_update_process_t
00070  * \brief PANA client NVM update states.
00071  */
00072 typedef enum pana_client_nvm_update_process_t {
00073     PANA_CLIENT_SESSION_UPDATE,     /**< PANA session information fully update.  */
00074     PANA_CLIENT_SESSION_SEQ_UPDATE, /**< PANA key pull or push operation update REQ and RES sequence number. */
00075 } pana_client_nvm_update_process_t;
00076 
00077 /* NVM API PART */
00078 /**
00079  * \brief PANA server NVM functionality initialization.
00080  *
00081  * \param passed_fptr A function pointer to NVM update process.
00082  * \param nvm_static_buffer A pointer to application allocated static memory, minimum size 115 bytes.
00083  *
00084  *
00085  * Reference callback function structure using EEPROM:
00086  * - nvm_static_buffer Application is allocated a static buffer.
00087  *
00088  * \return 0, Init OK.
00089  * \return -1, Null parameter detect.
00090  *
00091  */
00092 extern int8_t pana_server_nvm_callback_set(uint16_t (*passed_fptr)(pana_nvm_update_process_t), uint8_t *nvm_static_buffer);
00093 /**
00094  * \brief PANA server base restore from NVM.
00095  *
00096  * \param nvm_data A pointer to encrypted PANA server base data.
00097  *
00098  * \return 0, Restore OK.
00099  * \return -1, Memory allocation fail.
00100  *
00101  */
00102 extern int8_t pana_server_restore_from_nvm(uint8_t *nvm_data, int8_t interface_id);
00103 /**
00104  * \brief PANA client session load from NVM API.
00105  *
00106  * \param nvm_data A pointer to encrypted PANA client session.
00107  *
00108  * \return 0, Restore OK.
00109  * \return -1, Memory allocation fail.
00110  *
00111  */
00112 extern int8_t pana_server_nvm_client_session_load(uint8_t *nvm_pointer);
00113 
00114 /**
00115  * \brief PANA client NVM functionality init.
00116  *
00117  * \param passed_fptr A function pointer to NVM update process.
00118  * \param nvm_static_buffer A pointer to application allocated static memory, minimum size 88 bytes.
00119  *
00120  * Reference callback function structure using EEPROM:
00121  * - nvm_static_buffer Application allocated static buffer.
00122  *
00123  * \return 0, Init OK.
00124  * \return -1, Null parameter detect.
00125  *
00126  */
00127 extern int8_t pana_client_nvm_callback_set(void (*passed_fptr)(pana_client_nvm_update_process_t), uint8_t *nvm_static_buffer);
00128 /**
00129  * \brief Read network persistent data.
00130  *
00131  * \param data_buffer A pointer to location where the stack saves 18 bytes [NWK-ID 16bytes, Short Address 2bytes].
00132  *
00133  *
00134  * \return 0, Read OK.
00135  * \return -1, Null parameter detected.
00136  * \return -2 Bootstrap not ready yet.
00137  *
00138  * This function should call when network bootstrap is ready.
00139  *
00140  */
00141 extern int8_t net_read_persistent_data(uint8_t *data_buffer, int8_t interface_id);
00142 /**
00143  * \brief Load ZigBeeIP node persistent data to stack for re-use.
00144  *
00145  * \param data_buffer A pointer to data with 88 bytes [NWK-ID 16bytes, Short Address 2bytes, Pana 70 bytes].
00146  *
00147  *
00148  * \return 0, Read OK.
00149  * \return -1, Null parameter detected.
00150  * \return -2, Stack is active.
00151  * \return <-2 Memory allocation fail.
00152  *
00153  */
00154 extern int8_t net_nvm_data_load(uint8_t *data_buffer, int8_t interface_id);
00155 
00156 /**
00157  * \brief Load PANA client session data to the stack for re-use.
00158  *
00159  * \param data_buffer A pointer to data with encrypted PANA session 70 bytes.
00160  * \param session_address A pointer to a session-specific address. Give the address if you want to re-use the session with specific parent, otherwise give NULL.
00161  *
00162  *
00163  * \return 0, Read OK.
00164  * \return -1, Null parameter detected.
00165  * \return -2, Stack is active.
00166  * \return <-2 Memory allocation fail.
00167  *
00168  */
00169 extern int8_t net_pana_client_session_nvm_data_load(uint8_t *data_buffer, uint8_t *session_address, int8_t interface_id);
00170 /**
00171  * \brief Clean node persistent data and all PANA client sessions from the stack.
00172  *
00173  * This function disables the network ID filter, sets EUID-16 to 0xffff and removes PANA client sessions. It is only for client purposes.
00174  *
00175  *
00176  * \return 0, Clean OK.
00177  * \return -1, Stack is active.
00178  *
00179  */
00180 extern int8_t net_nvm_data_clean(int8_t interface_id);
00181 #ifdef __cplusplus
00182 }
00183 #endif
00184 #endif /* PANA_NVM_API_H_ */