Cristi Stoican / BLE_API

jgh

Dependents:   Migration

Fork of BLE_API by Bluetooth Low Energy

public/SecurityManager.h@546:9fdf3d960d12, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:09 2015 +0100
Revision:
546:9fdf3d960d12
Child:
560:ce6e36951457
Synchronized with git rev ebd6bbce

Author: Rohit Grover

introduce SecurityManager

Who changed what in which revision?

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