# BLE Secure

This module includes functions that control BLE Secure (TLS over BLE) communication.

## Summary

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.

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaac440753bdbd9d10ff6d64a7a638f5c4{ https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaac440753bdbd9d10ff6d64a7a638f5c4a9d19c576296cd42eb595c23462e96560 = 0, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaac440753bdbd9d10ff6d64a7a638f5c4a5bc6976cb96b2c160d0bd3e11176d1a0 = 1, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaac440753bdbd9d10ff6d64a7a638f5c4a70268d73e99e37aaa75e79b0d735ec11 = 2, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaac440753bdbd9d10ff6d64a7a638f5c4ae4f47a3823c5b757366f4435b61084ea = 3, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaac440753bdbd9d10ff6d64a7a638f5c4aedace9aab37c01d976bb5fe0228496dd = 4, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaac440753bdbd9d10ff6d64a7a638f5c4afb8a0404515a3b1bafe6e2a14a137ca6 = 5 }` | enumRepresents Advertised Device ID type. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga0d8d0c6d8b77199f1106f621b47d1530{ https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530a6e696cbe16a64173ca8bbfd6a76fdf05 = 0, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530ad09be555a794a44891ac858ad4e16896 = 0x02, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530a5cfaad8d563205d29d829e68a78ea2eb = 0x81, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530ac95c3c73cf3d4c1dc8a6dbcbcb60d9e8 = 0x82, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530a2de295ca45b5f0fb45c89af1511893a8 = 0x83, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530ae9a2a5e5ffc7fac04bd23b430d4fb1d9 = 0x84, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga0d8d0c6d8b77199f1106f621b47d1530aeaa3ba9c931d8be54ddaecdada184146 = 0x9F }` | enumRepresents TCAT application protocol options. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga2c16fe6fa8361eecebe90fdac6797254{ https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga2c16fe6fa8361eecebe90fdac6797254a15de90df6d9b25e91f264fe4d781171d = 0, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga2c16fe6fa8361eecebe90fdac6797254a7666a0974993a6159f58b4384c251742 = 1, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga2c16fe6fa8361eecebe90fdac6797254a612dae50f828d28d438d91261640b30e = 2, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga2c16fe6fa8361eecebe90fdac6797254a336bb9408362d2b460af272c51dae264 = 3, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga2c16fe6fa8361eecebe90fdac6797254ab91c7686a4d16edc7dfcee3185288e9e = 4 }` | enumRepresents a TCAT command class. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga5cb6e9ac50daa517f8d4b19219ec5d22{ https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a1ce4debc76e8aac6fa64dafcf986b382 = 0x01, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a5390585f3f02cff8ceafde760fa7a440 = 0x02, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a26fc143d3413546df403414c3cab5d0a = 0x03, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a7c48e2e25c595477ee6562cc43c0c758 = 0x08, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a8c4b2e0dcf92cd0c6660fa2986382a7a = 0x09, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a60dbb503e8b67f40c435cab8955c0371 = 0x0A, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a296db7f0b7f5df61e02b58f1a0856073 = 0x0B, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a775d5db969e3948ab25fa14814cfd44e = 0x0C, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22ac49e94a849df0d909486d67c3b674cd7 = 0x0D, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a497872622c49b8d4ce2dc155176d8c5f = 0x10, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a131c60db3c796a336bd1b7175f10bef1 = 0x11, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a24304faa4d8794c9f6dfd49dd63debd0 = 0x12, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22aaab08de7f6127cd153ecd83e5570339c = 0x13, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22af0a167493a4de660fd4fc5249cc6c53a = 0x20, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a2368badd5fd30e98da0febb208c1fe70 = 0x21, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a0dc6c6358750b50b8ffff35ecbcdbe63 = 0x25, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a0236b5e00990a613c3aa71f81967d47a = 0x26, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22ae5924fd17a30caa3005df74657003360 = 0x27, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a6ed435aa61f5fa55ec0f0e99571f9057 = 0x28, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22aa86edbe2ac8efc29a689456f2146a493 = 0x40, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a45d719ecc116a04fbe12889411159e7c = 0x41, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22ac7a1a0004af72ece9c9b3f55cec82274 = 0x60, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22afc9e0103b3f82f6b33ffcb8f7a1c4e02 = 0x80, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a5da16529123ad30f3bbaa643f76d1096 = 0x81, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a74b856d91e8c64bb953395c44bc8406a = 0x82, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22afa5920717dcf8d229cc836424b503a0a = 0x83, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a8ed8921465c97493f87cf420eac1bd54 = 0x84, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22adeed249123cbca8def653ccfc983e41a = 0x89, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a920f3af256346a3cbb01cebd0f76767b = 0x8A, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22af6536f299dfa5e1f42453e49ec59908a = 0x9F, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a46a2e2172190f85532cbaea2d4f8f971 = 0xA0, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a95c72cb4382ba1ea7e09cba2a379425e = 0xA1, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gga5cb6e9ac50daa517f8d4b19219ec5d22a281d0438d2c1e8045fee861d410fcc57 = 0xA2 }` | enumRepresents TCAT command TLV type. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaeb66dd61244b711c73bf16a206f44a77{ https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77acb8064877cb193a3b527f14610f43a5e = 0, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a2107ff309876a46de26436aeff0f1883 = 1, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a69e2a2fc60d3eb443c75da2a1a5dbb50 = 2, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a17c34a5217e0a5b3ae9d3aa3f8511da7 = 3, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a231a5dbe5b6d1c77867d3676a8a01124 = 4, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a469151c2354c661ba8f4aa29450c0e47 = 5, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a0d41adca88f5e591ecd3870da8f192b3 = 6, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a47ccd6717a9be71bd39858f2407024f3 = 7, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a2d823820967624fd1b982325903a62f9 = 8, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ggaeb66dd61244b711c73bf16a206f44a77a97a276b58e5b10fd16e88a23ee77a20d = 16 }` | enumRepresents TCAT status code. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga448f56b9750aeebce7eb642fa020fd26)(otInstance *aInstance, bool aConnected, bool aBleConnectionOpen, void *aContext)` | typedef `void(*` Pointer to a callback function invoked whenever the BLE Secure connection state changes. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gae728906eed23b11cd1cc16edd1270dce` | typedef `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaab8e570f1084f6cd1a83871f9a736ddb` Pointer to call when data was received over a BLE Secure TLS connection. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaab8e570f1084f6cd1a83871f9a736ddb)(otInstance *aInstance, const otMessage *aMessage, int32_t aOffset, otTcatApplicationProtocol aTcatApplicationProtocol, void *aContext)` | typedef `void(*` Pointer to call when application data or vendor-specific data was received over a TCAT TLS connection. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga9f68d3d44c1d22cb82eeb05dc51c2e44)(otInstance *aInstance, bool aIsJoin, otError aError, void *aContext)` | typedef `void(*` Pointer to call to notify of a network join/leave operation initiated under guidance of a TCAT Commissioner. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga147f247601d1ce0bba64cfb9d8fffab7)(otInstance *aInstance, otTcatCommandTlvType aTlvType, void *aContext)` | typedef `bool(*` Pointer to call to control if a TCAT TLV of a specific type is supported. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gadd0800859d43a8a76f4eb966d770d0c3` | typedef `struct https://openthread.io/reference/struct/ot-tcat-advertised-device-id` |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gae9e8c6b8b0527dde38f6e5bbc279e4a7` | typedef `enum https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaac440753bdbd9d10ff6d64a7a638f5c4` Represents Advertised Device ID type. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga14a1c4baf4636f78a536b0a567a27e71` | typedef `enum https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga0d8d0c6d8b77199f1106f621b47d1530` Represents TCAT application protocol options. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga2102b59d1de444f731f4876743e73d88` | typedef `enum https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga2c16fe6fa8361eecebe90fdac6797254` Represents a TCAT command class. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaa0bcc10b6943b09ea864e4504ca00916` | typedef `enum https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga5cb6e9ac50daa517f8d4b19219ec5d22` Represents TCAT command TLV type. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga5bb820a146a6496c97cab13f9a9f0970` | typedef `struct https://openthread.io/reference/struct/ot-tcat-general-device-id` Represents General Device ID type. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gab4a04658f71b8990cbfff8d8b7d626cf` | typedef `enum https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaeb66dd61244b711c73bf16a206f44a77` Represents TCAT status code. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gac33c0bacef61e7f76da51b481f2e2cfa` | typedef `struct https://openthread.io/reference/struct/ot-tcat-vendor-info` This structure represents a TCAT vendor information. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga7908296b539cdf96f055de186ee6cf24(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Initializes TLS session with a peer using an already open BLE connection. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga4df0a91320c63432be88f0db697f5236(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Stops the BLE and TLS connections. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga56058e0c5edd9cba0cc42a0a3ef58f2f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Flushes the send buffer. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gac5c729f4070029b3100a730b61827b28(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Gets the Install Code Verify Status during the current session. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga6aaec8be831be65a9bdee2987eb59b94(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, unsigned char *aPeerCert, size_t *aCertLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Returns the peer x509 certificate base64 encoded. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga2d7e8374b54b93950871ce2949c548a2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, unsigned char *aPeerCert, size_t *aCertLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Returns the DER encoded peer x509 certificate. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga65b8b30a817ee8ca74b9718499c66388(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aOid, size_t aOidLength, uint8_t *aAttributeBuffer, size_t *aAttributeLength, int *aAsn1Type)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Returns an attribute value identified by its OID from the subject of the peer x509 certificate. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga74541155f7c5e69c3f8c0493e82b634a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, int aThreadOidDescriptor, uint8_t *aAttributeBuffer, size_t *aAttributeLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` 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. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga98b3631ca4e297ffdcaba955d21a2b3a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, int aThreadOidDescriptor, uint8_t *aAttributeBuffer, size_t *aAttributeLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` 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. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gae2ed9ec659181a15ebd1f8825e220ca0(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga2c16fe6fa8361eecebe90fdac6797254 aCommandClass)` | `bool` Indicates whether or not a TCAT command class is authorized for the current TCAT Commissioner. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga3721ac8798c852af5c2cb6ad7eb53fce(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the TLS session is connected. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga3053345e6273f64f03da025ee4ccc4a1(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the TLS session is active (connected or connecting). |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gacde189e317c24cb83c24e4812e505f49(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the TCAT agent is started over BLE secure. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga21b15090da95a43f56c13267f433c278(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint8_t *aBuf, uint16_t aLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a secure BLE data packet. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga346f8c8c8777143f100c44f78b0ceff8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga0d8d0c6d8b77199f1106f621b47d1530 aApplicationProtocol, uint8_t *aBuf, uint16_t aLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a secure BLE data packet containing application data directed to the application layer `aApplicationProtocol` or a response to the latest received application data packet. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gac65ce6b31369429b9840575a6bd4a168(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-message#group__api-message_1ga42d128a0a9ad58de0eb79673843c2955 *aMessage)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends a secure BLE message. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaece24cd503bec0d459f79773dc61b2c8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)` | `void` Sets the trusted top level CAs. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga9ec873a118b3e4bfbbfc7ea7b312903e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const uint8_t *aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength)` | `void` Sets the local device's X509 certificate and corresponding private key. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga3f5fc3ab8165d0bed997ec51a8327e0e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const uint8_t *aPsk, uint16_t aPskLength, const uint8_t *aPskIdentity, uint16_t aPskIdLength)` | `void` Sets the Pre-Shared Key (PSK) and cipher suite TLS_PSK_WITH_AES_128_CCM_8. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaa21030867e154df6557f97fcd61e106d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aVerifyPeerCertificate)` | `void` Sets the authentication mode for the BLE secure connection. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga029ef3cacaa9f2040b255dfb315eb640(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aActive, uint32_t aDelayMs, uint32_t aDurationMs)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the TCAT agent over BLE Secure into active or standby state. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga1967cca26399a4ef64095e42cdb3b369(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-tcat-vendor-info *aVendorInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets TCAT vendor info. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gacd778687ff8f0c8d0f73ef9ef421512a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga448f56b9750aeebce7eb642fa020fd26 aConnectHandler, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gae728906eed23b11cd1cc16edd1270dce aReceiveHandler, bool aTlvMode, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts the BLE Secure service. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga20f5b8659c656e04ec77317790e8bb76(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Stops the BLE Secure server. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gab56e4b2dd0c89c9a50f9b1217953c683(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga9f68d3d44c1d22cb82eeb05dc51c2e44 aJoinHandler)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Enables the TCAT protocol over BLE Secure. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga865d43004368a96828b5fc4b5eb17386 29` | Maximum length of TCAT advertisement. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga2c7e0c2af0096f2c6b6a54e7892d3840 4` | Maximum number of application layer service names supported. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga13805c115ed613c597fededc87cf6fb9 600` | TCAT_ENABLE_MAX, default max TMF TCAT enable time, in seconds. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga8412976c5731f7303d4c92c4fad8e53f 5` | TCAT max size of any type of advertised Device ID. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga335b4b412171ba937fe0feced53ba893 64` | TCAT max size of device ID. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1gaf4048b52c5eb2fada2e2e639a3a66f5d 0x2` | TCAT Advertisement Operation Code. |
| `https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga78ed43597323cda9a0fcb04a0b4aa21f 15` | Maximum string length of a UDP or TCP service name (does not include null char). |

| ### Structs ||
|---|---|
| [otTcatAdvertisedDeviceId](https://openthread.io/reference/struct/ot-tcat-advertised-device-id) |   |
| [otTcatGeneralDeviceId](https://openthread.io/reference/struct/ot-tcat-general-device-id) | Represents General Device ID type. |
| [otTcatVendorInfo](https://openthread.io/reference/struct/ot-tcat-vendor-info) | This structure represents a TCAT vendor information. |

## Enumerations

### otTcatAdvertisedDeviceIdType

```
 otTcatAdvertisedDeviceIdType
```
Represents Advertised Device ID type.

Used during TCAT advertisement.

| Properties ||
|---|---|
| `OT_TCAT_DEVICE_ID_DISCRIMINATOR` | Advertised device ID type Device Discriminator. |
| `OT_TCAT_DEVICE_ID_EMPTY` | Advertised device ID type not set. |
| `OT_TCAT_DEVICE_ID_IANAPEN` | Advertised device ID type IANA PEN. |
| `OT_TCAT_DEVICE_ID_MAX` | Advertised device ID max number of types. |
| `OT_TCAT_DEVICE_ID_OUI24` | Advertised device ID type IEEE OUI-24. |
| `OT_TCAT_DEVICE_ID_OUI36` | Advertised device ID type IEEE OUI-36. |

### otTcatApplicationProtocol

```
 otTcatApplicationProtocol
```
Represents TCAT application protocol options.

| Properties ||
|---|---|
| `OT_TCAT_APPLICATION_PROTOCOL_1` | Message directed to application protocol 1. |
| `OT_TCAT_APPLICATION_PROTOCOL_2` | Message directed to application protocol 2. |
| `OT_TCAT_APPLICATION_PROTOCOL_3` | Message directed to application protocol 3. |
| `OT_TCAT_APPLICATION_PROTOCOL_4` | Message directed to application protocol 4. |
| `OT_TCAT_APPLICATION_PROTOCOL_NONE` | Message which has been sent without activating the TCAT agent. |
| `OT_TCAT_APPLICATION_PROTOCOL_RESPONSE` | Message directed to any application protocol indicating a response with status value (one byte otTcatStatusCode) Message directed to any application protocol indicating a response with payload |
| `OT_TCAT_APPLICATION_PROTOCOL_VENDOR` | Message directed to a vendor specific application protocol. |

### otTcatCommandClass

```
 otTcatCommandClass
```
Represents a TCAT command class.

| Properties ||
|---|---|
| `OT_TCAT_COMMAND_CLASS_APPLICATION` | TCAT commands related to application layer. |
| `OT_TCAT_COMMAND_CLASS_COMMISSIONING` | TCAT commands related to commissioning. |
| `OT_TCAT_COMMAND_CLASS_DECOMMISSIONING` | TCAT commands related to de-commissioning. |
| `OT_TCAT_COMMAND_CLASS_EXTRACTION` | TCAT commands related to key extraction. |
| `OT_TCAT_COMMAND_CLASS_GENERAL` | TCAT commands related to general operations. |

### otTcatCommandTlvType

```
 otTcatCommandTlvType
```
Represents TCAT command TLV type.

| Properties ||
|---|---|
| `OT_TCAT_TLV_DECOMMISSION` | TCAT decommission request TLV. |
| `OT_TCAT_TLV_DISCONNECT` | TCAT disconnect request TLV. |
| `OT_TCAT_TLV_GET_ACTIVE_OPERATIONAL_DATASET` | TCAT active operational dataset query TLV. |
| `OT_TCAT_TLV_GET_ACTIVE_OPERATIONAL_DATASET_ALT` | TCAT active dataset alt #1 query TLV (reserved) |
| `OT_TCAT_TLV_GET_APPLICATION_LAYERS` | TCAT get application layers request TLV. |
| `OT_TCAT_TLV_GET_COMMISSIONER_CERTIFICATE` | TCAT commissioner certificate query TLV. |
| `OT_TCAT_TLV_GET_DEVICE_ID` | TCAT device ID query TLV. |
| `OT_TCAT_TLV_GET_DIAGNOSTIC_TLVS` | TCAT diagnostics TLVs query TLV. |
| `OT_TCAT_TLV_GET_EXTENDED_PAN_ID` | TCAT extended PAN ID query TLV. |
| `OT_TCAT_TLV_GET_NETWORK_NAME` | TCAT network name query TLV. |
| `OT_TCAT_TLV_GET_PROVISIONING_URL` | TCAT provisioning URL query TLV. |
| `OT_TCAT_TLV_PING` | TCAT ping request TLV. |
| `OT_TCAT_TLV_PRESENT_INSTALL_CODE_HASH` | TCAT rights elevation TLV using install code. |
| `OT_TCAT_TLV_PRESENT_PSKC_HASH` | TCAT rights elevation request TLV using PSKc hash. |
| `OT_TCAT_TLV_PRESENT_PSKD_HASH` | TCAT rights elevation request TLV using PSKd hash. |
| `OT_TCAT_TLV_REQUEST_RANDOM_CHALLENGE` | TCAT random number challenge query TLV. |
| `OT_TCAT_TLV_RESPONSE_EVENT` | TCAT response event TLV (reserved) |
| `OT_TCAT_TLV_RESPONSE_WITH_PAYLOAD` | TCAT response with payload TLV. |
| `OT_TCAT_TLV_RESPONSE_WITH_STATUS` | TCAT response with status value TLV. |
| `OT_TCAT_TLV_SEND_APPLICATION_DATA_1` | TCAT send application data 1 TLV. |
| `OT_TCAT_TLV_SEND_APPLICATION_DATA_2` | TCAT send application data 2 TLV. |
| `OT_TCAT_TLV_SEND_APPLICATION_DATA_3` | TCAT send application data 3 TLV. |
| `OT_TCAT_TLV_SEND_APPLICATION_DATA_4` | TCAT send application data 4 TLV. |
| `OT_TCAT_TLV_SEND_VENDOR_SPECIFIC_DATA` | TCAT send vendor specific command or data TLV. |
| `OT_TCAT_TLV_SERVICE_NAME_TCP` | TCAT service name TCP sub-TLV (not used as a command) |
| `OT_TCAT_TLV_SERVICE_NAME_UDP` | TCAT service name UDP sub-TLV (not used as a command) |
| `OT_TCAT_TLV_SET_ACTIVE_OPERATIONAL_DATASET` | TCAT active operational dataset TLV. |
| `OT_TCAT_TLV_SET_ACTIVE_OPERATIONAL_DATASET_ALT` | TCAT active dataset alt #1 TLV (reserved) |
| `OT_TCAT_TLV_SET_DOMAIN_CA_CERT` | TCAT set domain CA certificate TLV (reserved) |
| `OT_TCAT_TLV_SET_LDEV_ID_OPERATIONAL_CERT` | TCAT set LDevID certificate TLV (reserved) |
| `OT_TCAT_TLV_SET_LDEV_ID_PRIVATE_KEY` | TCAT set LDevID certificate private key TLV (reserved) |
| `OT_TCAT_TLV_START_THREAD_INTERFACE` | TCAT start thread interface request TLV. |
| `OT_TCAT_TLV_STOP_THREAD_INTERFACE` | TCAT stop thread interface request TLV. |

### otTcatStatusCode

```
 otTcatStatusCode
```
Represents TCAT status code.

| Properties ||
|---|---|
| `OT_TCAT_STATUS_BUSY` | Command cannot be executed because the resource is busy. |
| `OT_TCAT_STATUS_GENERAL_ERROR` | An error not matching any other category occurred. |
| `OT_TCAT_STATUS_HASH_ERROR` | The hash value presented by the commissioner was incorrect. |
| `OT_TCAT_STATUS_INVALID_STATE` | The TCAT device is not in a correct state for the given command. |
| `OT_TCAT_STATUS_PARSE_ERROR` | Request / command could not be parsed correctly. |
| `OT_TCAT_STATUS_SUCCESS` | Command or request was successfully processed. |
| `OT_TCAT_STATUS_UNAUTHORIZED` | Sender does not have sufficient authorization for the given command. |
| `OT_TCAT_STATUS_UNDEFINED` | The requested value, data or service is not defined (currently) or not present. |
| `OT_TCAT_STATUS_UNSUPPORTED` | Requested command or received TLV is not supported. |
| `OT_TCAT_STATUS_VALUE_ERROR` | The value of the transmitted TLV has an error. |

## Typedefs

### otHandleBleSecureConnect

```
void(* otHandleBleSecureConnect)(otInstance *aInstance, bool aConnected, bool aBleConnectionOpen, void *aContext)
```
Pointer to a callback function invoked whenever the BLE Secure connection state changes.

The connection includes two layers that are reported independently: the underlying BLE link (`aBleConnectionOpen`) and the TLS session carried over it (`aConnected`). Both arguments report the current state of their respective layer (without disclosing which one(s) changed).

A TLS session cannot exist without a BLE link to carry it, so `aConnected` being TRUE always implies `aBleConnectionOpen` being TRUE. The three resulting states are:


- (aBleConnectionOpen=FALSE, aConnected=FALSE): Fully disconnected; no BLE link and no TLS session.
- (aBleConnectionOpen=TRUE, aConnected=FALSE): BLE link is up; TLS session not (yet) established.
- (aBleConnectionOpen=TRUE, aConnected=TRUE): BLE link is up and the TLS session is established.

<br />

The callback is invoked exactly once per change of the (`aBleConnectionOpen`, `aConnected`) pair and is never invoked twice in a row with identical argument values. If the BLE link drops while a TLS session is active, the TLS session is treated as closed at that same instant: a single call with (FALSE, FALSE) is made.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aConnected` | TRUE if a secure TLS session is established, FALSE otherwise. | | `[in] aBleConnectionOpen` | TRUE if a BLE link is open to carry the TLS data stream, FALSE otherwise. | | `[in] aContext` | A pointer to arbitrary context information. | |

### otHandleBleSecureReceive

```
otHandleTcatApplicationDataReceive otHandleBleSecureReceive
```
Pointer to call when data was received over a BLE Secure TLS connection.

When TCAT has been started, the TCAT agent automatically responds with status OT_TCAT_STATUS_UNSUPPORTED if no response has been generated or no handler is defined. The application may generate a response to incoming TCAT application data or vendor-specific data by calling [otBleSecureSendApplicationTlv](https://openthread.io/reference/group/api-ble-secure#group__api-ble-secure_1ga346f8c8c8777143f100c44f78b0ceff8).

### otHandleTcatApplicationDataReceive

```
void(* otHandleTcatApplicationDataReceive)(otInstance *aInstance, const otMessage *aMessage, int32_t aOffset, otTcatApplicationProtocol aTcatApplicationProtocol, void *aContext)
```
Pointer to call when application data or vendor-specific data was received over a TCAT TLS connection.

The application may generate a response to an incoming TCAT application data packet. The TCAT agent automatically responds with status OT_TCAT_STATUS_UNSUPPORTED if no response has been generated or no handler is defined.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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 application protocol the message is targeted to. | | `[in] aContext` | A pointer to arbitrary context information. | |

### otHandleTcatJoin

```
void(* otHandleTcatJoin)(otInstance *aInstance, bool aIsJoin, otError aError, void *aContext)
```
Pointer to call to notify of a network join/leave operation initiated under guidance of a TCAT Commissioner.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aIsJoin` | True if the operation was a network join (OT_TCAT_TLV_START_THREAD_INTERFACE), false if it was a network leave (OT_TCAT_TLV_STOP_THREAD_INTERFACE or OT_TCAT_TLV_DECOMMISSION). | | `[in] aError` | OT_ERROR_NONE if the network join/leave operation was successfully started. OT_ERROR_INVALID_STATE if network join was requested but network credentials were missing or incomplete. OT_ERROR_REJECTED if a network join/leave operation was requested, but the TCAT Commissioner is not authorized to make such a request. OT_ERROR_SECURITY is reserved for future use for a failed join due to credential mismatch. | | `[in] aContext` | A pointer to arbitrary context information. | |

### otHandleTcatTlvSupport

```
bool(* otHandleTcatTlvSupport)(otInstance *aInstance, otTcatCommandTlvType aTlvType, void *aContext)
```
Pointer to call to control if a TCAT TLV of a specific type is supported.

The application may allow or reject processing of a received TCAT command based on an application defined policy. If no handler is defined, all received TCAT commands will be allowed if the respective command class is authorized. If a handler is defined and returns false, the TCAT command will be rejected with status OT_TCAT_STATUS_UNSUPPORTED. If the handler returns true, the TCAT command will be allowed if the respective command class is authorized.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aTlvType` | A TLV type to be authorized. | | `[in] aContext` | A pointer to arbitrary context information. | |
| **Returns** | a boolean value indicating whether the TLV type is supported, based on current policy. |

### otTcatAdvertisedDeviceId

```
struct otTcatAdvertisedDeviceId otTcatAdvertisedDeviceId
```

### otTcatAdvertisedDeviceIdType

```
enum otTcatAdvertisedDeviceIdType otTcatAdvertisedDeviceIdType
```
Represents Advertised Device ID type.

Used during TCAT advertisement.

### otTcatApplicationProtocol

```
enum otTcatApplicationProtocol otTcatApplicationProtocol
```
Represents TCAT application protocol options.

### otTcatCommandClass

```
enum otTcatCommandClass otTcatCommandClass
```
Represents a TCAT command class.

### otTcatCommandTlvType

```
enum otTcatCommandTlvType otTcatCommandTlvType
```
Represents TCAT command TLV type.

### otTcatGeneralDeviceId

```
struct otTcatGeneralDeviceId otTcatGeneralDeviceId
```
Represents General Device ID type.

### otTcatStatusCode

```
enum otTcatStatusCode otTcatStatusCode
```
Represents TCAT status code.

### otTcatVendorInfo

```
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.

## Functions

### otBleSecureConnect

```
otError otBleSecureConnect(
  otInstance *aInstance
)
```
Initializes TLS session with a peer using an already open BLE connection.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully started TLS connection. | |

### otBleSecureDisconnect

```
void otBleSecureDisconnect(
  otInstance *aInstance
)
```
Stops the BLE and TLS connections.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |

### otBleSecureFlush

```
otError otBleSecureFlush(
  otInstance *aInstance
)
```
Flushes the send buffer.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully flushed output buffer. | | `OT_ERROR_NO_BUFS` | Failed to allocate buffer memory. | | `OT_ERROR_INVALID_STATE` | TLS connection was not initialized. | |

### otBleSecureGetInstallCodeVerifyStatus

```
bool otBleSecureGetInstallCodeVerifyStatus(
  otInstance *aInstance
)
```
Gets the Install Code Verify Status during the current session.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The install code was correctly verified. | | `FALSE` | The install code was not verified. | |

### otBleSecureGetPeerCertificateBase64

```
otError otBleSecureGetPeerCertificateBase64(
  otInstance *aInstance,
  unsigned char *aPeerCert,
  size_t *aCertLength
)
```
Returns the peer x509 certificate base64 encoded.


> [!NOTE]
> **Note:** Requires the build-time features `MBEDTLS_BASE64_C` and `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[out] aPeerCert` | A pointer to the base64 encoded certificate buffer. | | `[in,out] aCertLength` | On input, the size the max size of `aPeerCert`. On output, the length of the base64 encoded peer certificate. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully get the peer certificate. | | `OT_ERROR_INVALID_ARGS` | `aInstance` or `aCertLength` is invalid. | | `OT_ERROR_INVALID_STATE` | Not connected yet. | | `OT_ERROR_NO_BUFS` | Can't allocate memory for certificate. | |

### otBleSecureGetPeerCertificateDer

```
otError otBleSecureGetPeerCertificateDer(
  otInstance *aInstance,
  unsigned char *aPeerCert,
  size_t *aCertLength
)
```
Returns the DER encoded peer x509 certificate.


> [!NOTE]
> **Note:** Requires the build-time feature `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[out] aPeerCert` | A pointer to the DER encoded certificate buffer. | | `[in,out] aCertLength` | On input, the size the max size of `aPeerCert`. On output, the length of the DER encoded peer certificate. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully get the peer certificate. | | `OT_ERROR_INVALID_ARGS` | `aInstance` or `aCertLength` is invalid. | | `OT_ERROR_INVALID_STATE` | Not connected yet. | | `OT_ERROR_NO_BUFS` | Can't allocate memory for certificate. | |

### 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.

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]
> **Note:** Requires the build-time feature `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | | `[in,out] aAttributeLength` | On input, the size the max size of `aAttributeBuffer`. On output, the length of the attribute written to the buffer. | | `[out] aAsn1Type` | A pointer to the ASN.1 type of the attribute written to the buffer. | |
| Return Values | |---|---| | `OT_ERROR_INVALID_STATE` | Not connected yet. | | `OT_ERROR_INVALID_ARGS` | Invalid attribute length. | | `OT_ERROR_NONE` | Successfully read attribute. | | `OT_ERROR_NO_BUFS` | Insufficient memory for storing the attribute value. | |

### 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.

The attribute length is set if the attribute was successfully read or zero if unsuccessful. Requires a connection to be active.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | | `[in,out] aAttributeLength` | On input, the size the max size of `aAttributeBuffer`. On output, the length of the attribute written to the buffer. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully read attribute. | | `OT_ERROR_INVALID_ARGS` | Invalid attribute length. | | `OT_NOT_FOUND` | The requested attribute was not found. | | `OT_ERROR_NO_BUFS` | Insufficient memory for storing the attribute value. | | `OT_ERROR_INVALID_STATE` | Not connected yet. | | `OT_ERROR_NOT_IMPLEMENTED` | The value of aThreadOidDescriptor is \>127. | | `OT_ERROR_PARSE` | The certificate extensions could not be parsed. | |

### 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.

The attribute length is set if the attribute was successfully read or zero if unsuccessful. Requires a connection to be active.


> [!NOTE]
> **Note:** Requires the build-time feature `MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` to be enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | | `[in,out] aAttributeLength` | On input, the size the max size of `aAttributeBuffer`. On output, the length of the attribute written to the buffer. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully read attribute. | | `OT_ERROR_INVALID_ARGS` | Invalid attribute length. | | `OT_NOT_FOUND` | The requested attribute was not found. | | `OT_ERROR_NO_BUFS` | Insufficient memory for storing the attribute value. | | `OT_ERROR_INVALID_STATE` | Not connected yet. | | `OT_ERROR_NOT_IMPLEMENTED` | The value of aThreadOidDescriptor is \>127. | | `OT_ERROR_PARSE` | The certificate extensions could not be parsed. | |

### otBleSecureIsCommandClassAuthorized

```
bool otBleSecureIsCommandClassAuthorized(
  otInstance *aInstance,
  otTcatCommandClass aCommandClass
)
```
Indicates whether or not a TCAT command class is authorized for the current TCAT Commissioner.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aCommandClass` | A command class to check. | |
| Return Values | |---|---| | `TRUE` | The command class is authorized for the current (if any) TCAT Commissioner. | | `FALSE` | The command class is not authorized. | |

### otBleSecureIsConnected

```
bool otBleSecureIsConnected(
  otInstance *aInstance
)
```
Indicates whether or not the TLS session is connected.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The TLS session is connected. | | `FALSE` | The TLS session is not connected. | |

### otBleSecureIsConnectionActive

```
bool otBleSecureIsConnectionActive(
  otInstance *aInstance
)
```
Indicates whether or not the TLS session is active (connected or connecting).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | If TLS session is active. | | `FALSE` | If TLS session is not active. | |

### otBleSecureIsTcatAgentStarted

```
bool otBleSecureIsTcatAgentStarted(
  otInstance *aInstance
)
```
Indicates whether or not the TCAT agent is started over BLE secure.

<br />

| Details ||
|---|---|
| Return Values | |---|---| | `TRUE` | The TCAT agent is started, communicating over BLE secure. | | `FALSE` | The TCAT agent is disabled on BLE secure. | |

### otBleSecureSend

```
otError otBleSecureSend(
  otInstance *aInstance,
  uint8_t *aBuf,
  uint16_t aLength
)
```
Sends a secure BLE data packet.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully sent data. | | `OT_ERROR_NO_BUFS` | Failed to allocate buffer memory. | | `OT_ERROR_INVALID_STATE` | TLS connection was not initialized. | |

### otBleSecureSendApplicationTlv

```
otError otBleSecureSendApplicationTlv(
  otInstance *aInstance,
  otTcatApplicationProtocol aApplicationProtocol,
  uint8_t *aBuf,
  uint16_t aLength
)
```
Sends a secure BLE data packet containing application data directed to the application layer `aApplicationProtocol` or a response to the latest received application data packet.

Only a single response can be sent while executing the `otHandleBleSecureReceive` handler. If no (further) response is expected `OT_ERROR_REJECTED` is returned.

For responses with a payload `aApplicationProtocol` shall be set to `OT_TCAT_APPLICATION_PROTOCOL_PAYLOAD`. For responses with a status `aApplicationProtocol` shall be `OT_TCAT_APPLICATION_PROTOCOL_STATUS` and @ aBuf shall contain a single byte `otTcatStatusCode` value.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aApplicationProtocol` | An application protocol the data is directed to. | | `[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. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully sent data. | | `OT_ERROR_NO_BUFS` | Failed to allocate buffer memory. | | `OT_ERROR_INVALID_STATE` | TLS connection was not initialized. | | `OT_ERROR_REJECTED` | Application protocol is response with data or status but no response is pending. | |

### otBleSecureSendMessage

```
otError otBleSecureSendMessage(
  otInstance *aInstance,
  otMessage *aMessage
)
```
Sends a secure BLE message.


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.

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aMessage` | A pointer to the message to send. | |

<br />

| Details ||
|---|---|
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully sent message. | | `OT_ERROR_NO_BUFS` | Failed to allocate buffer memory. | | `OT_ERROR_INVALID_STATE` | TLS connection was not initialized. | |

### otBleSecureSetCaCertificateChain

```
void otBleSecureSetCaCertificateChain(
  otInstance *aInstance,
  const uint8_t *aX509CaCertificateChain,
  uint32_t aX509CaCertChainLength
)
```
Sets the trusted top level CAs.

It is needed for validating the certificate of the peer via TLS.

Used for TLS sessions with cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.


> [!NOTE]
> **Note:** Requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | |

### 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 and corresponding private key.

Used for TLS sessions with cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.


> [!NOTE]
> **Note:** Requires `MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED=1`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | |

### 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.


> [!NOTE]
> **Note:** Requires the build-time feature `MBEDTLS_KEY_EXCHANGE_PSK_ENABLED` to be enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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. | |

### otBleSecureSetSslAuthMode

```
void otBleSecureSetSslAuthMode(
  otInstance *aInstance,
  bool aVerifyPeerCertificate
)
```
Sets the authentication mode for the BLE secure connection.

Disable or enable the verification of peer certificate. Must be called before start.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aVerifyPeerCertificate` | true, to verify the peer certificate. | |

### otBleSecureSetTcatAgentState

```
otError otBleSecureSetTcatAgentState(
  otInstance *aInstance,
  bool aActive,
  uint32_t aDelayMs,
  uint32_t aDurationMs
)
```
Sets the TCAT agent over BLE Secure into active or standby state.

In standby state, no BLE advertisements are sent and TCAT Commissioners can't connect. TCAT can be automatically enabled via a TMF message while in standby.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aActive` | If TRUE, attempts to set TCAT agent to active state. If FALSE, attempts to set TCAT agent to standby (inactive) state. | | `[in] aDelayMs` | Delay in ms before activating TCAT agent. If 0, activate immediately. | | `[in] aDurationMs` | Duration in ms of the activation of the TCAT agent. If 0, activate indefinitely. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully set the TCAT state as requested. | | `OT_ERROR_INVALID_STATE` | TCAT is not yet started, or not in a state from which it can transition to the desired state. | |

### otBleSecureSetTcatVendorInfo

```
otError otBleSecureSetTcatVendorInfo(
  otInstance *aInstance,
  const otTcatVendorInfo *aVendorInfo
)
```
Sets TCAT vendor info.

The vendor info is used for advertising in TCAT Advertisements, as well as for responding to particular TCAT commands that supply vendor info to the TCAT Commissioner.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aVendorInfo` | A pointer to the Vendor Information (MUST remain valid after the method call). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully set vendor info. | | `OT_ERROR_INVALID_ARGS` | Vendor info could not be set. | |

### otBleSecureStart

```
otError otBleSecureStart(
  otInstance *aInstance,
  otHandleBleSecureConnect aConnectHandler,
  otHandleBleSecureReceive aReceiveHandler,
  bool aTlvMode,
  void *aContext
)
```
Starts the BLE Secure service.

When TLV mode is active, the function `aReceiveHandler` will be called once a complete TLV or line was received and the message offset points to the TLV value.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[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 TLV mode (TRUE) shall be activated, or line mode (FALSE). | | `[in] aContext` | A pointer to arbitrary context information. May be NULL if not used. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully started the BLE Secure server. | | `OT_ERROR_FAILED` | The BLE radio could not be enabled, or BLE advertisement data unavailable, or a socket could not be opened. | | `OT_ERROR_NO_BUFS` | No bufferspace available. | | `OT_ERROR_INVALID_ARGS` | Invalid arguments or vendor BLE advertisement data unavailable. | | `OT_ERROR_INVALID_STATE` | BLE Device or socket is in invalid state. | | `OT_ERROR_ALREADY` | The service was started already. | |

### otBleSecureStop

```
void otBleSecureStop(
  otInstance *aInstance
)
```
Stops the BLE Secure server.

If the TCAT agent is active, it is also stopped and any ongoing connection is forcibly ended.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |

### otBleSecureTcatStart

```
otError otBleSecureTcatStart(
  otInstance *aInstance,
  otHandleTcatJoin aJoinHandler
)
```
Enables the TCAT protocol over BLE Secure.

Vendor info must be set before calling this function. Depending on the policy defined in the vendor info, TCAT may start in standby mode if the device is commissioned and Thread is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aJoinHandler` | A pointer to a function that is called when a network join or leave operation is requested under guidance of the TCAT Commissioner. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully started TCAT over BLE Secure. | | `OT_ERROR_ALREADY` | TCAT is already started. | | `OT_ERROR_FAILED` | TCAT vendor info could not be initialized. | | `OT_ERROR_INVALID_STATE` | The BLE Secure function is not started yet or TLV mode is not selected. | |

## Macros

### OT_TCAT_ADVERTISEMENT_MAX_LEN

```
 OT_TCAT_ADVERTISEMENT_MAX_LEN 29
```
Maximum length of TCAT advertisement.

### OT_TCAT_APPLICATION_LAYER_MAX_COUNT

```
 OT_TCAT_APPLICATION_LAYER_MAX_COUNT 4
```
Maximum number of application layer service names supported.

### OT_TCAT_ENABLE_MAX

```
 OT_TCAT_ENABLE_MAX 600
```
TCAT_ENABLE_MAX, default max TMF TCAT enable time, in seconds.

### OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE

```
 OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE 5
```
TCAT max size of any type of advertised Device ID.

### OT_TCAT_MAX_DEVICEID_SIZE

```
 OT_TCAT_MAX_DEVICEID_SIZE 64
```
TCAT max size of device ID.

### OT_TCAT_OPCODE

```
 OT_TCAT_OPCODE 0x2
```
TCAT Advertisement Operation Code.

### OT_TCAT_SERVICE_NAME_MAX_LENGTH

```
 OT_TCAT_SERVICE_NAME_MAX_LENGTH 15
```
Maximum string length of a UDP or TCP service name (does not include null char).

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).