thread_meshcop_lib.h

00001 /*
00002  * Copyright (c) 2015-2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: BSD-3-Clause
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the copyright holder nor the
00014  *    names of its contributors may be used to endorse or promote products
00015  *    derived from this software without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00018  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
00021  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00022  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00023  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00026  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00027  * POSSIBILITY OF SUCH DAMAGE.
00028  */
00029 
00030 /**
00031  * \file thread_meshcop_lib.h
00032  * \brief Public API to handle the Thread management framework message parsing and building.
00033  *
00034  */
00035 
00036 #ifndef THREAD_MESHCOP_LIB_H_
00037 #define THREAD_MESHCOP_LIB_H_
00038 
00039 #include "ns_types.h"
00040 
00041 /**
00042  * TLV Types used in thread network
00043  */
00044 /**
00045  * Network configuration TLV
00046  */
00047 /** Channel TLV. */
00048 #define MESHCOP_TLV_CHANNEL                                0
00049 /** PANID TLV. */
00050 #define MESHCOP_TLV_PANID                                  1
00051 /** Extended PANID TLV. */
00052 #define MESHCOP_TLV_XPANID                                 2
00053 /** Network Name TLV. */
00054 #define MESHCOP_TLV_NETWORK_NAME                           3
00055 /** PSKc TLV. */
00056 #define MESHCOP_TLV_PSKC                                   4
00057 /** Network Master key TLV. */
00058 #define MESHCOP_TLV_NETWORK_MASTER_KEY                     5
00059 /** Network Key Sequence TLV. */
00060 #define MESHCOP_TLV_NETWORK_KEY_SEQUENCE                   6
00061 /** Mesh Local Ula prefix TLV. */
00062 #define MESHCOP_TLV_NETWORK_MESH_LOCAL_ULA                 7
00063 
00064 /**
00065  * Network management TLV
00066  */
00067 /** Steering data TLV. */
00068 #define MESHCOP_TLV_STEERING_DATA                          8
00069 /** Border router locator TLV. */
00070 #define MESHCOP_TLV_BORDER_ROUTER_LOCATOR                  9
00071 /** Commissioner ID TLV. */
00072 #define MESHCOP_TLV_COMMISSIONER_ID                        10
00073 /** Commissioner session ID TLV. */
00074 #define MESHCOP_TLV_COMMISSIONER_SESSION_ID                11
00075 /** Security Policy TLV. */
00076 #define MESHCOP_TLV_SECURITY_POLICY                        12
00077 /** GET TLV. */
00078 #define MESHCOP_TLV_GET                                    13
00079 /** Active Timestamp TLV. */
00080 #define MESHCOP_TLV_ACTIVE_TIME_STAMP                      14
00081 /** Commissioner UDP port TLV. */
00082 #define MESHCOP_TLV_COMMISSIONER_UDP_PORT                  15
00083 /** state TLV. */
00084 #define MESHCOP_TLV_STATE                                  16
00085 /** Joiner UDP port TLV. */
00086 #define MESHCOP_TLV_JOINER_UDP_PORT                        18
00087 
00088 /**
00089  * Network management TLV specific bit defines
00090  */
00091 #define MESHCOP_TLV_ACTIVE_TIME_STAMP_U_BIT                 0x01
00092 
00093 /**
00094  * Relay message TLV
00095  */
00096 /** Joiner Encapsulation TLV. */
00097 #define MESHCOP_TLV_JOINER_ENCAPSULATION                   17
00098 /** Joiner UDP port TLV. */
00099 #define MESHCOP_TLV_JOINER_UDP_PORT                        18
00100 /** Joiner IID TLV. */
00101 #define MESHCOP_TLV_JOINER_IID                             19
00102 /** Joiner Router locator TLV. */
00103 #define MESHCOP_TLV_JOINER_ROUTER_LOCATOR                  20
00104 /** Key Exchange Key TLV. */
00105 #define MESHCOP_TLV_JOINER_ROUTER_KEK                      21
00106 
00107 /**
00108  * Application provisioning TLVs
00109  */
00110 /** Provisioning URL TLV. */
00111 #define MESHCOP_TLV_PROVISIONING_URL                       32
00112 /** Vendr Name TLV. */
00113 #define MESHCOP_TLV_VENDOR_NAME                            33
00114 /** Vendor Model TLV. */
00115 #define MESHCOP_TLV_VENDOR_MODEL                           34
00116 /** Vendor SW version TLV. */
00117 #define MESHCOP_TLV_VENDOR_SW_VERSION                      35
00118 /** Vendor Data TLV. */
00119 #define MESHCOP_TLV_VENDOR_DATA                            36
00120 /** Vendor Stack Version TLV. */
00121 #define MESHCOP_TLV_VENDOR_STACK_VERSION                   37
00122 
00123 /**
00124  * Tunneling
00125  */
00126 /** UDP encapsulation TLV. */
00127 #define MESHCOP_TLV_UDP_ENCAPSULATION                      48
00128 /** IPv6 address TLV. */
00129 #define MESHCOP_TLV_IPV6_ADDRESS                           49
00130 /** TMF Forwarding Port TLV. */
00131 #define MESHCOP_TLV_TMF_FORWARDING_PORT                    50
00132 
00133 /**
00134  * Thread management interface TLVs
00135  */
00136 /** Pending Timestamp TLV. */
00137 #define MESHCOP_TLV_PENDING_TIMESTAMP                      51
00138 /** Delay timer for pending configuration TLV. */
00139 #define MESHCOP_TLV_DELAY_TIMER                            52
00140 /** Channel mask TLV. */
00141 #define MESHCOP_TLV_CHANNEL_MASK                           53
00142 /** Count TLV. */
00143 #define MESHCOP_TLV_COUNT                                  54
00144 /** Period TLV. */
00145 #define MESHCOP_TLV_PERIOD                                 55
00146 /** Duration TLV. */
00147 #define MESHCOP_TLV_DURATION                               56
00148 /** Energy List TLV. */
00149 #define MESHCOP_TLV_ENERGY_LIST                            57
00150 
00151 /** Thread 1.2 */
00152 
00153 /** Timeout TLV. */
00154 #define MESHCOP_TLV_TIMEOUT                                58
00155 
00156 /** Thread domain name TLV. */
00157 #define MESHCOP_TLV_DOMAIN_NAME                            59
00158 
00159 /** Domain prefix TLV TLV.*/
00160 #define MESHCOP_TLV_DOMAIN_PREFIX                          60
00161 
00162 /** AE Steering Data TLV. */
00163 #define MESHCOP_TLV_AE_STEERING_DATA                       61
00164 
00165 /** NMKP Steering Data TLV. */
00166 #define MESHCOP_TLV_NMKP_STEERING_DATA                     62
00167 
00168 /** Commissioner Token TLV. */
00169 #define MESHCOP_TLV_COMM_TOKEN                             63
00170 
00171 /** Commissioner Signature TLV. */
00172 #define MESHCOP_TLV_COMM_SIGNATURE                         64
00173 
00174 /** NMKP Steering Data TLV. */
00175 #define MESHCOP_TLV_AE_PORT                                65
00176 
00177 /** NMKP Steering Data TLV. */
00178 #define MESHCOP_TLV_NMKP_PORT                              66
00179 
00180 /** Registrar IPV6 address. */
00181 #define MESHCOP_TLV_REGISTRAR_IPV6_ADDRESS                 68
00182 
00183 
00184 /** Discovery Request TLV. */
00185 #define MESHCOP_TLV_DISCOVERY_REQUEST                      128
00186 /** Discovery response TLV. */
00187 #define MESHCOP_TLV_DISCOVERY_RESPONSE                     129
00188 
00189 /**
00190  * Write array TLV.
00191  *
00192  * \param ptr pointer for array where to write the TLV.
00193  * \param type Type of TLV.
00194  * \param length length of the data that is written in TLV.
00195  * \param data array for TLV value.
00196  *
00197  * \return pointer value for writing the next TLV.
00198  */
00199 uint8_t *thread_meshcop_tlv_data_write(uint8_t *ptr, const  uint8_t type, const  uint16_t length, const uint8_t *data);
00200 
00201 /**
00202  * Write header.
00203  *
00204  * \param ptr pointer for array where to write the TLV.
00205  * \param type Type of TLV.
00206  * \param length length of the data that is written in TLV.
00207  *
00208  * \return pointer value for writing the remaining bytes of network data.
00209  */
00210 uint8_t *thread_meshcop_tlv_data_write_header(uint8_t *ptr, uint8_t type, uint16_t length);
00211 
00212 /**
00213  * Write 1 byte length TLV.
00214  *
00215  * \param ptr pointer for array where to write the TLV.
00216  * \param type Type of TLV.
00217  * \param data value.
00218  *
00219  * \return pointer value for writing the next TLV.
00220  */
00221 uint8_t *thread_meshcop_tlv_data_write_uint8(uint8_t *ptr, const uint8_t type, const uint8_t data);
00222 
00223 /**
00224  * Write 2 byte length TLV.
00225  *
00226  * \param ptr pointer for array where to write the TLV.
00227  * \param type Type of TLV.
00228  * \param data value.
00229  *
00230  * \return pointer value for writing the next TLV.
00231  */
00232 uint8_t *thread_meshcop_tlv_data_write_uint16(uint8_t *ptr, const uint8_t type, const uint16_t data);
00233 
00234 /**
00235  * Write 4 byte length TLV.
00236  *
00237  * \param ptr pointer for array where to write the TLV.
00238  * \param type Type of TLV.
00239  * \param data value.
00240  *
00241  * \return pointer value for writing the next TLV.
00242  */
00243 uint8_t *thread_meshcop_tlv_data_write_uint32(uint8_t *ptr, const uint8_t type, const uint32_t data);
00244 
00245 /**
00246  * Write 8 byte length TLV.
00247  *
00248  * \param ptr pointer for array where to write the TLV.
00249  * \param type Type of TLV.
00250  * \param data value.
00251  *
00252  * \return pointer value for writing the next TLV.
00253  */
00254 uint8_t *thread_meshcop_tlv_data_write_uint64(uint8_t *ptr, const uint8_t type, const uint64_t data);
00255 
00256 /**
00257  * Check if TLV exists in the message.
00258  *
00259  * \param ptr Message buffer.
00260  * \param length Length of the message buffer to validate message.
00261  * \param type Type of TLV searched.
00262  *
00263  * \return true if TLV is found.
00264  * \return false if TLV does not exist.
00265  */
00266 bool thread_meshcop_tlv_exist(const uint8_t *ptr, const uint16_t length, const uint8_t type);
00267 
00268 /**
00269  * Find TLV from message.
00270  *
00271  * \param ptr Message buffer.
00272  * \param length Length of the message buffer to validate message.
00273  * \param type Type of TLV searched.
00274  * \param result_ptr Pointer value is given as result if length is positive. Can be NULL which only searches for the length.
00275  *
00276  * \return The length of the TLV data found
00277  * \return 0 if TLV is empty or no TLV found.
00278  * \return negative value indicates corrupted message.
00279  */
00280 uint16_t thread_meshcop_tlv_find(const uint8_t *ptr, const uint16_t length, const uint8_t type, uint8_t **result_ptr);
00281 
00282 /**
00283  * Get length of the TLV.
00284  *
00285  * \param ptr Message buffer.
00286  * \param length Length of the message buffer to validate message.
00287  *
00288  * \return The length of the TLV data found
00289  * \return 0 if TLV is empty.
00290  * \return negative value indicates corrupted message or no TLV present.
00291  */
00292 int16_t thread_meshcop_tlv_length(const uint8_t *ptr, uint16_t length);
00293 
00294 /**
00295  * Get length of the TLV including the type and length field.
00296  *
00297  * \param ptr Message buffer.
00298  * \param length Length of the message buffer to validate message.
00299  *
00300  * \return The length of the TLV data found
00301  * \return 0 if TLV is empty.
00302  * \return negative value indicates corrupted message or no TLV present.
00303  */
00304 int16_t thread_meshcop_tlv_length_required(const uint8_t *ptr, uint16_t length);
00305 
00306 /**
00307  * Go through TLV list in order.
00308  *
00309  * \param ptr Message buffer.
00310  * \param length Length of the message buffer to validate message. Length value modified to remaining value or 0 when no more TLVs present
00311  *
00312  * \return ptr to the next TLV
00313  * \return NULL if no TLV found.
00314  */
00315 const uint8_t *thread_meshcop_tlv_get_next(const uint8_t *ptr, uint16_t *length);
00316 
00317 /**
00318  * Validate that required TLVs are present in the buffer.
00319  *
00320  * \param ptr TLV message buffer.
00321  * \param length Length of the TLV message buffer.
00322  * \param required_tlv_ptr buffer where the IDs of TLVs that are must be present
00323  * \param required_tlv_len Amount of TLVs
00324  *
00325  * \return amount of TLVs present in the buffer.
00326  */
00327 bool thread_meshcop_tlv_list_present(const uint8_t *ptr, uint16_t length, const uint8_t *required_tlv_ptr, uint8_t required_tlv_len);
00328 
00329 /**
00330  * Get list of TLVS included in the buffer.
00331  *
00332  * \param ptr TLV message buffer.
00333  * \param length Length of the TLV message buffer.
00334  * \param result_ptr [OUT] buffer where the IDs of TLVs are written. can be NULL when counting amount of TLVs
00335  * \param result_len [OUT] Amount of TLVs written in buffer
00336  *
00337  * \return amount of TLVs present in the buffer.
00338  */
00339 uint16_t thread_meshcop_tlv_list_generate(const uint8_t *ptr, uint16_t length, uint8_t *result_ptr, uint16_t *result_len);
00340 
00341 /**
00342  * Remove TLV from list of TLVs.
00343  *
00344  * \param tlv_ptr pointer to TLV List buffer.
00345  * \param tlv_len Length of the TLV list buffer.
00346  * \param tlv_type TLV that is removed from the List
00347  *
00348  * \return amount of TLVs present in the buffer.
00349  */
00350 uint16_t thread_meshcop_tlv_list_remove(uint8_t *tlv_ptr, uint16_t tlv_len, uint8_t tlv_type);
00351 
00352 /**
00353  * Check if specific type is available in list of TLVs.
00354  *
00355  * \param list_ptr Pointer to TLV list buffer.
00356  * \param list_len Length of the TLV list buffer.
00357  * \param tlv_type TLV type to be find from the list
00358  *
00359  * \return true if type exists, false if type does not exist.
00360  */
00361 bool thread_meshcop_tlv_list_type_available(const uint8_t *list_ptr, uint16_t list_len, uint8_t tlv_type);
00362 
00363 /**
00364  * Find next TLV from message.
00365  *
00366  * \param tlv_ba TLV message buffer.
00367  * \param tlv_ba_length Length of the TLV message buffer.
00368  * \param tlv_id ID of the TLV to be searched.
00369  * \param found_tlv [IN] Pointer value is given as result if length is > 0. Can be NULL which only searches for the length.
00370  * \                [OUT] Pointer to previous TLV found
00371  *
00372  * \return The length of the TLV data found and found_tlv updated to point beginning of value field. 0 if TLV is not found.
00373  */
00374 uint16_t thread_meshcop_tlv_find_next(uint8_t *tlv_ba, uint16_t tlv_ba_length, uint8_t tlv_id, uint8_t **found_tlv);
00375 
00376 /**
00377  * Read 1 byte length TLV.
00378  *
00379  * \param ptr pointer TLV message array.
00380  * \param length length of TLV message array.
00381  * \param type Type of TLV.
00382  * \param data_ptr pointer to variable where the value is read.
00383  *
00384  * \return pointer length of TLV 1 if success. 0 means TLV not found or does not have any data.
00385  * \return Any other value indicates that TLV is not as expected.
00386  */
00387 uint8_t thread_meshcop_tlv_data_get_uint8(const uint8_t *ptr, const uint16_t length, const uint8_t type, uint8_t *data_ptr);
00388 
00389 /**
00390  * Read 2 byte length TLV.
00391  *
00392  * \param ptr pointer TLV message array.
00393  * \param length length of TLV message array.
00394  * \param type Type of TLV.
00395  * \param data_ptr pointer to variable where the value is read.
00396  *
00397  * \return pointer length of TLV 2 if success. 0 means TLV not found or does not have any data.
00398  * \return Any other value indicates that TLV is not as expected.
00399  */
00400 uint8_t thread_meshcop_tlv_data_get_uint16(const uint8_t *ptr, const uint16_t length, const uint8_t type, uint16_t *data_ptr);
00401 
00402 /**
00403  * Read 4 byte length TLV.
00404  *
00405  * \param ptr pointer TLV message array.
00406  * \param length length of TLV message array.
00407  * \param type Type of TLV.
00408  * \param data_ptr pointer to variable where the value is read.
00409  *
00410  * \return pointer length of TLV 4 if success. 0 means TLV not found or does not have any data.
00411  * \return Any other value indicates that TLV is not as expected.
00412  */
00413 uint8_t thread_meshcop_tlv_data_get_uint32(const uint8_t *ptr, const uint16_t length, const uint8_t type, uint32_t *data_ptr);
00414 
00415 /**
00416  * Read 8 byte length TLV.
00417  *
00418  * \param ptr pointer TLV message array.
00419  * \param length length of TLV message array.
00420  * \param type Type of TLV.
00421  * \param data_ptr pointer to variable where the value is read.
00422  *
00423  * \return pointer length of TLV 4 if success. 0 means TLV not found or does not have any data.
00424  * \return Any other value indicates that TLV is not as expected.
00425  */
00426 uint8_t thread_meshcop_tlv_data_get_uint64(const uint8_t *ptr, const uint16_t length, const uint8_t type, uint64_t *data_ptr);
00427 
00428 #endif /* THREAD_MESHCOP_LIB_H_ */