net_ws_test.h

00001 /*
00002  * Copyright (c) 2014-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 NET_WS_TEST_H_
00019 #define NET_WS_TEST_H_
00020 
00021 /* Prevent this file being inserted in public Doxygen generated file
00022  * this is not part of our external API. */
00023 #ifndef DOXYGEN
00024 
00025 /**
00026  * \file net_ws_test.h
00027  * \brief Wi-SUN Library Test API.
00028  *
00029  * \warning NOTICE! This is test API must not be used externally.
00030  *
00031  * \warning This file is not part of the version number control and can change any time.
00032  *
00033  */
00034 
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 #include "ns_types.h"
00041 
00042 /**
00043  * \brief Set Pan size.
00044  *
00045  * Pan size is reported to advertisement. Using this function
00046  * actual value can be overridden.
00047  *
00048  * Set pan_size to 0xffff to stop override
00049  *
00050  * \param interface_id               Network Interface
00051  * \param pan_size                   Pan size reported in advertisements
00052  *
00053  * \return 0                         OK
00054  * \return <0                        Failure
00055  */
00056 int ws_test_pan_size_set(int8_t interface_id, uint16_t pan_size);
00057 
00058 /**
00059  * \brief Set maximum child count.
00060  *
00061  * Maximum amount of children allowed for this device
00062  *
00063  * Values above MAC neighbor table - RPL parents - temporary entries will cause undefined behaviour
00064  *
00065  * Set child count to 0xffff to stop override
00066  *
00067  * \param interface_id               Network Interface
00068  * \param child_count                   Pan size reported in advertisements
00069  *
00070  * \return 0                         OK
00071  * \return <0                        Failure
00072  */
00073 int ws_test_max_child_count_set(int8_t interface_id, uint16_t child_count);
00074 
00075 /**
00076  * Sets Group Transient Keys.
00077  *
00078  * Sets Group Transient Keys (GTKs). Up to four GTKs can be set (GTKs from index
00079  * 0 to 3). At least one GTK must be set. GTKs provided in this function call are
00080  * compared to current GTKs on node or border router GTK storage. If GTK is new
00081  * or modified it is updated to GTK storage. If GTK is same as previous one, no
00082  * changes are made. If GTK is NULL then it is removed from GTK storage. When a
00083  * new GTK is inserted or GTK is modified, GTK lifetime is set to default. If GTKs
00084  * are set to border router after bootstrap, border router initiates GTK update
00085  * to network.
00086  *
00087  * \param interface_id Network interface ID.
00088  * \param gtk GTK array, if GTK is not set, pointer for the index shall be NULL.
00089  *
00090  * \return 0                         GTKs are set
00091  * \return <0                        GTK set has failed
00092  */
00093 int ws_test_gtk_set(int8_t interface_id, uint8_t *gtk[4]);
00094 
00095 /**
00096  * Sets index of active key.
00097  *
00098  * Sets index of active Group Transient Key (GTK) to border router. If index is
00099  * set after bootstrap, initiates dissemination of new key index to network.
00100  *
00101  * \param interface_id Network interface ID.
00102  * \param index Key index
00103  *
00104  * \return 0                         Active key index has been set
00105  * \return <0                        Active key index set has failed
00106  */
00107 int ws_test_active_key_set(int8_t interface_id, uint8_t index);
00108 
00109 /**
00110  * Sets lifetime for keys
00111  *
00112  * Sets Group Transient Key (GTK), Pairwise Master Key (PMK) and
00113  * Pairwise Transient Key (PTK) lifetimes.
00114  *
00115  * \param interface_id Network interface ID.
00116  * \param gtk_lifetime GTK lifetime in minutes or zero if value is not changed
00117  * \param pmk_lifetime PMK lifetime in minutes or zero if value is not changed
00118  * \param ptk_lifetime PTK lifetime in minutes or zero if value is not changed
00119  *
00120  * \return 0                         Lifetimes are set
00121  * \return <0                        Lifetime set has failed
00122  */
00123 int ws_test_key_lifetime_set(
00124     int8_t interface_id,
00125     uint32_t gtk_lifetime,
00126     uint32_t pmk_lifetime,
00127     uint32_t ptk_lifetime
00128 );
00129 
00130 /**
00131  * Sets time configurations for GTK keys
00132  *
00133  * Sets GTK Revocation Lifetime Reduction and GTK New Activation Time values
00134  * as parts of the GTK lifetime (e.g. value 3 is 1/3 * lifetime). Sets GTK
00135  * maximum mismatch time in minutes.
00136  *
00137  * \param interface_id Network interface ID.
00138  * \param revocat_lifetime_reduct GTK Revocation Lifetime Reduction (1 / value * GTK lifetime) or zero if value is not changed
00139  * \param new_activation_time GTK New Activation Time (1 / value * GTK lifetime) or zero if value is not changed
00140  * \param new_install_req GTK New Install Required (percent * GTK lifetime) or zero if value is not changed
00141  * \param max_mismatch GTK maximum mismatch in minutes or zero if value is not changed
00142  *
00143  * \return 0                         Lifetimes are set
00144  * \return <0                        Lifetime set has failed.
00145  */
00146 int ws_test_gtk_time_settings_set(
00147     int8_t interface_id,
00148     uint8_t revocat_lifetime_reduct,
00149     uint8_t new_activation_time,
00150     uint8_t new_install_req,
00151     uint32_t max_mismatch
00152 );
00153 
00154 /**
00155  * Sets Next Group Transient Keys used during GTK life cycle
00156  *
00157  * Sets next Group Transient Keys (GTKs) used during GTK life cycle. Up to four
00158  * GTKs can be set (GTKs from index 0 to 3). When next GTK(s) are set, border
00159  * router inserts GTKs from the next GTK list into use during GTK update
00160  * procedure.
00161  *
00162  * \param interface_id Network interface ID.
00163  * \param gtk GTK array, if GTK is not set, pointer for the index shall be NULL.
00164  *
00165  * \return 0                         GTKs are set
00166  * \return <0                        GTK set has failed
00167  */
00168 int ws_test_next_gtk_set(int8_t interface_id, uint8_t *gtk[4]);
00169 
00170 #ifdef __cplusplus
00171 }
00172 #endif
00173 
00174 #endif /* DOXYGEN */
00175 #endif /* NET_THREAD_TEST_H_ */