| /* |
| * Copyright (c) 2023, The OpenThread Authors. |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions are met: |
| * 1. Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * 2. Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in the |
| * documentation and/or other materials provided with the distribution. |
| * 3. Neither the name of the copyright holder nor the |
| * names of its contributors may be used to endorse or promote products |
| * derived from this software without specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| * POSSIBILITY OF SUCH DAMAGE. |
| */ |
| |
| /** |
| * @file |
| * @brief |
| * This file defines the top-level functions for the OpenThread BLE Secure implementation. |
| * |
| * @note |
| * The functions in this module require the build-time feature `OPENTHREAD_CONFIG_BLE_TCAT_ENABLE=1`. |
| * |
| * @note |
| * To enable cipher suite DTLS_PSK_WITH_AES_128_CCM_8, MBEDTLS_KEY_EXCHANGE_PSK_ENABLED |
| * must be enabled in mbedtls-config.h |
| * To enable cipher suite DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8, |
| * MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED must be enabled in mbedtls-config.h. |
| */ |
| |
| #ifndef OPENTHREAD_BLE_SECURE_H_ |
| #define OPENTHREAD_BLE_SECURE_H_ |
| |
| #include <stdint.h> |
| #include <openthread/message.h> |
| #include <openthread/tcat.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @addtogroup api-ble-secure |
| * |
| * @brief |
| * This module includes functions that control BLE Secure (TLS over BLE) communication. |
| * |
| * The functions in this module are available when BLE Secure API feature |
| * (`OPENTHREAD_CONFIG_BLE_TCAT_ENABLE`) is enabled. |
| * |
| * @{ |
| * |
| */ |
| |
| /** |
| * Pointer to call when ble secure connection state changes. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aConnected TRUE, if a secure connection was established, FALSE otherwise. |
| * @param[in] aBleConnectionOpen TRUE if a BLE connection was established to carry a TLS data stream, FALSE |
| * otherwise. |
| * @param[in] aContext A pointer to arbitrary context information. |
| * |
| */ |
| typedef void (*otHandleBleSecureConnect)(otInstance *aInstance, |
| bool aConnected, |
| bool aBleConnectionOpen, |
| void *aContext); |
| |
| /** |
| * Pointer to call when data was received over a BLE Secure TLS connection. |
| * |
| */ |
| typedef otHandleTcatApplicationDataReceive otHandleBleSecureReceive; |
| |
| /** |
| * Starts the BLE Secure service. |
| * When TLV mode is active, the function @p aReceiveHandler will be called once a complete TLV was received and the |
| * message offset points to the TLV value. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aConnectHandler A pointer to a function that will be called when the connection |
| * state changes. |
| * @param[in] aReceiveHandler A pointer to a function that will be called once data has been received |
| * over the TLS connection. |
| * @param[in] aTlvMode A boolean value indicating if line mode shall be activated. |
| * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used. |
| * |
| * @retval OT_ERROR_NONE Successfully started the BLE Secure server. |
| * @retval OT_ERROR_ALREADY The service was stated already. |
| * |
| */ |
| otError otBleSecureStart(otInstance *aInstance, |
| otHandleBleSecureConnect aConnectHandler, |
| otHandleBleSecureReceive aReceiveHandler, |
| bool aTlvMode, |
| void *aContext); |
| |
| /** |
| * Enables the TCAT protocol over BLE Secure. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aVendorInfo A pointer to the Vendor Information (must remain valid after the method call, may be |
| * NULL). |
| * @param[in] aHandler A pointer to a function that is called when the join operation completes. |
| * |
| * @retval OT_ERROR_NONE Successfully started the BLE Secure Joiner role. |
| * @retval OT_ERROR_INVALID_ARGS @p aElevationPsk or @p aVendorInfo is invalid. |
| * @retval OT_ERROR_INVALID_STATE The BLE function has not been started or line mode is not selected. |
| * |
| */ |
| otError otBleSecureTcatStart(otInstance *aInstance, const otTcatVendorInfo *aVendorInfo, otHandleTcatJoin aHandler); |
| |
| /** |
| * Stops the BLE Secure server. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * |
| */ |
| void otBleSecureStop(otInstance *aInstance); |
| |
| /** |
| * Sets the Pre-Shared Key (PSK) and cipher suite |
| * TLS_PSK_WITH_AES_128_CCM_8. |
| * |
| * @note Requires the build-time feature `MBEDTLS_KEY_EXCHANGE_PSK_ENABLED` to be enabled. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aPsk A pointer to the PSK. |
| * @param[in] aPskLength The PSK length. |
| * @param[in] aPskIdentity The Identity Name for the PSK. |
| * @param[in] aPskIdLength The PSK Identity Length. |
| * |
| */ |
| void otBleSecureSetPsk(otInstance *aInstance, |
| const uint8_t *aPsk, |
| uint16_t aPskLength, |
| const uint8_t *aPskIdentity, |
| uint16_t aPskIdLength); |
| |
| /** |
| * Returns the peer x509 certificate base64 encoded. |
| * |
| * @note Requires the build-time features `MBEDTLS_BASE64_C` and |
| * `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[out] aPeerCert A pointer to the base64 encoded certificate buffer. |
| * @param[in,out] aCertLength On input, the size the max size of @p aPeerCert. |
| * On output, the length of the base64 encoded peer certificate. |
| * |
| * @retval OT_ERROR_NONE Successfully get the peer certificate. |
| * @retval OT_ERROR_INVALID_ARGS @p aInstance or @p aCertLength is invalid. |
| * @retval OT_ERROR_INVALID_STATE Not connected yet. |
| * @retval OT_ERROR_NO_BUFS Can't allocate memory for certificate. |
| * |
| */ |
| otError otBleSecureGetPeerCertificateBase64(otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength); |
| |
| /** |
| * Returns an attribute value identified by its OID from the subject |
| * of the peer x509 certificate. The peer OID is provided in binary format. |
| * The attribute length is set if the attribute was successfully read or zero |
| * if unsuccessful. The ASN.1 type as is set as defineded in the ITU-T X.690 standard |
| * if the attribute was successfully read. |
| * |
| * @note Requires the build-time feature |
| * `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aOid A pointer to the OID to be found. |
| * @param[in] aOidLength The length of the OID. |
| * @param[out] aAttributeBuffer A pointer to the attribute buffer. |
| * @param[in,out] aAttributeLength On input, the size the max size of @p aAttributeBuffer. |
| * On output, the length of the attribute written to the buffer. |
| * @param[out] aAsn1Type A pointer to the ASN.1 type of the attribute written to the buffer. |
| * |
| * @retval OT_ERROR_INVALID_STATE Not connected yet. |
| * @retval OT_ERROR_INVALID_ARGS Invalid attribute length. |
| * @retval OT_ERROR_NONE Successfully read attribute. |
| * @retval OT_ERROR_NO_BUFS Insufficient memory for storing the attribute value. |
| * |
| */ |
| otError otBleSecureGetPeerSubjectAttributeByOid(otInstance *aInstance, |
| const char *aOid, |
| size_t aOidLength, |
| uint8_t *aAttributeBuffer, |
| size_t *aAttributeLength, |
| int *aAsn1Type); |
| |
| /** |
| * Returns an attribute value for the OID 1.3.6.1.4.1.44970.x from the v3 extensions of |
| * the peer x509 certificate, where the last digit x is set to aThreadOidDescriptor. |
| * The attribute length is set if the attribute was successfully read or zero if unsuccessful. |
| * Requires a connection to be active. |
| * |
| * @note Requires the build-time feature |
| * `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aThreadOidDescriptor The last digit of the Thread attribute OID. |
| * @param[out] aAttributeBuffer A pointer to the attribute buffer. |
| * @param[in,out] aAttributeLength On input, the size the max size of @p aAttributeBuffer. |
| * On output, the length of the attribute written to the buffer. |
| * |
| * @retval OT_ERROR_NONE Successfully read attribute. |
| * @retval OT_ERROR_INVALID_ARGS Invalid attribute length. |
| * @retval OT_NOT_FOUND The requested attribute was not found. |
| * @retval OT_ERROR_NO_BUFS Insufficient memory for storing the attribute value. |
| * @retval OT_ERROR_INVALID_STATE Not connected yet. |
| * @retval OT_ERROR_NOT_IMPLEMENTED The value of aThreadOidDescriptor is >127. |
| * @retval OT_ERROR_PARSE The certificate extensions could not be parsed. |
| * |
| */ |
| otError otBleSecureGetThreadAttributeFromPeerCertificate(otInstance *aInstance, |
| int aThreadOidDescriptor, |
| uint8_t *aAttributeBuffer, |
| size_t *aAttributeLength); |
| |
| /** |
| * Returns an attribute value for the OID 1.3.6.1.4.1.44970.x from the v3 extensions of |
| * the own x509 certificate, where the last digit x is set to aThreadOidDescriptor. |
| * The attribute length is set if the attribute was successfully read or zero if unsuccessful. |
| * Requires a connection to be active. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aThreadOidDescriptor The last digit of the Thread attribute OID. |
| * @param[out] aAttributeBuffer A pointer to the attribute buffer. |
| * @param[in,out] aAttributeLength On input, the size the max size of @p aAttributeBuffer. |
| * On output, the length of the attribute written to the buffer. |
| * |
| * @retval OT_ERROR_NONE Successfully read attribute. |
| * @retval OT_ERROR_INVALID_ARGS Invalid attribute length. |
| * @retval OT_NOT_FOUND The requested attribute was not found. |
| * @retval OT_ERROR_NO_BUFS Insufficient memory for storing the attribute value. |
| * @retval OT_ERROR_INVALID_STATE Not connected yet. |
| * @retval OT_ERROR_NOT_IMPLEMENTED The value of aThreadOidDescriptor is >127. |
| * @retval OT_ERROR_PARSE The certificate extensions could not be parsed. |
| * |
| */ |
| otError otBleSecureGetThreadAttributeFromOwnCertificate(otInstance *aInstance, |
| int aThreadOidDescriptor, |
| uint8_t *aAttributeBuffer, |
| size_t *aAttributeLength); |
| |
| /** |
| * Sets the authentication mode for the BLE secure connection. |
| * |
| * Disable or enable the verification of peer certificate. |
| * Must be called before start. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aVerifyPeerCertificate true, to verify the peer certificate. |
| * |
| */ |
| void otBleSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate); |
| |
| /** |
| * Sets the local device's X509 certificate with corresponding private key for |
| * TLS session with TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8. |
| * |
| * @note Requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aX509Cert A pointer to the PEM formatted X509 certificate. |
| * @param[in] aX509Length The length of certificate. |
| * @param[in] aPrivateKey A pointer to the PEM formatted private key. |
| * @param[in] aPrivateKeyLength The length of the private key. |
| * |
| */ |
| void otBleSecureSetCertificate(otInstance *aInstance, |
| const uint8_t *aX509Cert, |
| uint32_t aX509Length, |
| const uint8_t *aPrivateKey, |
| uint32_t aPrivateKeyLength); |
| |
| /** |
| * Sets the trusted top level CAs. It is needed for validating the |
| * certificate of the peer. |
| * |
| * TLS mode "ECDHE ECDSA with AES 128 CCM 8" for secure BLE. |
| * |
| * @note Requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aX509CaCertificateChain A pointer to the PEM formatted X509 CA chain. |
| * @param[in] aX509CaCertChainLength The length of chain. |
| * |
| */ |
| void otBleSecureSetCaCertificateChain(otInstance *aInstance, |
| const uint8_t *aX509CaCertificateChain, |
| uint32_t aX509CaCertChainLength); |
| |
| /** |
| * Initializes TLS session with a peer using an already open BLE connection. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * |
| * @retval OT_ERROR_NONE Successfully started TLS connection. |
| * |
| */ |
| otError otBleSecureConnect(otInstance *aInstance); |
| |
| /** |
| * Stops the BLE and TLS connection. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * |
| */ |
| void otBleSecureDisconnect(otInstance *aInstance); |
| |
| /** |
| * Indicates whether or not the TLS session is active (connected or conneting). |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * |
| * @retval TRUE If TLS session is active. |
| * @retval FALSE If TLS session is not active. |
| * |
| */ |
| bool otBleSecureIsConnectionActive(otInstance *aInstance); |
| |
| /** |
| * Indicates whether or not the TLS session is connected. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * |
| * @retval TRUE The TLS session is connected. |
| * @retval FALSE The TLS session is not connected. |
| * |
| */ |
| bool otBleSecureIsConnected(otInstance *aInstance); |
| |
| /** |
| * Indicates whether or not the TCAT agent is enabled. |
| * |
| * @retval TRUE The TCAT agent is enabled. |
| * @retval FALSE The TCAT agent is not enabled. |
| * |
| */ |
| bool otBleSecureIsTcatEnabled(otInstance *aInstance); |
| |
| /** |
| * Indicates whether or not a TCAT command class is authorized. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aCommandClass A command class to check. |
| * |
| * @retval TRUE The command class is authorized. |
| * @retval FALSE The command class is not authorized. |
| * |
| */ |
| bool otBleSecureIsCommandClassAuthorized(otInstance *aInstance, otTcatCommandClass aCommandClass); |
| |
| /** |
| * Sends a secure BLE message. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aMessage A pointer to the message to send. |
| * |
| * If the return value is OT_ERROR_NONE, OpenThread takes ownership of @p aMessage, and the caller should no longer |
| * reference @p aMessage. If the return value is not OT_ERROR_NONE, the caller retains ownership of @p aMessage, |
| * including freeing @p aMessage if the message buffer is no longer needed. |
| * |
| * @retval OT_ERROR_NONE Successfully sent message. |
| * @retval OT_ERROR_NO_BUFS Failed to allocate buffer memory. |
| * @retval OT_ERROR_INVALID_STATE TLS connection was not initialized. |
| * |
| */ |
| otError otBleSecureSendMessage(otInstance *aInstance, otMessage *aMessage); |
| |
| /** |
| * Sends a secure BLE data packet. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aBuf A pointer to the data to send as the Value of the TCAT Send Application Data TLV. |
| * @param[in] aLength A number indicating the length of the data buffer. |
| * |
| * @retval OT_ERROR_NONE Successfully sent data. |
| * @retval OT_ERROR_NO_BUFS Failed to allocate buffer memory. |
| * @retval OT_ERROR_INVALID_STATE TLS connection was not initialized. |
| * |
| */ |
| otError otBleSecureSend(otInstance *aInstance, uint8_t *aBuf, uint16_t aLength); |
| |
| /** |
| * Sends a secure BLE data packet containing a TCAT Send Application Data TLV. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * @param[in] aBuf A pointer to the data to send as the Value of the TCAT Send Application Data TLV. |
| * @param[in] aLength A number indicating the length of the data buffer. |
| * |
| * @retval OT_ERROR_NONE Successfully sent data. |
| * @retval OT_ERROR_NO_BUFS Failed to allocate buffer memory. |
| * @retval OT_ERROR_INVALID_STATE TLS connection was not initialized. |
| * |
| */ |
| otError otBleSecureSendApplicationTlv(otInstance *aInstance, uint8_t *aBuf, uint16_t aLength); |
| |
| /** |
| * Flushes the send buffer. |
| * |
| * @param[in] aInstance A pointer to an OpenThread instance. |
| * |
| * @retval OT_ERROR_NONE Successfully flushed output buffer. |
| * @retval OT_ERROR_NO_BUFS Failed to allocate buffer memory. |
| * @retval OT_ERROR_INVALID_STATE TLS connection was not initialized. |
| * |
| */ |
| otError otBleSecureFlush(otInstance *aInstance); |
| |
| /** |
| * @} |
| * |
| */ |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif /* OPENTHREAD_BLE_SECURE_H_ */ |
