Jörg Küfen / BLE_API

fka mod

Fork of BLE_API by Bluetooth Low Energy

ble/SecurityManager.h@1074:1fedc77d9add, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:42 2016 +0000
Revision:
1074:1fedc77d9add
Parent:
1063:187f9929cb60
Child:
1075:0d0dafb54bc9
Synchronized with git rev cd809e2a

Author: Andres Amaya Garcia

Modify shutdown API and functionality



Modify the shutdown API to remove the static shutdown function in Gap,

SecurityManager, GattClient and GattServer. Futhermore, remove the static

references to Gap, SecurityManager, GattClient and GattServer objects inside

their own classes. The cleanup method is renamed to `reset()` and made public.

Finally, additional functionality is added to the reset implementation in

Gap.

Who changed what in which revision?

UserRevisionLine numberNew 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,
vcoubard 1048:efb29faf12fc 28 SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< Require no protection, open link. */
vcoubard 1048:efb29faf12fc 29 SECURITY_MODE_ENCRYPTION_NO_MITM, /**< Require encryption, but no MITM protection. */
vcoubard 1048:efb29faf12fc 30 SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< Require encryption and MITM protection. */
vcoubard 1048:efb29faf12fc 31 SECURITY_MODE_SIGNED_NO_MITM, /**< Require signing or encryption, but no MITM protection. */
vcoubard 1048:efb29faf12fc 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 /**
vcoubard 1048:efb29faf12fc 36 * @brief Defines possible security status or states.
rgrover1 716:11b41f651697 37 *
vcoubard 1048:efb29faf12fc 38 * @details Defines possible security status or 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 {
vcoubard 1048:efb29faf12fc 47 IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display only. */
vcoubard 1048:efb29faf12fc 48 IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and yes/no entry. */
vcoubard 1048:efb29faf12fc 49 IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */
rgrover1 716:11b41f651697 50 IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */
vcoubard 1048:efb29faf12fc 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.
vcoubard 1048:efb29faf12fc 97 * @param[in] iocaps To specify the I/O capabilities of this peripheral,
vcoubard 1048:efb29faf12fc 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) {
vcoubard 1048:efb29faf12fc 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
vcoubard 1048:efb29faf12fc 114 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API 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.
vcoubard 1048:efb29faf12fc 121 * @param[out] securityStatusP Security status.
rgrover1 716:11b41f651697 122 *
vcoubard 1057:93a9679d655c 123 * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
rgrover1 716:11b41f651697 124 */
rgrover1 716:11b41f651697 125 virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) {
vcoubard 1048:efb29faf12fc 126 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 127 (void)connectionHandle;
rgrover1 734:4872b70437ce 128 (void)securityStatusP;
rgrover1 734:4872b70437ce 129
vcoubard 1048:efb29faf12fc 130 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
rgrover1 716:11b41f651697 131 }
rgrover1 716:11b41f651697 132
rgrover1 716:11b41f651697 133 /**
vcoubard 1057:93a9679d655c 134 * Set the security mode on a connection. Useful for elevating the security mode
vcoubard 1057:93a9679d655c 135 * once certain conditions are met, e.g., a particular service is found.
vcoubard 1057:93a9679d655c 136 *
vcoubard 1057:93a9679d655c 137 * @param[in] connectionHandle Handle to identify the connection.
vcoubard 1057:93a9679d655c 138 * @param[in] securityMode Requested security mode.
vcoubard 1057:93a9679d655c 139 *
vcoubard 1057:93a9679d655c 140 * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
vcoubard 1057:93a9679d655c 141 */
vcoubard 1057:93a9679d655c 142 virtual ble_error_t setLinkSecurity(Gap::Handle_t connectionHandle, SecurityMode_t securityMode) {
vcoubard 1057:93a9679d655c 143 /* Avoid compiler warnings about unused variables. */
vcoubard 1057:93a9679d655c 144 (void)connectionHandle;
vcoubard 1057:93a9679d655c 145 (void)securityMode;
vcoubard 1057:93a9679d655c 146
vcoubard 1057:93a9679d655c 147 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1057:93a9679d655c 148 }
vcoubard 1057:93a9679d655c 149
vcoubard 1057:93a9679d655c 150 /**
rgrover1 716:11b41f651697 151 * Delete all peer device context and all related bonding information from
rgrover1 716:11b41f651697 152 * the database within the security manager.
rgrover1 716:11b41f651697 153 *
rgrover1 716:11b41f651697 154 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
vcoubard 1048:efb29faf12fc 155 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
rgrover1 716:11b41f651697 156 * application registration.
rgrover1 716:11b41f651697 157 */
rgrover1 716:11b41f651697 158 virtual ble_error_t purgeAllBondingState(void) {
vcoubard 1048:efb29faf12fc 159 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
rgrover1 716:11b41f651697 160 }
rgrover1 716:11b41f651697 161
rgrover1 716:11b41f651697 162 /* Event callback handlers. */
rgrover1 716:11b41f651697 163 public:
rgrover1 716:11b41f651697 164 /**
vcoubard 1048:efb29faf12fc 165 * To indicate that a security procedure for the link has started.
rgrover1 716:11b41f651697 166 */
rgrover1 716:11b41f651697 167 virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {securitySetupInitiatedCallback = callback;}
rgrover1 716:11b41f651697 168
rgrover1 716:11b41f651697 169 /**
vcoubard 1048:efb29faf12fc 170 * To indicate that the security procedure for the link has completed.
rgrover1 716:11b41f651697 171 */
rgrover1 716:11b41f651697 172 virtual void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback) {securitySetupCompletedCallback = callback;}
rgrover1 716:11b41f651697 173
rgrover1 716:11b41f651697 174 /**
vcoubard 1048:efb29faf12fc 175 * To indicate that the link with the peer is secured. For bonded devices,
vcoubard 1048:efb29faf12fc 176 * subsequent reconnections with a bonded peer will result only in this callback
vcoubard 1048:efb29faf12fc 177 * when the link is secured; setup procedures will not occur (unless the
vcoubard 1048:efb29faf12fc 178 * bonding information is either lost or deleted on either or both sides).
rgrover1 716:11b41f651697 179 */
rgrover1 716:11b41f651697 180 virtual void onLinkSecured(LinkSecuredCallback_t callback) {linkSecuredCallback = callback;}
rgrover1 716:11b41f651697 181
rgrover1 716:11b41f651697 182 /**
rgrover1 716:11b41f651697 183 * To indicate that device context is stored persistently.
rgrover1 716:11b41f651697 184 */
rgrover1 716:11b41f651697 185 virtual void onSecurityContextStored(HandleSpecificEvent_t callback) {securityContextStoredCallback = callback;}
rgrover1 716:11b41f651697 186
rgrover1 716:11b41f651697 187 /**
rgrover1 716:11b41f651697 188 * To set the callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability.
rgrover1 716:11b41f651697 189 */
rgrover1 716:11b41f651697 190 virtual void onPasskeyDisplay(PasskeyDisplayCallback_t callback) {passkeyDisplayCallback = callback;}
rgrover1 716:11b41f651697 191
rgrover1 716:11b41f651697 192 /* Entry points for the underlying stack to report events back to the user. */
rgrover1 716:11b41f651697 193 public:
rgrover1 716:11b41f651697 194 void processSecuritySetupInitiatedEvent(Gap::Handle_t handle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps) {
rgrover1 716:11b41f651697 195 if (securitySetupInitiatedCallback) {
rgrover1 716:11b41f651697 196 securitySetupInitiatedCallback(handle, allowBonding, requireMITM, iocaps);
rgrover1 716:11b41f651697 197 }
rgrover1 716:11b41f651697 198 }
rgrover1 716:11b41f651697 199
rgrover1 716:11b41f651697 200 void processSecuritySetupCompletedEvent(Gap::Handle_t handle, SecurityCompletionStatus_t status) {
rgrover1 716:11b41f651697 201 if (securitySetupCompletedCallback) {
rgrover1 716:11b41f651697 202 securitySetupCompletedCallback(handle, status);
rgrover1 716:11b41f651697 203 }
rgrover1 716:11b41f651697 204 }
rgrover1 716:11b41f651697 205
rgrover1 716:11b41f651697 206 void processLinkSecuredEvent(Gap::Handle_t handle, SecurityMode_t securityMode) {
rgrover1 716:11b41f651697 207 if (linkSecuredCallback) {
rgrover1 716:11b41f651697 208 linkSecuredCallback(handle, securityMode);
rgrover1 716:11b41f651697 209 }
rgrover1 716:11b41f651697 210 }
rgrover1 716:11b41f651697 211
rgrover1 716:11b41f651697 212 void processSecurityContextStoredEvent(Gap::Handle_t handle) {
rgrover1 716:11b41f651697 213 if (securityContextStoredCallback) {
rgrover1 716:11b41f651697 214 securityContextStoredCallback(handle);
rgrover1 716:11b41f651697 215 }
rgrover1 716:11b41f651697 216 }
rgrover1 716:11b41f651697 217
rgrover1 716:11b41f651697 218 void processPasskeyDisplayEvent(Gap::Handle_t handle, const Passkey_t passkey) {
rgrover1 716:11b41f651697 219 if (passkeyDisplayCallback) {
rgrover1 716:11b41f651697 220 passkeyDisplayCallback(handle, passkey);
rgrover1 716:11b41f651697 221 }
rgrover1 716:11b41f651697 222 }
rgrover1 716:11b41f651697 223
rgrover1 716:11b41f651697 224 protected:
rgrover1 716:11b41f651697 225 SecurityManager() :
rgrover1 716:11b41f651697 226 securitySetupInitiatedCallback(),
rgrover1 716:11b41f651697 227 securitySetupCompletedCallback(),
rgrover1 716:11b41f651697 228 linkSecuredCallback(),
rgrover1 716:11b41f651697 229 securityContextStoredCallback(),
rgrover1 716:11b41f651697 230 passkeyDisplayCallback() {
rgrover1 716:11b41f651697 231 /* empty */
rgrover1 716:11b41f651697 232 }
rgrover1 716:11b41f651697 233
vcoubard 1074:1fedc77d9add 234 public:
vcoubard 1074:1fedc77d9add 235 /**
vcoubard 1074:1fedc77d9add 236 * Clear all SecurityManager state of the associated object.
vcoubard 1074:1fedc77d9add 237 *
vcoubard 1074:1fedc77d9add 238 * This function is meant to be overridden in the platform-specific
vcoubard 1074:1fedc77d9add 239 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1074:1fedc77d9add 240 * state and not the data held in SecurityManager members. This shall be
vcoubard 1074:1fedc77d9add 241 * achieved by a call to SecurityManager::reset() from the sub-class'
vcoubard 1074:1fedc77d9add 242 * reset() implementation.
vcoubard 1074:1fedc77d9add 243 *
vcoubard 1074:1fedc77d9add 244 * @return BLE_ERROR_NONE on success.
vcoubard 1074:1fedc77d9add 245 */
vcoubard 1074:1fedc77d9add 246 virtual ble_error_t reset(void) {
vcoubard 1074:1fedc77d9add 247 securitySetupInitiatedCallback = NULL;
vcoubard 1074:1fedc77d9add 248 securitySetupCompletedCallback = NULL;
vcoubard 1074:1fedc77d9add 249 linkSecuredCallback = NULL;
vcoubard 1074:1fedc77d9add 250 securityContextStoredCallback = NULL;
vcoubard 1074:1fedc77d9add 251 passkeyDisplayCallback = NULL;
vcoubard 1074:1fedc77d9add 252
vcoubard 1074:1fedc77d9add 253 return BLE_ERROR_NONE;
vcoubard 1074:1fedc77d9add 254 }
vcoubard 1074:1fedc77d9add 255
rgrover1 716:11b41f651697 256 protected:
rgrover1 716:11b41f651697 257 SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
rgrover1 716:11b41f651697 258 SecuritySetupCompletedCallback_t securitySetupCompletedCallback;
rgrover1 716:11b41f651697 259 LinkSecuredCallback_t linkSecuredCallback;
rgrover1 716:11b41f651697 260 HandleSpecificEvent_t securityContextStoredCallback;
rgrover1 716:11b41f651697 261 PasskeyDisplayCallback_t passkeyDisplayCallback;
rgrover1 716:11b41f651697 262 };
rgrover1 716:11b41f651697 263
rgrover1 716:11b41f651697 264 #endif /*__SECURITY_MANAGER_H__*/