Lancaster University / BLE_API

Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API

Dependents:   microbit-dal microbit-dal microbit-ble-open microbit-dal ... more

Fork of BLE_API by Bluetooth Low Energy

ble/SecurityManager.h@1131:73c11a85c6d6, 2016-04-06 (annotated)

Committer:
LancasterUniversity
Date:
Wed Apr 06 18:40:26 2016 +0100
Revision:
1131:73c11a85c6d6
Parent:
1129:85ee56c4f469
Child:
1137:290d499dd0e8
Synchronized with git rev 13bf70b6

Author: Rohit Grover

Release 2.1.5

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



A minor release to separate the concept of minlen and len in

GattCharacteristic. Also contains some improvements to documentation.

Who changed what in which revision?

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