1# ESP32 Classic Bluetooth Security - Secure Simple Pairing 2 3This document briefly describes how the device io capability and security mask affect the process of the Secure Simple Pairing. It will help you figure out how to set the parameter when calling `esp_bt_gap_set_security_param`, or the parameter `sec_mask` when you want to establish a connection associate a certain profile, for example, an SPP connection. 4 5## IO Capability 6Input and output capabilities of a device are combined to generate its IO capabilities. The input capabilities are described in Table 1 The output capabilities are described in Table 2. Table 3 shows the combination of Input and Output Capability, which are defined as `ESP_BT_IO_CAP_OUT`, `ESP_BT_IO_CAP_IO`, `ESP_BT_IO_CAP_IN` and `ESP_BT_IO_CAP_NONE` in `esp_gap_bt_api.h`. 7 8| Input Capability | Description | 9| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 10| No input | Device does not have the ability to indicate 'yes' or 'no' | 11| Yes / No | Device has at least two buttons that can be easily mapped to 'yes' and 'no' or the device has a mechanism whereby the user can indicate either 'yes' or 'no' (see note below). | 12| Keyboard | Device has a numeric keyboard that can input the numbers '0' through '9' and a confirmation. Device also has two buttons that can be easily mapped to 'yes' and 'no' or the device has a mechanism whereby the user can indicate either 'yes' or 'no' (see Note below). | 13*Table 1 User Input Capability* 14**Note**: 'yes' could be indicated by pressing a button within a certain time limit otherwise 'no' would be assumed. 15 16| Output Capability | Description | 17| ----------------- | ----------------------------------------------------------------------------------- | 18| No output | Device does not have the ability to display or communicate a 6 digit decimal number | 19| Numeric output | Device has the ability to display or communicate a 6 digit decimal number | 20*Table 2 User Output Capability* 21 22| | No Output | Numeric Output | 23| -------- | -------------------------------------- | --------------------------------- | 24| No input | NoInputNoOutput (`ESP_BT_IO_CAP_NONE`) | DisplayOnly (`ESP_BT_IO_CAP_OUT`) | 25| Yes / No | NoInputNoOutput (`ESP_BT_IO_CAP_NONE`) | DisplayYesNo (`ESP_BT_IO_CAP_IO`) | 26| Keyboard | KeyboardOnly (`ESP_BT_IO_CAP_IN`) | DisplayYesNo (`ESP_BT_IO_CAP_IO`) | 27*Table 3 IO Capability Mapping* 28 29## Secure Simple Pairing 30The primary goal of Secure Simple Pairing is to simplify the pairing procedure for the user. Secondary goals are to protect against passive eavesdropping and man-in-the-middle (MITM) attacks (active eavesdropping). It uses four association models referred to as Numeric Comparison, Just Works, Out Of Band, and Passkey Entry. 31* Numeric Comparison: both devices are capable of displaying a six digit number and both are capable of having the user enter "yes" or "no" 32* Just Works: at least one of the devices does not have a display capable of displaying a six digit number nor does it have a keyboard capable of entering six decimal digits 33* Out Of Band: use Out of Band mechanism to discover the devices and transfer cryptographic numbers 34* Passkey Entry: one device has input capability but does not have the capability to display six digits and the other device has output capabilities. 35 36**Note**: Just Works can be considered as a special kind of Numeric Comparison with automatic accept allowed. 37 38There are four stages defined in the Secure Simple Pairing LM process: 39* IO Capability exchange 40* Public key exchange 41* Authentication stage 1 42* Authentication stage 2 43 44### IO Capability Exchange 45The IO_Capability_Request_Reply command is used to reply to an IO Capability Request event from the controller, and specifies the current I/O capabilities of the host. The content of this command is shown as Table 4. 46| Command | OCF | Command Parameters | Return Parameters | 47| ------------------------------- | ------ | ------------------------------------------------------------------------------ | ------------------ | 48| HCI_IO_Capability_Request_Reply | 0x002B | BD_ADDR,<br>IO_Capability,<br>OOB_Data_Present,<br>Authentication_Requirements | Status,<br>BD_ADDR | 49*Table 4 IO_Capability_Request_Reply command* 50 51### Authentication Requirements 52If an authenticated link key is not required by the Host, the Authentication Requirements parameter may be set to one of the following: 53* MITM Protection Not Required – No Bonding 54* MITM Protection Not Required – Dedicated Bonding 55* MITM Protection Not Required – General Bonding 56 57**Note**: If both Hosts set the Authentication_Requirements parameter to one of the above values, the Link Managers shall use the numeric comparison authentication procedure and the hosts shall use the Just Works Association Model. 58 59If an authenticated link key is required by the Host, the Authentication Requirements parameter shall be set to one of the following: 60* MITM Protection Required – No Bonding 61* MITM Protection Required – Dedicated Bonding 62* MITM Protection Required – General Bonding 63 64**Note**: In addition, the following requirements apply: 651. If one or both hosts set the Authentication Requirements parameter to one of the above values, the Link Managers shall use the IO_Capability parameter to determine the authentication procedure. 662. A Host that sets the Authentication_Requirements parameter to one of the above values shall verify that the resulting Link Key type meets the security requirements requested. 67 68### IO Capability and Authentication Procedure Mapping 69If one or both devices have set the Authentication_Requirements parameter to one of the MITM Protection Required options, the IO capabilities are mapped to the authentication method as defined in the following table. A host has set the MITM Protection Required options shall verify that the resulting Link Key is an Authenticated Combination Key. 70<table> 71 <tr> 72 <th ></th> 73 <th colspan = "4" bgcolor="#1FB0E6">Responder</th> 74 </tr> 75 <tr> 76 <th bgcolor="#C8E6F8">Initiator</th> 77 <th bgcolor="#1FB0E6">DisplayOnly</th> 78 <th bgcolor="#1FB0E6">DisplayYesNo</th> 79 <th bgcolor="#1FB0E6">KeyboardOnly</th> 80 <th bgcolor="#1FB0E6">NoInputNoOutput</th> 81 </tr> 82 <tr> 83 <th bgcolor="#C8E6F8">DisplayOnly</th> 84 <td>Just Works<br><br>Unauthenticated</td> 85 <td>Just Works<br><br>Unauthenticated</td> 86 <td>Passkey Entry<br><br>Authenticated</td> 87 <td>Just Works<br><br>Unauthenticated</td> 88 </tr> 89 <tr> 90 <th bgcolor="#C8E6F8">DisplayYesNo</th> 91 <td>Just Works<br><br>Unauthenticated</td> 92 <td>Numeric Comparison<br><br>Authenticated</td> 93 <td>Passkey Entry<br><br>Authenticated</td> 94 <td>Just Works<br><br>Unauthenticated</td> 95 </tr> 96 <tr> 97 <th bgcolor="#C8E6F8">KeyboardOnly</th> 98 <td>Passkey Entry<br><br>Authenticated</td> 99 <td>Passkey Entry<br><br>Authenticated</td> 100 <td>Passkey Entry(both need enter)<br><br>Authenticated</td> 101 <td>Just Works<br><br>Unauthenticated</td> 102 </tr> 103 <tr> 104 <th bgcolor="#C8E6F8">NoInputNoOutput</th> 105 <td>Just Works<br><br>Unauthenticated</td> 106 <td>Just Works<br><br>Unauthenticated</td> 107 <td>Just Works<br><br>Unauthenticated</td> 108 <td>Just Works<br><br>Unauthenticated</td> 109 </tr> 110</table> 111 112*Table 5 IO Capability and Authentication Procedure Mapping* 113 114## Security Mask 115Security Mask has two function. First, to decide whether or not required MITM protection for Authentication_Requirements parameter. Second, to set the security level for authentication stage. On ESP32, the Security Masks for A2DP and HFP are hard coded with `BTA_SEC_AUTHENTICATE` and `(BTA_SEC_AUTHENTICATE|BTA_SEC_ENCRYPT)`. The following table shows `sec_mask` value for SPP and its definition in BTA layer of ESP32 Bluetooth stack. 116 117| SPP sec_mask | BTA layer sec_mask | value | Description | 118| -------------------------- | ---------------------- | ------ | ----------------------------------------------------------------------------------------- | 119| `ESP_SPP_SEC_NONE` | `BTA_SEC_NONE` | 0x0000 | No security | 120| `ESP_SPP_SEC_AUTHORIZE` | `BTA_SEC_AUTHORIZE` | 0x0001 | Authorization required (only needed for out going connection)<br>(not support) | 121| `ESP_SPP_SEC_AUTHENTICATE` | `BTA_SEC_AUTHENTICATE` | 0x0012 | Authentication required | 122| `ESP_SPP_SEC_ENCRYPT` | `BTA_SEC_ENCRYPT` | 0x0024 | Encryption required | 123| `ESP_SPP_SEC_MODE4_LEVEL4` | `BTA_SEC_MODE4_LEVEL4` | 0x0040 | Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption<br>(not support) | 124| `ESP_SPP_SEC_MITM` | `BTA_SEC_MITM` | 0x3000 | Man-In-The_Middle protection | 125| `ESP_SPP_SEC_IN_16_DIGITS` | `BTA_SEC_IN_16_DIGITS` | 0x4000 | Min 16 digit for pin code | 126*Table 6 ESP32 SPP Security Mask* 127 128**Note**: 1291. When `ESP_SPP_SEC_AUTHENTICATE` is set, then Security Manager set `ESP_SPP_SEC_MITM` automatically. 1302. When `ESP_SPP_SEC_ENCRYPT` is set, then Security Manager set `ESP_SPP_SEC_AUTHENTICATE` automatically. 131 132## Security Mode 4 133The ESP32 Security Manager supports Security Mode 4 which means that it enforces security requirements before it attempts to access services offered by a remote device and before it grants access to services it offers to remote devices. Security Mode 4 has 4 level of security. 134 135<table> 136 <tr> 137 <th width='200'>Security Level Required for Service</th> 138 <th>Link Key type required for remote devices</th> 139 <th width='200'>Comments</th> 140 <th width='200'>IO Capability & Security Mask Setting</th> 141 </tr> 142 <tr> 143 <td><b>Level 4(not support)</b><br>* MITM protection required<br>* Encryption required<br>* User interaction acceptable</td> 144 <td>Authenticated (P-256 based Secure Simple Pairing and Secure Authentication)</td> 145 <td>Highest Security Only possible when both devices support Secure Connections</td> 146 <td>/</td> 147 </tr> 148 <tr> 149 <td><b>Level 3</b><br>* MITM protection required<br>* Encryption required<br>* User interaction acceptable</td> 150 <td>Authenticated</td> 151 <td>High Security</td> 152 <td>IO: >= DisplayYesNo <br>Mask: ESP_SPP_SEC_MITM | BTA_SEC_ENCRYPT</td> 153 </tr> 154 <tr> 155 <td><b>Level 2</b><br>* MITM protection not necessary<br>* Encryption desired</td> 156 <td>Unauthenticated</td> 157 <td>Medium Security</td> 158 <td>IO: >= DisplayYesNo <br>Mask: BTA_SEC_ENCRYPT</td> 159 </tr> 160 <tr> 161 <td><b>Level 1</b><br>* MITM protection not necessary<br>* Encryption desired<br>* Minimal user interaction desired</td> 162 <td>Unauthenticated</td> 163 <td>Low Security</td> 164 <td>IO: >= NoInputNoOutput <br>Mask: BTA_SEC_ENCRYPT</td> 165 </tr> 166 <tr> 167 <td><b>Level 0</b><br>* MITM protection not necessary<br>* Encryption not necessary<br>* No user interaction desired</td> 168 <td>None</td> 169 <td>Permitted only for SDP and service data sent via either L2CAP fixed signaling channels or the L2CAP connectionless channel to PSMs that correspond to service class UUIDs which are allowed to utilize Level 0.</td> 170 <td>/</td> 171 </tr> 172</table> 173 174*Table 7 Security Mode 4 Security Level mapping to link key requirements* 175 176**Note**: Security Mode 4 always requires **authentication** and **encryption** over establishment of L2CAP connection on ESP32. 177 178 179ESP32 Secure Simple Pairing performs legacy authentication which means mutual authentication is achieved by first performing the authentication procedure in one direction and then immediately performing the authentication procedure in the opposite direction. So, when the initiator does not require MITM protection, the generated link key type in this direction is unauthenticated. In other direction, if the responder need MITM protection and have the `sec_mask` of `ESP_SPP_SEC_AUTHENTICATE`, then the unauthenticated link key will be regenerated and upgraded to an authenticated one. Each time the link key is regenerated, user will receive a `ESP_BT_GAP_AUTH_CMPL_EVT` event. 180
