BLE Secure#
This module includes functions that control BLE Secure (TLS over BLE) communication.
This module includes functions that implement TCAT communication.
The functions in this module are available when BLE Secure API feature (OPENTHREAD_CONFIG_BLE_TCAT_ENABLE
) is enabled.
The functions in this module are available when TCAT feature (OPENTHREAD_CONFIG_BLE_TCAT_ENABLE
) is enabled.
Modules#
Enumerations#
Represents TCAT status code.
Represents TCAT application protocol.
Represents a TCAT command class.
Represents Advertised Device ID type.
Typedefs#
Pointer to call when ble secure connection state changes.
Pointer to call when data was received over a BLE Secure TLS connection.
Represents TCAT status code.
Represents TCAT application protocol.
Represents a TCAT command class.
Represents Advertised Device ID type.
Represents General Device ID type.
This structure represents a TCAT vendor information.
Pointer to call when application data was received over a TCAT TLS connection.
Pointer to call to notify the completion of a join operation.
Functions#
Starts the BLE Secure service.
Sets TCAT vendor info.
Enables the TCAT protocol over BLE Secure.
Stops the BLE Secure server.
Sets the Pre-Shared Key (PSK) and cipher suite TLS_PSK_WITH_AES_128_CCM_8.
Returns the peer x509 certificate base64 encoded.
Returns an attribute value identified by its OID from the subject of the peer x509 certificate.
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.
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.
Sets the authentication mode for the BLE secure connection.
Sets the local device's X509 certificate with corresponding private key for TLS session with TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8.
Sets the trusted top level CAs.
Initializes TLS session with a peer using an already open BLE connection.
Stops the BLE and TLS connection.
Indicates whether or not the TLS session is active (connected or connecting).
Indicates whether or not the TLS session is connected.
Indicates whether or not the TCAT agent is enabled.
Indicates whether or not a TCAT command class is authorized.
Sends a secure BLE message.
Sends a secure BLE data packet.
Sends a secure BLE data packet containing a TCAT Send Application Data TLV.
Flushes the send buffer.
Gets the Install Code Verify Status during the current session.
Macros#
Maximum string length of a UDP or TCP service name (does not include null char).
Maximum length of TCAT advertisement.
TCAT Advertisement Operation Code.
TCAT max size of any type of advertised Device ID.
TCAT max size of device ID.
Enumeration Documentation#
otTcatStatusCode#
otTcatStatusCode
Represents TCAT status code.
Enumerator | |
---|---|
OT_TCAT_STATUS_SUCCESS | Command or request was successfully processed. |
OT_TCAT_STATUS_UNSUPPORTED | Requested command or received TLV is not supported. |
OT_TCAT_STATUS_PARSE_ERROR | Request / command could not be parsed correctly. |
OT_TCAT_STATUS_VALUE_ERROR | The value of the transmitted TLV has an error. |
OT_TCAT_STATUS_GENERAL_ERROR | An error not matching any other category occurred. |
OT_TCAT_STATUS_BUSY | Command cannot be executed because the resource is busy. |
OT_TCAT_STATUS_UNDEFINED | The requested value, data or service is not defined (currently) or not present. |
OT_TCAT_STATUS_HASH_ERROR | The hash value presented by the commissioner was incorrect. |
OT_TCAT_STATUS_UNAUTHORIZED | Sender does not have sufficient authorization for the given command. |
77
of file include/openthread/tcat.h
otTcatApplicationProtocol#
otTcatApplicationProtocol
Represents TCAT application protocol.
Enumerator | |
---|---|
OT_TCAT_APPLICATION_PROTOCOL_NONE | Message which has been sent without activating the TCAT agent. |
OT_TCAT_APPLICATION_PROTOCOL_STATUS | Message directed to a UDP service. |
OT_TCAT_APPLICATION_PROTOCOL_TCP | Message directed to a TCP service. |
94
of file include/openthread/tcat.h
otTcatCommandClass#
otTcatCommandClass
Represents a TCAT command class.
Enumerator | |
---|---|
OT_TCAT_COMMAND_CLASS_GENERAL | TCAT commands related to general operations. |
OT_TCAT_COMMAND_CLASS_COMMISSIONING | TCAT commands related to commissioning. |
OT_TCAT_COMMAND_CLASS_EXTRACTION | TCAT commands related to key extraction. |
OT_TCAT_COMMAND_CLASS_DECOMMISSIONING | TCAT commands related to de-commissioning. |
OT_TCAT_COMMAND_CLASS_APPLICATION | TCAT commands related to application layer. |
105
of file include/openthread/tcat.h
otTcatAdvertisedDeviceIdType#
otTcatAdvertisedDeviceIdType
Represents Advertised Device ID type.
(used during TCAT advertisement)
Enumerator | |
---|---|
OT_TCAT_DEVICE_ID_EMPTY | Vendor device ID type not set. |
OT_TCAT_DEVICE_ID_OUI24 | Vendor device ID type IEEE OUI-24. |
OT_TCAT_DEVICE_ID_OUI36 | Vendor device ID type IEEE OUI-36. |
OT_TCAT_DEVICE_ID_DISCRIMINATOR | Vendor device ID type Device Discriminator. |
OT_TCAT_DEVICE_ID_IANAPEN | Vendor device ID type IANA PEN. |
OT_TCAT_DEVICE_ID_MAX | Vendor device ID type size. |
118
of file include/openthread/tcat.h
Typedef Documentation#
otHandleBleSecureConnect#
typedef void(* otHandleBleSecureConnect) (otInstance *aInstance, bool aConnected, bool aBleConnectionOpen, void *aContext) )(otInstance *aInstance, bool aConnected, bool aBleConnectionOpen, void *aContext)
Pointer to call when ble secure connection state changes.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aConnected | TRUE, if a secure connection was established, FALSE otherwise. |
[in] | aBleConnectionOpen | TRUE if a BLE connection was established to carry a TLS data stream, FALSE otherwise. |
[in] | aContext | A pointer to arbitrary context information. |
76
of file include/openthread/ble_secure.h
otHandleBleSecureReceive#
typedef otHandleTcatApplicationDataReceive otHandleBleSecureReceive
Pointer to call when data was received over a BLE Secure TLS connection.
84
of file include/openthread/ble_secure.h
otTcatStatusCode#
typedef enum otTcatStatusCode otTcatStatusCode
Represents TCAT status code.
89
of file include/openthread/tcat.h
otTcatApplicationProtocol#
typedef enum otTcatApplicationProtocol otTcatApplicationProtocol
Represents TCAT application protocol.
100
of file include/openthread/tcat.h
otTcatCommandClass#
typedef enum otTcatCommandClass otTcatCommandClass
Represents a TCAT command class.
113
of file include/openthread/tcat.h
otTcatAdvertisedDeviceIdType#
typedef enum otTcatAdvertisedDeviceIdType otTcatAdvertisedDeviceIdType
Represents Advertised Device ID type.
(used during TCAT advertisement)
126
of file include/openthread/tcat.h
otTcatAdvertisedDeviceId#
typedef struct otTcatAdvertisedDeviceId otTcatAdvertisedDeviceId
133
of file include/openthread/tcat.h
otTcatGeneralDeviceId#
typedef struct otTcatGeneralDeviceId otTcatGeneralDeviceId
Represents General Device ID type.
142
of file include/openthread/tcat.h
otTcatVendorInfo#
typedef struct otTcatVendorInfo otTcatVendorInfo
This structure represents a TCAT vendor information.
The content of this structure MUST persist and remain unchanged while a TCAT session is running.
163
of file include/openthread/tcat.h
otHandleTcatApplicationDataReceive#
typedef void(* otHandleTcatApplicationDataReceive) (otInstance *aInstance, const otMessage *aMessage, int32_t aOffset, otTcatApplicationProtocol aTcatApplicationProtocol, const char *aServiceName, void *aContext) )(otInstance *aInstance, const otMessage *aMessage, int32_t aOffset, otTcatApplicationProtocol aTcatApplicationProtocol, const char *aServiceName, void *aContext)
Pointer to call when application data was received over a TCAT TLS connection.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aMessage | A pointer to the message. |
[in] | aOffset | The offset where the application data begins. |
[in] | aTcatApplicationProtocol | The protocol type of the message received. |
[in] | aServiceName | The name of the service the message is direced to. |
[in] | aContext | A pointer to arbitrary context information. |
175
of file include/openthread/tcat.h
otHandleTcatJoin#
typedef void(* otHandleTcatJoin) (otError aError, void *aContext) )(otError aError, void *aContext)
Pointer to call to notify the completion of a join operation.
[in] | aError | OT_ERROR_NONE if the join process succeeded. OT_ERROR_SECURITY if the join process failed due to security credentials. |
[in] | aContext | A pointer to arbitrary context information. |
189
of file include/openthread/tcat.h
Function Documentation#
otBleSecureStart#
otError otBleSecureStart (otInstance * aInstance, otHandleBleSecureConnect aConnectHandler, otHandleBleSecureReceive aReceiveHandler, bool aTlvMode, void * aContext)
Starts the BLE Secure service.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aConnectHandler | A pointer to a function that will be called when the connection state changes. |
[in] | aReceiveHandler | A pointer to a function that will be called once data has been received over the TLS connection. |
[in] | aTlvMode | A boolean value indicating if line mode shall be activated. |
[in] | aContext | A pointer to arbitrary context information. May be NULL if not used. |
When TLV mode is active, the function aReceiveHandler
will be called once a complete TLV was received and the message offset points to the TLV value.
102
of file include/openthread/ble_secure.h
otBleSecureSetTcatVendorInfo#
otError otBleSecureSetTcatVendorInfo (otInstance * aInstance, const otTcatVendorInfo * aVendorInfo)
Sets TCAT vendor info.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aVendorInfo | A pointer to the Vendor Information (must remain valid after the method call. |
117
of file include/openthread/ble_secure.h
otBleSecureTcatStart#
otError otBleSecureTcatStart (otInstance * aInstance, otHandleTcatJoin aHandler)
Enables the TCAT protocol over BLE Secure.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aHandler | A pointer to a function that is called when the join operation completes. |
129
of file include/openthread/ble_secure.h
otBleSecureStop#
void otBleSecureStop (otInstance * aInstance)
Stops the BLE Secure server.
[in] | aInstance | A pointer to an OpenThread instance. |
136
of file include/openthread/ble_secure.h
otBleSecureSetPsk#
void otBleSecureSetPsk (otInstance * aInstance, const uint8_t * aPsk, uint16_t aPskLength, const uint8_t * aPskIdentity, uint16_t aPskIdLength)
Sets the Pre-Shared Key (PSK) and cipher suite TLS_PSK_WITH_AES_128_CCM_8.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aPsk | A pointer to the PSK. |
[in] | aPskLength | The PSK length. |
[in] | aPskIdentity | The Identity Name for the PSK. |
[in] | aPskIdLength | The PSK Identity Length. |
Note
Requires the build-time feature
MBEDTLS_KEY_EXCHANGE_PSK_ENABLED
to be enabled.
150
of file include/openthread/ble_secure.h
otBleSecureGetPeerCertificateBase64#
otError otBleSecureGetPeerCertificateBase64 (otInstance * aInstance, unsigned char * aPeerCert, size_t * aCertLength)
Returns the peer x509 certificate base64 encoded.
[in] | aInstance | A pointer to an OpenThread instance. |
[out] | aPeerCert | A pointer to the base64 encoded certificate buffer. |
[inout] | aCertLength | On input, the size the max size of |
Note
Requires the build-time features
MBEDTLS_BASE64_C
andMBEDTLS_SSL_KEEP_PEER_CERTIFICATE
to be enabled.
172
of file include/openthread/ble_secure.h
otBleSecureGetPeerSubjectAttributeByOid#
otError otBleSecureGetPeerSubjectAttributeByOid (otInstance * aInstance, const char * aOid, size_t aOidLength, uint8_t * aAttributeBuffer, size_t * aAttributeLength, int * aAsn1Type)
Returns an attribute value identified by its OID from the subject of the peer x509 certificate.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aOid | A pointer to the OID to be found. |
[in] | aOidLength | The length of the OID. |
[out] | aAttributeBuffer | A pointer to the attribute buffer. |
[inout] | aAttributeLength | On input, the size the max size of |
[out] | aAsn1Type | A pointer to the ASN.1 type of the attribute written to the buffer. |
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.
197
of file include/openthread/ble_secure.h
otBleSecureGetThreadAttributeFromPeerCertificate#
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 peer x509 certificate, where the last digit x is set to aThreadOidDescriptor.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aThreadOidDescriptor | The last digit of the Thread attribute OID. |
[out] | aAttributeBuffer | A pointer to the attribute buffer. |
[inout] | aAttributeLength | On input, the size the max size of |
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.
227
of file include/openthread/ble_secure.h
otBleSecureGetThreadAttributeFromOwnCertificate#
otError otBleSecureGetThreadAttributeFromOwnCertificate (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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aThreadOidDescriptor | The last digit of the Thread attribute OID. |
[out] | aAttributeBuffer | A pointer to the attribute buffer. |
[inout] | aAttributeLength | On input, the size the max size of |
The attribute length is set if the attribute was successfully read or zero if unsuccessful. Requires a connection to be active.
252
of file include/openthread/ble_secure.h
otBleSecureSetSslAuthMode#
void otBleSecureSetSslAuthMode (otInstance * aInstance, bool aVerifyPeerCertificate)
Sets the authentication mode for the BLE secure connection.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aVerifyPeerCertificate | true, to verify the peer certificate. |
Disable or enable the verification of peer certificate. Must be called before start.
266
of file include/openthread/ble_secure.h
otBleSecureSetCertificate#
void otBleSecureSetCertificate (otInstance * aInstance, const uint8_t * aX509Cert, uint32_t aX509Length, const uint8_t * aPrivateKey, uint32_t aPrivateKeyLength)
Sets the local device's X509 certificate with corresponding private key for TLS session with TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aX509Cert | A pointer to the PEM formatted X509 certificate. |
[in] | aX509Length | The length of certificate. |
[in] | aPrivateKey | A pointer to the PEM formatted private key. |
[in] | aPrivateKeyLength | The length of the private key. |
Note
Requires
MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1
.
280
of file include/openthread/ble_secure.h
otBleSecureSetCaCertificateChain#
void otBleSecureSetCaCertificateChain (otInstance * aInstance, const uint8_t * aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
Sets the trusted top level CAs.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aX509CaCertificateChain | A pointer to the PEM formatted X509 CA chain. |
[in] | aX509CaCertChainLength | The length of chain. |
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
.
298
of file include/openthread/ble_secure.h
otBleSecureConnect#
otError otBleSecureConnect (otInstance * aInstance)
Initializes TLS session with a peer using an already open BLE connection.
[in] | aInstance | A pointer to an OpenThread instance. |
309
of file include/openthread/ble_secure.h
otBleSecureDisconnect#
void otBleSecureDisconnect (otInstance * aInstance)
Stops the BLE and TLS connection.
[in] | aInstance | A pointer to an OpenThread instance. |
316
of file include/openthread/ble_secure.h
otBleSecureIsConnectionActive#
bool otBleSecureIsConnectionActive (otInstance * aInstance)
Indicates whether or not the TLS session is active (connected or connecting).
[in] | aInstance | A pointer to an OpenThread instance. |
326
of file include/openthread/ble_secure.h
otBleSecureIsConnected#
bool otBleSecureIsConnected (otInstance * aInstance)
Indicates whether or not the TLS session is connected.
[in] | aInstance | A pointer to an OpenThread instance. |
336
of file include/openthread/ble_secure.h
otBleSecureIsTcatEnabled#
bool otBleSecureIsTcatEnabled (otInstance * aInstance)
Indicates whether or not the TCAT agent is enabled.
N/A | aInstance |
344
of file include/openthread/ble_secure.h
otBleSecureIsCommandClassAuthorized
bool otBleSecureIsCommandClassAuthorized (otInstance * aInstance, otTcatCommandClass aCommandClass)
Indicates whether or not a TCAT command class is authorized.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aCommandClass | A command class to check. |
355
of file include/openthread/ble_secure.h
otBleSecureSendMessage#
otError otBleSecureSendMessage (otInstance * aInstance, otMessage * aMessage)
Sends a secure BLE message.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aMessage | A pointer to the message to send. |
If the return value is OT_ERROR_NONE, OpenThread takes ownership of aMessage
, and the caller should no longer reference aMessage
. If the return value is not OT_ERROR_NONE, the caller retains ownership of aMessage
, including freeing aMessage
if the message buffer is no longer needed.
371
of file include/openthread/ble_secure.h
otBleSecureSend#
otError otBleSecureSend (otInstance * aInstance, uint8_t * aBuf, uint16_t aLength)
Sends a secure BLE data packet.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aBuf | A pointer to the data to send as the Value of the TCAT Send Application Data TLV. |
[in] | aLength | A number indicating the length of the data buffer. |
384
of file include/openthread/ble_secure.h
otBleSecureSendApplicationTlv#
otError otBleSecureSendApplicationTlv (otInstance * aInstance, uint8_t * aBuf, uint16_t aLength)
Sends a secure BLE data packet containing a TCAT Send Application Data TLV.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aBuf | A pointer to the data to send as the Value of the TCAT Send Application Data TLV. |
[in] | aLength | A number indicating the length of the data buffer. |
397
of file include/openthread/ble_secure.h
otBleSecureFlush#
otError otBleSecureFlush (otInstance * aInstance)
Flushes the send buffer.
[in] | aInstance | A pointer to an OpenThread instance. |
408
of file include/openthread/ble_secure.h
otBleSecureGetInstallCodeVerifyStatus#
bool otBleSecureGetInstallCodeVerifyStatus (otInstance * aInstance)
Gets the Install Code Verify Status during the current session.
[in] | aInstance | A pointer to an OpenThread instance. |
418
of file include/openthread/ble_secure.h
Macro Definition Documentation#
OT_TCAT_MAX_SERVICE_NAME_LENGTH#
#define OT_TCAT_MAX_SERVICE_NAME_LENGTHValue:
15
Maximum string length of a UDP or TCP service name (does not include null char).
66
of file include/openthread/tcat.h
OT_TCAT_ADVERTISEMENT_MAX_LEN#
#define OT_TCAT_ADVERTISEMENT_MAX_LENValue:
29
Maximum length of TCAT advertisement.
69
of file include/openthread/tcat.h
OT_TCAT_OPCODE#
#define OT_TCAT_OPCODEValue:
0x2
TCAT Advertisement Operation Code.
70
of file include/openthread/tcat.h
OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE#
#define OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZEValue:
5
TCAT max size of any type of advertised Device ID.
71
of file include/openthread/tcat.h
OT_TCAT_MAX_DEVICEID_SIZE#
#define OT_TCAT_MAX_DEVICEID_SIZEValue:
64
TCAT max size of device ID.
72
of file include/openthread/tcat.h