add "LE Device Address" 0x1B to advertising data types
Fork of BLE_API by
ble/SecurityManager.h@734:4872b70437ce, 2015-07-06 (annotated)
- Committer:
- rgrover1
- Date:
- Mon Jul 06 10:10:35 2015 +0100
- Revision:
- 734:4872b70437ce
- Parent:
- 716:11b41f651697
- Child:
- 735:15bfcec377d5
Synchronized with git rev 163f9e01
Author: Rohit Grover
add empty (void) declarations for unused variables. This avoids warnings.
I could have used the compiler-polyfill module, but I wanted to avoid creating that dependency.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
rgrover1 | 716:11b41f651697 | 1 | /* mbed Microcontroller Library |
rgrover1 | 716:11b41f651697 | 2 | * Copyright (c) 2006-2015 ARM Limited |
rgrover1 | 716:11b41f651697 | 3 | * |
rgrover1 | 716:11b41f651697 | 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
rgrover1 | 716:11b41f651697 | 5 | * you may not use this file except in compliance with the License. |
rgrover1 | 716:11b41f651697 | 6 | * You may obtain a copy of the License at |
rgrover1 | 716:11b41f651697 | 7 | * |
rgrover1 | 716:11b41f651697 | 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
rgrover1 | 716:11b41f651697 | 9 | * |
rgrover1 | 716:11b41f651697 | 10 | * Unless required by applicable law or agreed to in writing, software |
rgrover1 | 716:11b41f651697 | 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
rgrover1 | 716:11b41f651697 | 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
rgrover1 | 716:11b41f651697 | 13 | * See the License for the specific language governing permissions and |
rgrover1 | 716:11b41f651697 | 14 | * limitations under the License. |
rgrover1 | 716:11b41f651697 | 15 | */ |
rgrover1 | 716:11b41f651697 | 16 | |
rgrover1 | 716:11b41f651697 | 17 | #ifndef __SECURITY_MANAGER_H__ |
rgrover1 | 716:11b41f651697 | 18 | #define __SECURITY_MANAGER_H__ |
rgrover1 | 716:11b41f651697 | 19 | |
rgrover1 | 716:11b41f651697 | 20 | #include <stdint.h> |
rgrover1 | 716:11b41f651697 | 21 | |
rgrover1 | 716:11b41f651697 | 22 | #include "Gap.h" |
rgrover1 | 716:11b41f651697 | 23 | |
rgrover1 | 716:11b41f651697 | 24 | class SecurityManager { |
rgrover1 | 716:11b41f651697 | 25 | public: |
rgrover1 | 716:11b41f651697 | 26 | enum SecurityMode_t { |
rgrover1 | 716:11b41f651697 | 27 | SECURITY_MODE_NO_ACCESS, |
rgrover1 | 716:11b41f651697 | 28 | SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< require no protection, open link. */ |
rgrover1 | 716:11b41f651697 | 29 | SECURITY_MODE_ENCRYPTION_NO_MITM, /**< require encryption, but no MITM protection. */ |
rgrover1 | 716:11b41f651697 | 30 | SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< require encryption and MITM protection. */ |
rgrover1 | 716:11b41f651697 | 31 | SECURITY_MODE_SIGNED_NO_MITM, /**< require signing or encryption, but no MITM protection. */ |
rgrover1 | 716:11b41f651697 | 32 | SECURITY_MODE_SIGNED_WITH_MITM, /**< require signing or encryption, and MITM protection. */ |
rgrover1 | 716:11b41f651697 | 33 | }; |
rgrover1 | 716:11b41f651697 | 34 | |
rgrover1 | 716:11b41f651697 | 35 | /** |
rgrover1 | 716:11b41f651697 | 36 | * @brief Defines possible security status/states. |
rgrover1 | 716:11b41f651697 | 37 | * |
rgrover1 | 716:11b41f651697 | 38 | * @details Defines possible security status/states of a link when requested by getLinkSecurity(). |
rgrover1 | 716:11b41f651697 | 39 | */ |
rgrover1 | 716:11b41f651697 | 40 | enum LinkSecurityStatus_t { |
rgrover1 | 716:11b41f651697 | 41 | NOT_ENCRYPTED, /**< The link is not secured. */ |
rgrover1 | 716:11b41f651697 | 42 | ENCRYPTION_IN_PROGRESS, /**< Link security is being established.*/ |
rgrover1 | 716:11b41f651697 | 43 | ENCRYPTED /**< The link is secure.*/ |
rgrover1 | 716:11b41f651697 | 44 | }; |
rgrover1 | 716:11b41f651697 | 45 | |
rgrover1 | 716:11b41f651697 | 46 | enum SecurityIOCapabilities_t { |
rgrover1 | 716:11b41f651697 | 47 | IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display Only. */ |
rgrover1 | 716:11b41f651697 | 48 | IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and Yes/No entry. */ |
rgrover1 | 716:11b41f651697 | 49 | IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard Only. */ |
rgrover1 | 716:11b41f651697 | 50 | IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */ |
rgrover1 | 716:11b41f651697 | 51 | IO_CAPS_KEYBOARD_DISPLAY = 0x04, /**< Keyboard and Display. */ |
rgrover1 | 716:11b41f651697 | 52 | }; |
rgrover1 | 716:11b41f651697 | 53 | |
rgrover1 | 716:11b41f651697 | 54 | enum SecurityCompletionStatus_t { |
rgrover1 | 716:11b41f651697 | 55 | SEC_STATUS_SUCCESS = 0x00, /**< Procedure completed with success. */ |
rgrover1 | 716:11b41f651697 | 56 | SEC_STATUS_TIMEOUT = 0x01, /**< Procedure timed out. */ |
rgrover1 | 716:11b41f651697 | 57 | SEC_STATUS_PDU_INVALID = 0x02, /**< Invalid PDU received. */ |
rgrover1 | 716:11b41f651697 | 58 | SEC_STATUS_PASSKEY_ENTRY_FAILED = 0x81, /**< Passkey entry failed (user canceled or other). */ |
rgrover1 | 716:11b41f651697 | 59 | SEC_STATUS_OOB_NOT_AVAILABLE = 0x82, /**< Out of Band Key not available. */ |
rgrover1 | 716:11b41f651697 | 60 | SEC_STATUS_AUTH_REQ = 0x83, /**< Authentication requirements not met. */ |
rgrover1 | 716:11b41f651697 | 61 | SEC_STATUS_CONFIRM_VALUE = 0x84, /**< Confirm value failed. */ |
rgrover1 | 716:11b41f651697 | 62 | SEC_STATUS_PAIRING_NOT_SUPP = 0x85, /**< Pairing not supported. */ |
rgrover1 | 716:11b41f651697 | 63 | SEC_STATUS_ENC_KEY_SIZE = 0x86, /**< Encryption key size. */ |
rgrover1 | 716:11b41f651697 | 64 | SEC_STATUS_SMP_CMD_UNSUPPORTED = 0x87, /**< Unsupported SMP command. */ |
rgrover1 | 716:11b41f651697 | 65 | SEC_STATUS_UNSPECIFIED = 0x88, /**< Unspecified reason. */ |
rgrover1 | 716:11b41f651697 | 66 | SEC_STATUS_REPEATED_ATTEMPTS = 0x89, /**< Too little time elapsed since last attempt. */ |
rgrover1 | 716:11b41f651697 | 67 | SEC_STATUS_INVALID_PARAMS = 0x8A, /**< Invalid parameters. */ |
rgrover1 | 716:11b41f651697 | 68 | }; |
rgrover1 | 716:11b41f651697 | 69 | |
rgrover1 | 716:11b41f651697 | 70 | /** |
rgrover1 | 716:11b41f651697 | 71 | * Declaration of type containing a passkey to be used during pairing. This |
rgrover1 | 716:11b41f651697 | 72 | * is passed into initializeSecurity() to specify a pre-programmed passkey |
rgrover1 | 716:11b41f651697 | 73 | * for authentication instead of generating a random one. |
rgrover1 | 716:11b41f651697 | 74 | */ |
rgrover1 | 716:11b41f651697 | 75 | static const unsigned PASSKEY_LEN = 6; |
rgrover1 | 716:11b41f651697 | 76 | typedef uint8_t Passkey_t[PASSKEY_LEN]; /**< 6-digit passkey in ASCII ('0'-'9' digits only). */ |
rgrover1 | 716:11b41f651697 | 77 | |
rgrover1 | 716:11b41f651697 | 78 | public: |
rgrover1 | 716:11b41f651697 | 79 | typedef void (*HandleSpecificEvent_t)(Gap::Handle_t handle); |
rgrover1 | 716:11b41f651697 | 80 | typedef void (*SecuritySetupInitiatedCallback_t)(Gap::Handle_t, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps); |
rgrover1 | 716:11b41f651697 | 81 | typedef void (*SecuritySetupCompletedCallback_t)(Gap::Handle_t, SecurityCompletionStatus_t status); |
rgrover1 | 716:11b41f651697 | 82 | typedef void (*LinkSecuredCallback_t)(Gap::Handle_t handle, SecurityMode_t securityMode); |
rgrover1 | 716:11b41f651697 | 83 | typedef void (*PasskeyDisplayCallback_t)(Gap::Handle_t handle, const Passkey_t passkey); |
rgrover1 | 716:11b41f651697 | 84 | |
rgrover1 | 716:11b41f651697 | 85 | /* |
rgrover1 | 716:11b41f651697 | 86 | * The following functions are meant to be overridden in the platform-specific sub-class. |
rgrover1 | 716:11b41f651697 | 87 | */ |
rgrover1 | 716:11b41f651697 | 88 | public: |
rgrover1 | 716:11b41f651697 | 89 | /** |
rgrover1 | 716:11b41f651697 | 90 | * Enable the BLE stack's Security Manager. The Security Manager implements |
rgrover1 | 716:11b41f651697 | 91 | * the actual cryptographic algorithms and protocol exchanges that allow two |
rgrover1 | 716:11b41f651697 | 92 | * devices to securely exchange data and privately detect each other. |
rgrover1 | 716:11b41f651697 | 93 | * Calling this API is a prerequisite for encryption and pairing (bonding). |
rgrover1 | 716:11b41f651697 | 94 | * |
rgrover1 | 716:11b41f651697 | 95 | * @param[in] enableBonding Allow for bonding. |
rgrover1 | 716:11b41f651697 | 96 | * @param[in] requireMITM Require protection for man-in-the-middle attacks. |
rgrover1 | 716:11b41f651697 | 97 | * @param[in] iocaps To specify IO capabilities of this peripheral, |
rgrover1 | 716:11b41f651697 | 98 | * such as availability of a display or keyboard to |
rgrover1 | 716:11b41f651697 | 99 | * support out-of-band exchanges of security data. |
rgrover1 | 716:11b41f651697 | 100 | * @param[in] passkey To specify a static passkey. |
rgrover1 | 716:11b41f651697 | 101 | * |
rgrover1 | 716:11b41f651697 | 102 | * @return BLE_ERROR_NONE on success. |
rgrover1 | 716:11b41f651697 | 103 | */ |
rgrover1 | 716:11b41f651697 | 104 | virtual ble_error_t init(bool enableBonding = true, |
rgrover1 | 716:11b41f651697 | 105 | bool requireMITM = true, |
rgrover1 | 716:11b41f651697 | 106 | SecurityIOCapabilities_t iocaps = IO_CAPS_NONE, |
rgrover1 | 716:11b41f651697 | 107 | const Passkey_t passkey = NULL) { |
rgrover1 | 734:4872b70437ce | 108 | /* avoid compiler warnings about unused variables */ |
rgrover1 | 734:4872b70437ce | 109 | (void)enableBonding; |
rgrover1 | 734:4872b70437ce | 110 | (void)requireMITM; |
rgrover1 | 734:4872b70437ce | 111 | (void)iocaps; |
rgrover1 | 734:4872b70437ce | 112 | (void)passkey; |
rgrover1 | 734:4872b70437ce | 113 | |
rgrover1 | 716:11b41f651697 | 114 | return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this if security is supported. */ |
rgrover1 | 716:11b41f651697 | 115 | } |
rgrover1 | 716:11b41f651697 | 116 | |
rgrover1 | 716:11b41f651697 | 117 | /** |
rgrover1 | 716:11b41f651697 | 118 | * Get the security status of a connection. |
rgrover1 | 716:11b41f651697 | 119 | * |
rgrover1 | 716:11b41f651697 | 120 | * @param[in] connectionHandle Handle to identify the connection. |
rgrover1 | 716:11b41f651697 | 121 | * @param[out] securityStatusP security status. |
rgrover1 | 716:11b41f651697 | 122 | * |
rgrover1 | 716:11b41f651697 | 123 | * @return BLE_SUCCESS Or appropriate error code indicating reason for failure. |
rgrover1 | 716:11b41f651697 | 124 | */ |
rgrover1 | 716:11b41f651697 | 125 | virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) { |
rgrover1 | 734:4872b70437ce | 126 | /* avoid compiler warnings about unused variables */ |
rgrover1 | 734:4872b70437ce | 127 | (void)connectionHandle; |
rgrover1 | 734:4872b70437ce | 128 | (void)securityStatusP; |
rgrover1 | 734:4872b70437ce | 129 | |
rgrover1 | 716:11b41f651697 | 130 | return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this if security is supported. */ |
rgrover1 | 716:11b41f651697 | 131 | } |
rgrover1 | 716:11b41f651697 | 132 | |
rgrover1 | 716:11b41f651697 | 133 | /** |
rgrover1 | 716:11b41f651697 | 134 | * Delete all peer device context and all related bonding information from |
rgrover1 | 716:11b41f651697 | 135 | * the database within the security manager. |
rgrover1 | 716:11b41f651697 | 136 | * |
rgrover1 | 716:11b41f651697 | 137 | * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure. |
rgrover1 | 716:11b41f651697 | 138 | * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or |
rgrover1 | 716:11b41f651697 | 139 | * application registration. |
rgrover1 | 716:11b41f651697 | 140 | */ |
rgrover1 | 716:11b41f651697 | 141 | virtual ble_error_t purgeAllBondingState(void) { |
rgrover1 | 716:11b41f651697 | 142 | return BLE_ERROR_NOT_IMPLEMENTED; /* default implementation; override this if security is supported. */ |
rgrover1 | 716:11b41f651697 | 143 | } |
rgrover1 | 716:11b41f651697 | 144 | |
rgrover1 | 716:11b41f651697 | 145 | /* Event callback handlers. */ |
rgrover1 | 716:11b41f651697 | 146 | public: |
rgrover1 | 716:11b41f651697 | 147 | /** |
rgrover1 | 716:11b41f651697 | 148 | * To indicate that security procedure for link has started. |
rgrover1 | 716:11b41f651697 | 149 | */ |
rgrover1 | 716:11b41f651697 | 150 | virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {securitySetupInitiatedCallback = callback;} |
rgrover1 | 716:11b41f651697 | 151 | |
rgrover1 | 716:11b41f651697 | 152 | /** |
rgrover1 | 716:11b41f651697 | 153 | * To indicate that security procedure for link has completed. |
rgrover1 | 716:11b41f651697 | 154 | */ |
rgrover1 | 716:11b41f651697 | 155 | virtual void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback) {securitySetupCompletedCallback = callback;} |
rgrover1 | 716:11b41f651697 | 156 | |
rgrover1 | 716:11b41f651697 | 157 | /** |
rgrover1 | 716:11b41f651697 | 158 | * To indicate that link with the peer is secured. For bonded devices, |
rgrover1 | 716:11b41f651697 | 159 | * subsequent re-connections with bonded peer will result only in this callback |
rgrover1 | 716:11b41f651697 | 160 | * when the link is secured and setup procedures will not occur unless the |
rgrover1 | 716:11b41f651697 | 161 | * bonding information is either lost or deleted on either or both sides. |
rgrover1 | 716:11b41f651697 | 162 | */ |
rgrover1 | 716:11b41f651697 | 163 | virtual void onLinkSecured(LinkSecuredCallback_t callback) {linkSecuredCallback = callback;} |
rgrover1 | 716:11b41f651697 | 164 | |
rgrover1 | 716:11b41f651697 | 165 | /** |
rgrover1 | 716:11b41f651697 | 166 | * To indicate that device context is stored persistently. |
rgrover1 | 716:11b41f651697 | 167 | */ |
rgrover1 | 716:11b41f651697 | 168 | virtual void onSecurityContextStored(HandleSpecificEvent_t callback) {securityContextStoredCallback = callback;} |
rgrover1 | 716:11b41f651697 | 169 | |
rgrover1 | 716:11b41f651697 | 170 | /** |
rgrover1 | 716:11b41f651697 | 171 | * To set the callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability. |
rgrover1 | 716:11b41f651697 | 172 | */ |
rgrover1 | 716:11b41f651697 | 173 | virtual void onPasskeyDisplay(PasskeyDisplayCallback_t callback) {passkeyDisplayCallback = callback;} |
rgrover1 | 716:11b41f651697 | 174 | |
rgrover1 | 716:11b41f651697 | 175 | /* Entry points for the underlying stack to report events back to the user. */ |
rgrover1 | 716:11b41f651697 | 176 | public: |
rgrover1 | 716:11b41f651697 | 177 | void processSecuritySetupInitiatedEvent(Gap::Handle_t handle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps) { |
rgrover1 | 716:11b41f651697 | 178 | if (securitySetupInitiatedCallback) { |
rgrover1 | 716:11b41f651697 | 179 | securitySetupInitiatedCallback(handle, allowBonding, requireMITM, iocaps); |
rgrover1 | 716:11b41f651697 | 180 | } |
rgrover1 | 716:11b41f651697 | 181 | } |
rgrover1 | 716:11b41f651697 | 182 | |
rgrover1 | 716:11b41f651697 | 183 | void processSecuritySetupCompletedEvent(Gap::Handle_t handle, SecurityCompletionStatus_t status) { |
rgrover1 | 716:11b41f651697 | 184 | if (securitySetupCompletedCallback) { |
rgrover1 | 716:11b41f651697 | 185 | securitySetupCompletedCallback(handle, status); |
rgrover1 | 716:11b41f651697 | 186 | } |
rgrover1 | 716:11b41f651697 | 187 | } |
rgrover1 | 716:11b41f651697 | 188 | |
rgrover1 | 716:11b41f651697 | 189 | void processLinkSecuredEvent(Gap::Handle_t handle, SecurityMode_t securityMode) { |
rgrover1 | 716:11b41f651697 | 190 | if (linkSecuredCallback) { |
rgrover1 | 716:11b41f651697 | 191 | linkSecuredCallback(handle, securityMode); |
rgrover1 | 716:11b41f651697 | 192 | } |
rgrover1 | 716:11b41f651697 | 193 | } |
rgrover1 | 716:11b41f651697 | 194 | |
rgrover1 | 716:11b41f651697 | 195 | void processSecurityContextStoredEvent(Gap::Handle_t handle) { |
rgrover1 | 716:11b41f651697 | 196 | if (securityContextStoredCallback) { |
rgrover1 | 716:11b41f651697 | 197 | securityContextStoredCallback(handle); |
rgrover1 | 716:11b41f651697 | 198 | } |
rgrover1 | 716:11b41f651697 | 199 | } |
rgrover1 | 716:11b41f651697 | 200 | |
rgrover1 | 716:11b41f651697 | 201 | void processPasskeyDisplayEvent(Gap::Handle_t handle, const Passkey_t passkey) { |
rgrover1 | 716:11b41f651697 | 202 | if (passkeyDisplayCallback) { |
rgrover1 | 716:11b41f651697 | 203 | passkeyDisplayCallback(handle, passkey); |
rgrover1 | 716:11b41f651697 | 204 | } |
rgrover1 | 716:11b41f651697 | 205 | } |
rgrover1 | 716:11b41f651697 | 206 | |
rgrover1 | 716:11b41f651697 | 207 | protected: |
rgrover1 | 716:11b41f651697 | 208 | SecurityManager() : |
rgrover1 | 716:11b41f651697 | 209 | securitySetupInitiatedCallback(), |
rgrover1 | 716:11b41f651697 | 210 | securitySetupCompletedCallback(), |
rgrover1 | 716:11b41f651697 | 211 | linkSecuredCallback(), |
rgrover1 | 716:11b41f651697 | 212 | securityContextStoredCallback(), |
rgrover1 | 716:11b41f651697 | 213 | passkeyDisplayCallback() { |
rgrover1 | 716:11b41f651697 | 214 | /* empty */ |
rgrover1 | 716:11b41f651697 | 215 | } |
rgrover1 | 716:11b41f651697 | 216 | |
rgrover1 | 716:11b41f651697 | 217 | protected: |
rgrover1 | 716:11b41f651697 | 218 | SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback; |
rgrover1 | 716:11b41f651697 | 219 | SecuritySetupCompletedCallback_t securitySetupCompletedCallback; |
rgrover1 | 716:11b41f651697 | 220 | LinkSecuredCallback_t linkSecuredCallback; |
rgrover1 | 716:11b41f651697 | 221 | HandleSpecificEvent_t securityContextStoredCallback; |
rgrover1 | 716:11b41f651697 | 222 | PasskeyDisplayCallback_t passkeyDisplayCallback; |
rgrover1 | 716:11b41f651697 | 223 | }; |
rgrover1 | 716:11b41f651697 | 224 | |
rgrover1 | 716:11b41f651697 | 225 | #endif /*__SECURITY_MANAGER_H__*/ |