Oscar Ariza / BLE_API

BLE

Fork of BLE_API by Bluetooth Low Energy

ble/SecurityManager.h@1090:8e810a8e083e, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:49 2016 +0000
Revision:
1090:8e810a8e083e
Parent:
1089:709ebced28ab
Child:
1091:148d8b9b56a5
Synchronized with git rev 65ed5c13

Author: Vincent Coubard

Merge pull request #145 from rgrover/develop



transparenly support existing applications which may have used Gap::ADDR_TYPE_*

Who changed what in which revision?

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