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 /** 71 * Represents TCAT status code. 72 * 73 */ 74 typedef enum otTcatStatusCode 75 { 76 OT_TCAT_STATUS_SUCCESS = 0, ///< Command or request was successfully processed 77 OT_TCAT_STATUS_UNSUPPORTED = 1, ///< Requested command or received TLV is not supported 78 OT_TCAT_STATUS_PARSE_ERROR = 2, ///< Request / command could not be parsed correctly 79 OT_TCAT_STATUS_VALUE_ERROR = 3, ///< The value of the transmitted TLV has an error 80 OT_TCAT_STATUS_GENERAL_ERROR = 4, ///< An error not matching any other category occurred 81 OT_TCAT_STATUS_BUSY = 5, ///< Command cannot be executed because the resource is busy 82 OT_TCAT_STATUS_UNDEFINED = 6, ///< The requested value, data or service is not defined (currently) or not present 83 OT_TCAT_STATUS_HASH_ERROR = 7, ///< The hash value presented by the commissioner was incorrect 84 OT_TCAT_STATUS_UNAUTHORIZED = 16, ///< Sender does not have sufficient authorization for the given command 85 86 } otTcatStatusCode; 87 88 /** 89 * Represents TCAT application protocol. 90 * 91 */ 92 typedef enum otTcatApplicationProtocol 93 { 94 OT_TCAT_APPLICATION_PROTOCOL_NONE = 0, ///< Message which has been sent without activating the TCAT agent 95 OT_TCAT_APPLICATION_PROTOCOL_STATUS = 1, ///< Message directed to a UDP service 96 OT_TCAT_APPLICATION_PROTOCOL_TCP = 2, ///< Message directed to a TCP service 97 98 } otTcatApplicationProtocol; 99 100 /** 101 * Represents a TCAT command class. 102 * 103 */ 104 typedef enum otTcatCommandClass 105 { 106 OT_TCAT_COMMAND_CLASS_GENERAL = 0, ///< TCAT commands related to general operations 107 OT_TCAT_COMMAND_CLASS_COMMISSIONING = 1, ///< TCAT commands related to commissioning 108 OT_TCAT_COMMAND_CLASS_EXTRACTION = 2, ///< TCAT commands related to key extraction 109 OT_TCAT_COMMAND_CLASS_DECOMMISSIONING = 3, ///< TCAT commands related to de-commissioning 110 OT_TCAT_COMMAND_CLASS_APPLICATION = 4, ///< TCAT commands related to application layer 111 112 } otTcatCommandClass; 113 114 /** 115 * This structure represents a TCAT vendor information. 116 * 117 * The content of this structure MUST persist and remain unchanged while a TCAT session is running. 118 * 119 */ 120 typedef struct otTcatVendorInfo 121 { 122 const char *mProvisioningUrl; ///< Provisioning URL path string 123 const char *mVendorName; ///< Vendor name string 124 const char *mVendorModel; ///< Vendor model string 125 const char *mVendorSwVersion; ///< Vendor software version string 126 const char *mVendorData; ///< Vendor specific data string 127 const char *mPskdString; ///< Vendor managed pre-shared key for device 128 const char *mInstallCode; ///< Vendor managed install code string 129 const char *mDeviceId; ///< Vendor managed device ID string (if NULL: device ID is set to EUI-64 in binary format) 130 131 } otTcatVendorInfo; 132 133 /** 134 * Pointer to call when application data was received over a TCAT TLS connection. 135 * 136 * @param[in] aInstance A pointer to an OpenThread instance. 137 * @param[in] aMessage A pointer to the message. 138 * @param[in] aOffset The offset where the application data begins. 139 * @param[in] aTcatApplicationProtocol The protocol type of the message received. 140 * @param[in] aServiceName The name of the service the message is direced to. 141 * @param[in] aContext A pointer to arbitrary context information. 142 * 143 */ 144 typedef void (*otHandleTcatApplicationDataReceive)(otInstance *aInstance, 145 const otMessage *aMessage, 146 int32_t aOffset, 147 otTcatApplicationProtocol aTcatApplicationProtocol, 148 const char *aServiceName, 149 void *aContext); 150 151 /** 152 * Pointer to call to notify the completion of a join operation. 153 * 154 * @param[in] aError OT_ERROR_NONE if the join process succeeded. 155 * OT_ERROR_SECURITY if the join process failed due to security credentials. 156 * @param[in] aContext A pointer to arbitrary context information. 157 * 158 */ 159 typedef void (*otHandleTcatJoin)(otError aError, void *aContext); 160 161 /** 162 * @} 163 * 164 */ 165 166 #ifdef __cplusplus 167 } // extern "C" 168 #endif 169 170 #endif /* OPENTHREAD_TCAT_H_ */ 171
