Jörg Küfen / BLE_API

fka mod

Fork of BLE_API by Bluetooth Low Energy

ble/SecurityManager.h@912:f728aa46e7df, 2015-11-26 (annotated)

Committer:
rgrover1
Date:
Thu Nov 26 12:52:03 2015 +0000
Revision:
912:f728aa46e7df
Parent:
909:ca174e3a1385
Child:
913:690bea02c431
Synchronized with git rev 562aa49e

Author: Rohit Grover

delete an incorrect comment from the documentation in Gap.h

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 912:f728aa46e7df 28 SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< require no protection, open link. */
rgrover1 912:f728aa46e7df 29 SECURITY_MODE_ENCRYPTION_NO_MITM, /**< require encryption, but no MITM protection. */
rgrover1 912:f728aa46e7df 30 SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< require encryption and MITM protection. */
rgrover1 912:f728aa46e7df 31 SECURITY_MODE_SIGNED_NO_MITM, /**< require signing or encryption, but no MITM protection. */
rgrover1 912:f728aa46e7df 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 912:f728aa46e7df 36 * @brief Defines possible security status/states.
rgrover1 716:11b41f651697 37 *
rgrover1 912:f728aa46e7df 38 * @details Defines possible security status/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 912:f728aa46e7df 47 IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display Only. */
rgrover1 912:f728aa46e7df 48 IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and Yes/No entry. */
rgrover1 912:f728aa46e7df 49 IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard Only. */
rgrover1 716:11b41f651697 50 IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */
rgrover1 912:f728aa46e7df 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 912:f728aa46e7df 97 * @param[in] iocaps To specify IO capabilities of this peripheral,
rgrover1 912:f728aa46e7df 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 912:f728aa46e7df 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 912:f728aa46e7df 114 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): 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 912:f728aa46e7df 121 * @param[out] securityStatusP security status.
rgrover1 716:11b41f651697 122 *
rgrover1 912:f728aa46e7df 123 * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
rgrover1 716:11b41f651697 124 */
rgrover1 716:11b41f651697 125 virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) {
rgrover1 912:f728aa46e7df 126 /* avoid compiler warnings about unused variables */
rgrover1 734:4872b70437ce 127 (void)connectionHandle;
rgrover1 734:4872b70437ce 128 (void)securityStatusP;
rgrover1 734:4872b70437ce 129
rgrover1 912:f728aa46e7df 130 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): 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 912:f728aa46e7df 138 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or
rgrover1 716:11b41f651697 139 * application registration.
rgrover1 716:11b41f651697 140 */
rgrover1 716:11b41f651697 141 virtual ble_error_t purgeAllBondingState(void) {
rgrover1 912:f728aa46e7df 142 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): 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 912:f728aa46e7df 148 * To indicate that security procedure for 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 912:f728aa46e7df 153 * To indicate that security procedure for 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 912:f728aa46e7df 158 * To indicate that link with the peer is secured. For bonded devices,
rgrover1 912:f728aa46e7df 159 * subsequent re-connections with bonded peer will result only in this callback
rgrover1 912:f728aa46e7df 160 * when the link is secured and setup procedures will not occur unless the
rgrover1 912:f728aa46e7df 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__*/