Andrew Fox / BLE_API

add "LE Device Address" 0x1B to advertising data types

Fork of BLE_API by Bluetooth Low Energy

ble/SecurityManager.h@993:4d62b7967c11, 2015-12-02 (annotated)

Committer:
rgrover1
Date:
Wed Dec 02 10:29:44 2015 +0000
Revision:
993:4d62b7967c11
Parent:
992:ca834f7ae8ed
Child:
1042:21a86ac7f5b1
Synchronized with git rev 12e27cd4

Author: Rohit Grover

Release 2.1.3

=============



* Improvements to CallChainOfFunctionPointerswithContext:

  - add a `detach` function to be able to remove callbacks.

  - detach function now return true if a function has been detached and

    false otherwise.

  - add a function call operator.

  - use safe-bool idiom. see : http://www.artima.com/cppsource/safebool.html



* Add SafeBool class which allow to easily declare a safe bool operator in

  c++03.



* Improvements to FunctionPointerWithContext:

  - fix call propagation

  - use safe bool idiom



* Add config file for generating Doxygen.



* Setup for onRadioNotification callback does not call initRadioNotification

  anymore.



* GapAdvertisementData now handles replacement and appending of data fields

  based on type. Some fields can be replaced with new values, and others

  require the payload to be appended.

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,
rgrover1 993:4d62b7967c11 28 SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< Require no protection, open link. */
rgrover1 993:4d62b7967c11 29 SECURITY_MODE_ENCRYPTION_NO_MITM, /**< Require encryption, but no MITM protection. */
rgrover1 993:4d62b7967c11 30 SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< Require encryption and MITM protection. */
rgrover1 993:4d62b7967c11 31 SECURITY_MODE_SIGNED_NO_MITM, /**< Require signing or encryption, but no MITM protection. */
rgrover1 993:4d62b7967c11 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 993:4d62b7967c11 36 * @brief Defines possible security status or states.
rgrover1 716:11b41f651697 37 *
rgrover1 993:4d62b7967c11 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 {
rgrover1 993:4d62b7967c11 47 IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display only. */
rgrover1 993:4d62b7967c11 48 IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and yes/no entry. */
rgrover1 993:4d62b7967c11 49 IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */
rgrover1 716:11b41f651697 50 IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */
rgrover1 993:4d62b7967c11 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 993:4d62b7967c11 97 * @param[in] iocaps To specify the I/O capabilities of this peripheral,
rgrover1 993:4d62b7967c11 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 993:4d62b7967c11 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 993:4d62b7967c11 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.
rgrover1 993:4d62b7967c11 121 * @param[out] securityStatusP Security status.
rgrover1 716:11b41f651697 122 *
rgrover1 993:4d62b7967c11 123 * @return BLE_SUCCESS 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) {
rgrover1 993:4d62b7967c11 126 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 127 (void)connectionHandle;
rgrover1 734:4872b70437ce 128 (void)securityStatusP;
rgrover1 734:4872b70437ce 129
rgrover1 993:4d62b7967c11 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 /**
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 993:4d62b7967c11 138 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
rgrover1 716:11b41f651697 139 * application registration.
rgrover1 716:11b41f651697 140 */
rgrover1 716:11b41f651697 141 virtual ble_error_t purgeAllBondingState(void) {
rgrover1 993:4d62b7967c11 142 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API 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 993:4d62b7967c11 148 * To indicate that a security procedure for the 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 993:4d62b7967c11 153 * To indicate that the security procedure for the 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 993:4d62b7967c11 158 * To indicate that the link with the peer is secured. For bonded devices,
rgrover1 993:4d62b7967c11 159 * subsequent reconnections with a bonded peer will result only in this callback
rgrover1 993:4d62b7967c11 160 * when the link is secured; setup procedures will not occur (unless the
rgrover1 993:4d62b7967c11 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__*/