1 /* 2 * Copyright (c) 2023, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the top-level functions for the OpenThread TCAT. 33 * 34 * @note 35 * The functions in this module require the build-time feature `OPENTHREAD_CONFIG_BLE_TCAT_ENABLE=1`. 36 * 37 * @note 38 * To enable cipher suite DTLS_PSK_WITH_AES_128_CCM_8, MBEDTLS_KEY_EXCHANGE_PSK_ENABLED 39 * must be enabled in mbedtls-config.h 40 * To enable cipher suite DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8, 41 * MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED must be enabled in mbedtls-config.h. 42 */ 43 44 #ifndef OPENTHREAD_TCAT_H_ 45 #define OPENTHREAD_TCAT_H_ 46 47 #include <stdint.h> 48 #include <openthread/message.h> 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @addtogroup api-ble-secure 56 * 57 * @brief 58 * This module includes functions that implement TCAT communication. 59 * 60 * The functions in this module are available when TCAT feature 61 * (`OPENTHREAD_CONFIG_BLE_TCAT_ENABLE`) is enabled. 62 * 63 * @{ 64 * 65 */ 66 67 #define OT_TCAT_MAX_SERVICE_NAME_LENGTH \ 68 15 ///< Maximum string length of a UDP or TCP service name (does not include null char). 69 70 #define OT_TCAT_ADVERTISEMENT_MAX_LEN 29 ///< Maximum length of TCAT advertisement. 71 #define OT_TCAT_OPCODE 0x2 ///< TCAT Advertisement Operation Code. 72 #define OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE 5 ///< TCAT max size of any type of advertised Device ID. 73 #define OT_TCAT_MAX_DEVICEID_SIZE 64 ///< TCAT max size of device ID. 74 75 /** 76 * Represents TCAT status code. 77 * 78 */ 79 typedef enum otTcatStatusCode 80 { 81 OT_TCAT_STATUS_SUCCESS = 0, ///< Command or request was successfully processed 82 OT_TCAT_STATUS_UNSUPPORTED = 1, ///< Requested command or received TLV is not supported 83 OT_TCAT_STATUS_PARSE_ERROR = 2, ///< Request / command could not be parsed correctly 84 OT_TCAT_STATUS_VALUE_ERROR = 3, ///< The value of the transmitted TLV has an error 85 OT_TCAT_STATUS_GENERAL_ERROR = 4, ///< An error not matching any other category occurred 86 OT_TCAT_STATUS_BUSY = 5, ///< Command cannot be executed because the resource is busy 87 OT_TCAT_STATUS_UNDEFINED = 6, ///< The requested value, data or service is not defined (currently) or not present 88 OT_TCAT_STATUS_HASH_ERROR = 7, ///< The hash value presented by the commissioner was incorrect 89 OT_TCAT_STATUS_UNAUTHORIZED = 16, ///< Sender does not have sufficient authorization for the given command 90 91 } otTcatStatusCode; 92 93 /** 94 * Represents TCAT application protocol. 95 * 96 */ 97 typedef enum otTcatApplicationProtocol 98 { 99 OT_TCAT_APPLICATION_PROTOCOL_NONE = 0, ///< Message which has been sent without activating the TCAT agent 100 OT_TCAT_APPLICATION_PROTOCOL_STATUS = 1, ///< Message directed to a UDP service 101 OT_TCAT_APPLICATION_PROTOCOL_TCP = 2, ///< Message directed to a TCP service 102 103 } otTcatApplicationProtocol; 104 105 /** 106 * Represents a TCAT command class. 107 * 108 */ 109 typedef enum otTcatCommandClass 110 { 111 OT_TCAT_COMMAND_CLASS_GENERAL = 0, ///< TCAT commands related to general operations 112 OT_TCAT_COMMAND_CLASS_COMMISSIONING = 1, ///< TCAT commands related to commissioning 113 OT_TCAT_COMMAND_CLASS_EXTRACTION = 2, ///< TCAT commands related to key extraction 114 OT_TCAT_COMMAND_CLASS_DECOMMISSIONING = 3, ///< TCAT commands related to de-commissioning 115 OT_TCAT_COMMAND_CLASS_APPLICATION = 4, ///< TCAT commands related to application layer 116 117 } otTcatCommandClass; 118 119 /** 120 * Represents Advertised Device ID type. (used during TCAT advertisement) 121 * 122 */ 123 typedef enum otTcatAdvertisedDeviceIdType 124 { 125 OT_TCAT_DEVICE_ID_EMPTY = 0, ///< Vendor device ID type not set 126 OT_TCAT_DEVICE_ID_OUI24 = 1, ///< Vendor device ID type IEEE OUI-24 127 OT_TCAT_DEVICE_ID_OUI36 = 2, ///< Vendor device ID type IEEE OUI-36 128 OT_TCAT_DEVICE_ID_DISCRIMINATOR = 3, ///< Vendor device ID type Device Discriminator 129 OT_TCAT_DEVICE_ID_IANAPEN = 4, ///< Vendor device ID type IANA PEN 130 OT_TCAT_DEVICE_ID_MAX = 5, ///< Vendor device ID type size 131 } otTcatAdvertisedDeviceIdType; 132 133 typedef struct otTcatAdvertisedDeviceId 134 { 135 otTcatAdvertisedDeviceIdType mDeviceIdType; 136 uint16_t mDeviceIdLen; 137 uint8_t mDeviceId[OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE]; 138 } otTcatAdvertisedDeviceId; 139 140 /** 141 * Represents General Device ID type. 142 * 143 */ 144 typedef struct otTcatGeneralDeviceId 145 { 146 uint16_t mDeviceIdLen; 147 uint8_t mDeviceId[OT_TCAT_MAX_DEVICEID_SIZE]; 148 } otTcatGeneralDeviceId; 149 150 /** 151 * This structure represents a TCAT vendor information. 152 * 153 * The content of this structure MUST persist and remain unchanged while a TCAT session is running. 154 * 155 */ 156 typedef struct otTcatVendorInfo 157 { 158 const char *mProvisioningUrl; ///< Provisioning URL path string 159 const char *mVendorName; ///< Vendor name string 160 const char *mVendorModel; ///< Vendor model string 161 const char *mVendorSwVersion; ///< Vendor software version string 162 const char *mVendorData; ///< Vendor specific data string 163 const char *mPskdString; ///< Vendor managed pre-shared key for device 164 const char *mInstallCode; ///< Vendor managed install code string 165 const otTcatAdvertisedDeviceId *mAdvertisedDeviceIds; /** Vendor managed advertised device ID array. 166 Array is terminated like C string with OT_TCAT_DEVICE_ID_EMPTY */ 167 const otTcatGeneralDeviceId *mGeneralDeviceId; /** Vendor managed general device ID array. 168 (if NULL: device ID is set to EUI-64 in binary format)*/ 169 170 } otTcatVendorInfo; 171 172 /** 173 * Pointer to call when application data was received over a TCAT TLS connection. 174 * 175 * @param[in] aInstance A pointer to an OpenThread instance. 176 * @param[in] aMessage A pointer to the message. 177 * @param[in] aOffset The offset where the application data begins. 178 * @param[in] aTcatApplicationProtocol The protocol type of the message received. 179 * @param[in] aServiceName The name of the service the message is direced to. 180 * @param[in] aContext A pointer to arbitrary context information. 181 * 182 */ 183 typedef void (*otHandleTcatApplicationDataReceive)(otInstance *aInstance, 184 const otMessage *aMessage, 185 int32_t aOffset, 186 otTcatApplicationProtocol aTcatApplicationProtocol, 187 const char *aServiceName, 188 void *aContext); 189 190 /** 191 * Pointer to call to notify the completion of a join operation. 192 * 193 * @param[in] aError OT_ERROR_NONE if the join process succeeded. 194 * OT_ERROR_SECURITY if the join process failed due to security credentials. 195 * @param[in] aContext A pointer to arbitrary context information. 196 * 197 */ 198 typedef void (*otHandleTcatJoin)(otError aError, void *aContext); 199 200 /** 201 * @} 202 * 203 */ 204 205 #ifdef __cplusplus 206 } // extern "C" 207 #endif 208 209 #endif /* OPENTHREAD_TCAT_H_ */ 210
