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
otTcatAdvertisedDeviceIdType{
  OT_TCAT_DEVICE_ID_EMPTY = 0,
  OT_TCAT_DEVICE_ID_OUI24 = 1,
  OT_TCAT_DEVICE_ID_OUI36 = 2,
  OT_TCAT_DEVICE_ID_DISCRIMINATOR = 3,
  OT_TCAT_DEVICE_ID_IANAPEN = 4,
  OT_TCAT_DEVICE_ID_MAX = 5
} 		enum
Represents Advertised Device ID type.
otTcatApplicationProtocol{
  OT_TCAT_APPLICATION_PROTOCOL_NONE = 0,
  OT_TCAT_APPLICATION_PROTOCOL_RESPONSE = 0x02,
  OT_TCAT_APPLICATION_PROTOCOL_1 = 0x81,
  OT_TCAT_APPLICATION_PROTOCOL_2 = 0x82,
  OT_TCAT_APPLICATION_PROTOCOL_3 = 0x83,
  OT_TCAT_APPLICATION_PROTOCOL_4 = 0x84,
  OT_TCAT_APPLICATION_PROTOCOL_VENDOR = 0x9F
} 		enum
Represents TCAT application protocol options.
otTcatCommandClass{
  OT_TCAT_COMMAND_CLASS_GENERAL = 0,
  OT_TCAT_COMMAND_CLASS_COMMISSIONING = 1,
  OT_TCAT_COMMAND_CLASS_EXTRACTION = 2,
  OT_TCAT_COMMAND_CLASS_DECOMMISSIONING = 3,
  OT_TCAT_COMMAND_CLASS_APPLICATION = 4
} 		enum
Represents a TCAT command class.
otTcatStatusCode{
  OT_TCAT_STATUS_SUCCESS = 0,
  OT_TCAT_STATUS_UNSUPPORTED = 1,
  OT_TCAT_STATUS_PARSE_ERROR = 2,
  OT_TCAT_STATUS_VALUE_ERROR = 3,
  OT_TCAT_STATUS_GENERAL_ERROR = 4,
  OT_TCAT_STATUS_BUSY = 5,
  OT_TCAT_STATUS_UNDEFINED = 6,
  OT_TCAT_STATUS_HASH_ERROR = 7,
  OT_TCAT_STATUS_INVALID_STATE = 8,
  OT_TCAT_STATUS_UNAUTHORIZED = 16
} 		enum
Represents TCAT status code.

Typedefs
otHandleBleSecureConnect)(otInstance *aInstance, bool aConnected, bool aBleConnectionOpen, void *aContext) typedef
void(*
Pointer to call when ble secure connection state changes.
otHandleBleSecureReceive typedef
Pointer to call when data was received over a BLE Secure TLS connection.
otHandleTcatApplicationDataReceive)(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.
otHandleTcatJoin)(otError aError, void *aContext) typedef
void(*
Pointer to call to notify the completion of a network join/leave operation performed under guidance of a TCAT Commissioner.
otTcatAdvertisedDeviceId typedef
otTcatAdvertisedDeviceIdType typedef
Represents Advertised Device ID type.
otTcatApplicationProtocol typedef
Represents TCAT application protocol options.
otTcatCommandClass typedef
Represents a TCAT command class.
otTcatGeneralDeviceId typedef
Represents General Device ID type.
otTcatStatusCode typedef
Represents TCAT status code.
otTcatVendorInfo typedef
This structure represents a TCAT vendor information.

Functions
otBleSecureConnect(otInstance *aInstance)
Initializes TLS session with a peer using an already open BLE connection.
otBleSecureDisconnect(otInstance *aInstance)
void
Stops the BLE and TLS connections.
otBleSecureFlush(otInstance *aInstance)
Flushes the send buffer.
otBleSecureGetInstallCodeVerifyStatus(otInstance *aInstance)
bool
Gets the Install Code Verify Status during the current session.
otBleSecureGetPeerCertificateBase64(otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength)
Returns the peer x509 certificate base64 encoded.
otBleSecureGetPeerCertificateDer(otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength)
Returns the DER encoded peer x509 certificate.
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.
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.
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.
otBleSecureIsCommandClassAuthorized(otInstance *aInstance, otTcatCommandClass aCommandClass)
bool
Indicates whether or not a TCAT command class is authorized for the current TCAT Commissioner.
otBleSecureIsConnected(otInstance *aInstance)
bool
Indicates whether or not the TLS session is connected.
otBleSecureIsConnectionActive(otInstance *aInstance)
bool
Indicates whether or not the TLS session is active (connected or connecting).
otBleSecureIsTcatAgentStarted(otInstance *aInstance)
bool
Indicates whether or not the TCAT agent is started over BLE secure.
otBleSecureSend(otInstance *aInstance, uint8_t *aBuf, uint16_t aLength)
Sends a secure BLE data packet.
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.
otBleSecureSendMessage(otInstance *aInstance, otMessage *aMessage)
Sends a secure BLE message.
otBleSecureSetCaCertificateChain(otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
void
Sets the trusted top level CAs.
otBleSecureSetCertificate(otInstance *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.
otBleSecureSetPsk(otInstance *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.
otBleSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate)
void
Sets the authentication mode for the BLE secure connection.
otBleSecureSetTcatAgentState(otInstance *aInstance, bool aActive, uint32_t aDelayMs, uint32_t aDurationMs)
Sets the TCAT agent over BLE Secure into active or standby state.
otBleSecureSetTcatVendorInfo(otInstance *aInstance, const otTcatVendorInfo *aVendorInfo)
Sets TCAT vendor info.
otBleSecureStart(otInstance *aInstance, otHandleBleSecureConnect aConnectHandler, otHandleBleSecureReceive aReceiveHandler, bool aTlvMode, void *aContext)
Starts the BLE Secure service.
otBleSecureStop(otInstance *aInstance)
void
Stops the BLE Secure server.
otBleSecureTcatStart(otInstance *aInstance, otHandleTcatJoin aJoinHandler)
Enables the TCAT protocol over BLE Secure.

Macros
OT_TCAT_ADVERTISEMENT_MAX_LEN 29
Maximum length of TCAT advertisement.
OT_TCAT_APPLICATION_LAYER_MAX_COUNT 4
Maximum number of application layer service names supported.
OT_TCAT_MAX_ADVERTISED_DEVICEID_SIZE 5
TCAT max size of any type of advertised Device ID.
OT_TCAT_MAX_DEVICEID_SIZE 64
TCAT max size of device ID.
OT_TCAT_OPCODE 0x2
TCAT Advertisement Operation Code.
OT_TCAT_SERVICE_NAME_MAX_LENGTH 15
Maximum string length of a UDP or TCP service name (does not include null char).

Structs
otTcatAdvertisedDeviceId
otTcatGeneralDeviceId

Represents General Device ID type.

otTcatVendorInfo

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.

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 call when ble secure connection state changes.

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

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.

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.

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)(otError aError, void *aContext)

Pointer to call to notify the completion of a network join/leave operation performed under guidance of a TCAT Commissioner.

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

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.

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.

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.

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

otBleSecureFlush

otError otBleSecureFlush(
  otInstance *aInstance
)

Flushes the send buffer.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

otBleSecureTcatStart

otError otBleSecureTcatStart(
  otInstance *aInstance,
  otHandleTcatJoin aJoinHandler
)

Enables the TCAT protocol over BLE Secure.

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_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. For more information, or to contribute to our documentation, refer to Resources.