Matthew Lister / BLE_API

BLE_API

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

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