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 #define OT_TCAT_MAX_SERVICE_NAME_LENGTH \ 67 15 ///< Maximum string length of a UDP or TCP service name (does not include null char). 68 69 #define OT_TCAT_ADVERTISEMENT_MAX_LEN 29 ///< Maximum length of TCAT advertisement. 70 #define OT_TCAT_OPCODE 0x2 ///< TCAT Advertisement Operation Code. 71 #define OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE 5 ///< TCAT max size of any type of advertised Device ID. 72 #define OT_TCAT_MAX_DEVICEID_SIZE 64 ///< TCAT max size of device ID. 73 74 /** 75 * Represents TCAT status code. 76 */ 77 typedef enum otTcatStatusCode 78 { 79 OT_TCAT_STATUS_SUCCESS = 0, ///< Command or request was successfully processed 80 OT_TCAT_STATUS_UNSUPPORTED = 1, ///< Requested command or received TLV is not supported 81 OT_TCAT_STATUS_PARSE_ERROR = 2, ///< Request / command could not be parsed correctly 82 OT_TCAT_STATUS_VALUE_ERROR = 3, ///< The value of the transmitted TLV has an error 83 OT_TCAT_STATUS_GENERAL_ERROR = 4, ///< An error not matching any other category occurred 84 OT_TCAT_STATUS_BUSY = 5, ///< Command cannot be executed because the resource is busy 85 OT_TCAT_STATUS_UNDEFINED = 6, ///< The requested value, data or service is not defined (currently) or not present 86 OT_TCAT_STATUS_HASH_ERROR = 7, ///< The hash value presented by the commissioner was incorrect 87 OT_TCAT_STATUS_UNAUTHORIZED = 16, ///< Sender does not have sufficient authorization for the given command 88 89 } otTcatStatusCode; 90 91 /** 92 * Represents TCAT application protocol. 93 */ 94 typedef enum otTcatApplicationProtocol 95 { 96 OT_TCAT_APPLICATION_PROTOCOL_NONE = 0, ///< Message which has been sent without activating the TCAT agent 97 OT_TCAT_APPLICATION_PROTOCOL_STATUS = 1, ///< Message directed to a UDP service 98 OT_TCAT_APPLICATION_PROTOCOL_TCP = 2, ///< Message directed to a TCP service 99 100 } otTcatApplicationProtocol; 101 102 /** 103 * Represents a TCAT command class. 104 */ 105 typedef enum otTcatCommandClass 106 { 107 OT_TCAT_COMMAND_CLASS_GENERAL = 0, ///< TCAT commands related to general operations 108 OT_TCAT_COMMAND_CLASS_COMMISSIONING = 1, ///< TCAT commands related to commissioning 109 OT_TCAT_COMMAND_CLASS_EXTRACTION = 2, ///< TCAT commands related to key extraction 110 OT_TCAT_COMMAND_CLASS_DECOMMISSIONING = 3, ///< TCAT commands related to de-commissioning 111 OT_TCAT_COMMAND_CLASS_APPLICATION = 4, ///< TCAT commands related to application layer 112 113 } otTcatCommandClass; 114 115 /** 116 * Represents Advertised Device ID type. (used during TCAT advertisement) 117 */ 118 typedef enum otTcatAdvertisedDeviceIdType 119 { 120 OT_TCAT_DEVICE_ID_EMPTY = 0, ///< Vendor device ID type not set 121 OT_TCAT_DEVICE_ID_OUI24 = 1, ///< Vendor device ID type IEEE OUI-24 122 OT_TCAT_DEVICE_ID_OUI36 = 2, ///< Vendor device ID type IEEE OUI-36 123 OT_TCAT_DEVICE_ID_DISCRIMINATOR = 3, ///< Vendor device ID type Device Discriminator 124 OT_TCAT_DEVICE_ID_IANAPEN = 4, ///< Vendor device ID type IANA PEN 125 OT_TCAT_DEVICE_ID_MAX = 5, ///< Vendor device ID type size 126 } otTcatAdvertisedDeviceIdType; 127 128 typedef struct otTcatAdvertisedDeviceId 129 { 130 otTcatAdvertisedDeviceIdType mDeviceIdType; 131 uint16_t mDeviceIdLen; 132 uint8_t mDeviceId[OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE]; 133 } otTcatAdvertisedDeviceId; 134 135 /** 136 * Represents General Device ID type. 137 */ 138 typedef struct otTcatGeneralDeviceId 139 { 140 uint16_t mDeviceIdLen; 141 uint8_t mDeviceId[OT_TCAT_MAX_DEVICEID_SIZE]; 142 } otTcatGeneralDeviceId; 143 144 /** 145 * This structure represents a TCAT vendor information. 146 * 147 * The content of this structure MUST persist and remain unchanged while a TCAT session is running. 148 */ 149 typedef struct otTcatVendorInfo 150 { 151 const char *mProvisioningUrl; ///< Provisioning URL path string 152 const char *mVendorName; ///< Vendor name string 153 const char *mVendorModel; ///< Vendor model string 154 const char *mVendorSwVersion; ///< Vendor software version string 155 const char *mVendorData; ///< Vendor specific data string 156 const char *mPskdString; ///< Vendor managed pre-shared key for device 157 const char *mInstallCode; ///< Vendor managed install code string 158 const otTcatAdvertisedDeviceId *mAdvertisedDeviceIds; /** Vendor managed advertised device ID array. 159 Array is terminated like C string with OT_TCAT_DEVICE_ID_EMPTY */ 160 const otTcatGeneralDeviceId *mGeneralDeviceId; /** Vendor managed general device ID array. 161 (if NULL: device ID is set to EUI-64 in binary format)*/ 162 163 } otTcatVendorInfo; 164 165 /** 166 * Pointer to call when application data was received over a TCAT TLS connection. 167 * 168 * @param[in] aInstance A pointer to an OpenThread instance. 169 * @param[in] aMessage A pointer to the message. 170 * @param[in] aOffset The offset where the application data begins. 171 * @param[in] aTcatApplicationProtocol The protocol type of the message received. 172 * @param[in] aServiceName The name of the service the message is direced to. 173 * @param[in] aContext A pointer to arbitrary context information. 174 */ 175 typedef void (*otHandleTcatApplicationDataReceive)(otInstance *aInstance, 176 const otMessage *aMessage, 177 int32_t aOffset, 178 otTcatApplicationProtocol aTcatApplicationProtocol, 179 const char *aServiceName, 180 void *aContext); 181 182 /** 183 * Pointer to call to notify the completion of a join operation. 184 * 185 * @param[in] aError OT_ERROR_NONE if the join process succeeded. 186 * OT_ERROR_SECURITY if the join process failed due to security credentials. 187 * @param[in] aContext A pointer to arbitrary context information. 188 */ 189 typedef void (*otHandleTcatJoin)(otError aError, void *aContext); 190 191 /** 192 * @} 193 */ 194 195 #ifdef __cplusplus 196 } // extern "C" 197 #endif 198 199 #endif /* OPENTHREAD_TCAT_H_ */ 200