 Introduction to security-related API of BLE stack. In the previous sections we have learned the basics of BLE pairing and four pairing methods that exist. Now we will take a closer look on how to select the pairing method you want and how to initiate the pairing in the first place. I would recommend you open in parallel the application node AN-5270 that describes the interface for the Bluetooth stack. Before the pairing takes place, the two devices that form the BLE link exchange some information. This information is the IO capabilities of each device, whether or not the device requires managed middle protection, whether the device has the out-of-band data that were received previously, for example via NFC, and whether or not they support secure simple pairing or legacy only. The pairing method is based on all of the information above. Let's forget about out-of-band for a moment and let's just assume we will use one of the other methods. On the right side in the table you see the selection algorithm that is based on the IO capabilities for both initiator and responder. So let's assume that both devices support secure simple pairing and they both have support for keyboard and display. We end up in the last column and last row, so numeric comparison will be chosen as a pairing method. Here you see the API that should be called from user application side to tell the BLE stack what IOS are available to the application. The input parameter can take one of the five possible values. It can be display only, display and yes, no. By this we mean, for example, a button that can either confirm or reject that the numeric comparison value is the same or not. It can be keyboard only, no input and no output, and both keyboard and display. Apart from IO capabilities, the pairing method selection depends also whether the OOB data are present and whether man in the middle protection is required or not. If at least one of the device has out of band data, then OOB will be used as a pairing method. In the typical scenario when the phone taps the device, it reads the security credentials from the tag and it will set the OOB flag in the pairing feature exchange. Now let's assume that OOB data are not present on any device. Then the selection goes through man in the middle flag. If at least one of the device sets this flag, then IO capabilities are to decide which pairing method will be chosen. If none of the device set man in the middle flag, then JustWorks is used as a pairing method. Here you see the API that is among other things responsible for telling the BLE stack whether man in the middle protection is required or not. Here you see another input parameter of the same API by which we can tell the BLE stack whether secure simple pairing is supported, whether it's optional or whether it's mandatory. Let's now have a look at bonding. Bonding simply means storing the identity and security related information in the non-volatile memory. For bonding to take place, it must be supported on both devices. It can sometimes be used as a low power feature. If the two devices were in connection in the past, the client already knows what services and characteristics are there on the server. So the next time they connect, the client doesn't have to discover them all over again. This is however fully dependent on the implementation of the gut client. To allow or disallow bonding, we again use the ACA GUP Set Authentication Requirements API. Let's now have a look at how pairing is initiated. Gut server typically consists of one or more BLE services and each BLE service consists of one or more characteristic. The characteristic can have a property. For example, it can be read by the client or it can be written by the client. The characteristic value may require certain additional protections. For example, it can require the link is encrypted before the value can be read or it may require AuthenticEdit link, which means the link is encrypted plus the pairing method that was used provide protection against man in the middle attack. When security requirements are not met and the gut client tries to read the characteristic, the gut server returns error response. For example, insufficient encryption or insufficient authentication. Based on this, the client initiates pairing and when the link gets secured, it will read the characteristic value again with success. It's important to know that the list of characteristics and services is not considered confidential, so the discovery procedure shall be always permitted. It's only the characteristic value that may require certain additional measures. Let's describe it one more time. Let's assume we have a gut client on the phone and that we have a gut server on STM32WB. The gut client performs service and characteristic discovery and then it tries to read a characteristic that requires encrypted link. So the server returns insufficient encryption error response and the client initiates the pairing and establishes a secure link. Only then the gut server returns the characteristic value. The security requirements for characteristic value are defined when adding the characteristic to the gut server and you see the API that is used on the screen. The input parameter security permission can require authenticated link or encrypted link for read operation or write operation. Characteristic value can also require authorization by the user application before the value can be read or written. This is handled on the user application side unlike the security requirements which are handled by the BLE stack. If you have a look at the BLE specification you will see there are definition of security modes and security levels. Security mode one is the link layer security, so everything that we have discussed so far. Level one refers to no security, level two and three refers to legacy pairing and level four refers to secure simple pairing with its enhancement by the Diffie-Hall-Monkey agreement protocol. Security mode two is the data signing on the attribute protocol level and this is something we haven't discussed so far. It's used by the gut client when writing characteristic value to the gut server. The attribute value is appended by signature so the source of origin cannot be disputed. It's important to know that the data signing can happen only if the link is non-encrypted so the two security modes are mutually exclusive. However, for the data signing to take place both devices must have the CSR key which is one of the key that is distributed during pairing so the two devices must be paired but the link may not be encrypted. Attribute signing is only used by the signed write command which is issued by gut client. As you see at the bottom, the attribute value is appended by a 12 byte authentication signature. On the right side you see the architecture of the BLE stack as it's implemented on the Cortex M0+, and you see that the attribute protocol level stands well above the link layer and this is where the signature is checked. And here you see the API that is used by the gut client to perform signed write without response.