Oscar Ariza / BLE_API

BLE

Fork of BLE_API by Bluetooth Low Energy

public/SecurityManager.h@561:ce6e36951457, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:11 2015 +0100
Revision:
561:ce6e36951457
Parent:
547:9fdf3d960d12 
Synchronized with git rev 3a4a4c16

Author: Rohit Grover

SecurityManager: fix comments.

Who changed what in which revision?

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