Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of LinkNode-Test by
SecurityManager.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2015 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef __SECURITY_MANAGER_H__ 00018 #define __SECURITY_MANAGER_H__ 00019 00020 #include <stdint.h> 00021 00022 #include "Gap.h" 00023 00024 class SecurityManager { 00025 public: 00026 enum SecurityMode_t { 00027 SECURITY_MODE_NO_ACCESS, 00028 SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< Require no protection, open link. */ 00029 SECURITY_MODE_ENCRYPTION_NO_MITM, /**< Require encryption, but no MITM protection. */ 00030 SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< Require encryption and MITM protection. */ 00031 SECURITY_MODE_SIGNED_NO_MITM, /**< Require signing or encryption, but no MITM protection. */ 00032 SECURITY_MODE_SIGNED_WITH_MITM, /**< Require signing or encryption, and MITM protection. */ 00033 }; 00034 00035 /** 00036 * @brief Defines possible security status or states. 00037 * 00038 * @details Defines possible security status or states of a link when requested by getLinkSecurity(). 00039 */ 00040 enum LinkSecurityStatus_t { 00041 NOT_ENCRYPTED, /**< The link is not secured. */ 00042 ENCRYPTION_IN_PROGRESS, /**< Link security is being established.*/ 00043 ENCRYPTED /**< The link is secure.*/ 00044 }; 00045 00046 enum SecurityIOCapabilities_t { 00047 IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display only. */ 00048 IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and yes/no entry. */ 00049 IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */ 00050 IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */ 00051 IO_CAPS_KEYBOARD_DISPLAY = 0x04, /**< Keyboard and display. */ 00052 }; 00053 00054 enum SecurityCompletionStatus_t { 00055 SEC_STATUS_SUCCESS = 0x00, /**< Procedure completed with success. */ 00056 SEC_STATUS_TIMEOUT = 0x01, /**< Procedure timed out. */ 00057 SEC_STATUS_PDU_INVALID = 0x02, /**< Invalid PDU received. */ 00058 SEC_STATUS_PASSKEY_ENTRY_FAILED = 0x81, /**< Passkey entry failed (user canceled or other). */ 00059 SEC_STATUS_OOB_NOT_AVAILABLE = 0x82, /**< Out of Band Key not available. */ 00060 SEC_STATUS_AUTH_REQ = 0x83, /**< Authentication requirements not met. */ 00061 SEC_STATUS_CONFIRM_VALUE = 0x84, /**< Confirm value failed. */ 00062 SEC_STATUS_PAIRING_NOT_SUPP = 0x85, /**< Pairing not supported. */ 00063 SEC_STATUS_ENC_KEY_SIZE = 0x86, /**< Encryption key size. */ 00064 SEC_STATUS_SMP_CMD_UNSUPPORTED = 0x87, /**< Unsupported SMP command. */ 00065 SEC_STATUS_UNSPECIFIED = 0x88, /**< Unspecified reason. */ 00066 SEC_STATUS_REPEATED_ATTEMPTS = 0x89, /**< Too little time elapsed since last attempt. */ 00067 SEC_STATUS_INVALID_PARAMS = 0x8A, /**< Invalid parameters. */ 00068 }; 00069 00070 /** 00071 * Declaration of type containing a passkey to be used during pairing. This 00072 * is passed into initializeSecurity() to specify a pre-programmed passkey 00073 * for authentication instead of generating a random one. 00074 */ 00075 static const unsigned PASSKEY_LEN = 6; 00076 typedef uint8_t Passkey_t[PASSKEY_LEN]; /**< 6-digit passkey in ASCII ('0'-'9' digits only). */ 00077 00078 public: 00079 typedef void (*HandleSpecificEvent_t)(Gap::Handle_t handle); 00080 typedef void (*SecuritySetupInitiatedCallback_t)(Gap::Handle_t, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps); 00081 typedef void (*SecuritySetupCompletedCallback_t)(Gap::Handle_t, SecurityCompletionStatus_t status); 00082 typedef void (*LinkSecuredCallback_t)(Gap::Handle_t handle, SecurityMode_t securityMode); 00083 typedef void (*PasskeyDisplayCallback_t)(Gap::Handle_t handle, const Passkey_t passkey); 00084 00085 /* 00086 * The following functions are meant to be overridden in the platform-specific sub-class. 00087 */ 00088 public: 00089 /** 00090 * Enable the BLE stack's Security Manager. The Security Manager implements 00091 * the actual cryptographic algorithms and protocol exchanges that allow two 00092 * devices to securely exchange data and privately detect each other. 00093 * Calling this API is a prerequisite for encryption and pairing (bonding). 00094 * 00095 * @param[in] enableBonding Allow for bonding. 00096 * @param[in] requireMITM Require protection for man-in-the-middle attacks. 00097 * @param[in] iocaps To specify the I/O capabilities of this peripheral, 00098 * such as availability of a display or keyboard, to 00099 * support out-of-band exchanges of security data. 00100 * @param[in] passkey To specify a static passkey. 00101 * 00102 * @return BLE_ERROR_NONE on success. 00103 */ 00104 virtual ble_error_t init(bool enableBonding = true, 00105 bool requireMITM = true, 00106 SecurityIOCapabilities_t iocaps = IO_CAPS_NONE, 00107 const Passkey_t passkey = NULL) { 00108 /* Avoid compiler warnings about unused variables. */ 00109 (void)enableBonding; 00110 (void)requireMITM; 00111 (void)iocaps; 00112 (void)passkey; 00113 00114 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */ 00115 } 00116 00117 /** 00118 * Get the security status of a connection. 00119 * 00120 * @param[in] connectionHandle Handle to identify the connection. 00121 * @param[out] securityStatusP Security status. 00122 * 00123 * @return BLE_SUCCESS or appropriate error code indicating the failure reason. 00124 */ 00125 virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) { 00126 /* Avoid compiler warnings about unused variables. */ 00127 (void)connectionHandle; 00128 (void)securityStatusP; 00129 00130 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */ 00131 } 00132 00133 /** 00134 * Delete all peer device context and all related bonding information from 00135 * the database within the security manager. 00136 * 00137 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure. 00138 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or 00139 * application registration. 00140 */ 00141 virtual ble_error_t purgeAllBondingState(void) { 00142 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */ 00143 } 00144 00145 /* Event callback handlers. */ 00146 public: 00147 /** 00148 * To indicate that a security procedure for the link has started. 00149 */ 00150 virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {securitySetupInitiatedCallback = callback;} 00151 00152 /** 00153 * To indicate that the security procedure for the link has completed. 00154 */ 00155 virtual void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback) {securitySetupCompletedCallback = callback;} 00156 00157 /** 00158 * To indicate that the link with the peer is secured. For bonded devices, 00159 * subsequent reconnections with a bonded peer will result only in this callback 00160 * when the link is secured; setup procedures will not occur (unless the 00161 * bonding information is either lost or deleted on either or both sides). 00162 */ 00163 virtual void onLinkSecured(LinkSecuredCallback_t callback) {linkSecuredCallback = callback;} 00164 00165 /** 00166 * To indicate that device context is stored persistently. 00167 */ 00168 virtual void onSecurityContextStored(HandleSpecificEvent_t callback) {securityContextStoredCallback = callback;} 00169 00170 /** 00171 * To set the callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability. 00172 */ 00173 virtual void onPasskeyDisplay(PasskeyDisplayCallback_t callback) {passkeyDisplayCallback = callback;} 00174 00175 /* Entry points for the underlying stack to report events back to the user. */ 00176 public: 00177 void processSecuritySetupInitiatedEvent(Gap::Handle_t handle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps) { 00178 if (securitySetupInitiatedCallback) { 00179 securitySetupInitiatedCallback(handle, allowBonding, requireMITM, iocaps); 00180 } 00181 } 00182 00183 void processSecuritySetupCompletedEvent(Gap::Handle_t handle, SecurityCompletionStatus_t status) { 00184 if (securitySetupCompletedCallback) { 00185 securitySetupCompletedCallback(handle, status); 00186 } 00187 } 00188 00189 void processLinkSecuredEvent(Gap::Handle_t handle, SecurityMode_t securityMode) { 00190 if (linkSecuredCallback) { 00191 linkSecuredCallback(handle, securityMode); 00192 } 00193 } 00194 00195 void processSecurityContextStoredEvent(Gap::Handle_t handle) { 00196 if (securityContextStoredCallback) { 00197 securityContextStoredCallback(handle); 00198 } 00199 } 00200 00201 void processPasskeyDisplayEvent(Gap::Handle_t handle, const Passkey_t passkey) { 00202 if (passkeyDisplayCallback) { 00203 passkeyDisplayCallback(handle, passkey); 00204 } 00205 } 00206 00207 protected: 00208 SecurityManager() : 00209 securitySetupInitiatedCallback(), 00210 securitySetupCompletedCallback(), 00211 linkSecuredCallback(), 00212 securityContextStoredCallback(), 00213 passkeyDisplayCallback() { 00214 /* empty */ 00215 } 00216 00217 protected: 00218 SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback; 00219 SecuritySetupCompletedCallback_t securitySetupCompletedCallback; 00220 LinkSecuredCallback_t linkSecuredCallback; 00221 HandleSpecificEvent_t securityContextStoredCallback; 00222 PasskeyDisplayCallback_t passkeyDisplayCallback; 00223 }; 00224 00225 #endif /*__SECURITY_MANAGER_H__*/
Generated on Tue Jul 12 2022 16:00:22 by
