ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
mbed-os/features/FEATURE_BLE/ble/SecurityManager.h

595 lines
25 KiB
C++
Raw Blame History

/* mbed Microcontroller Library
* Copyright (c) 2006-2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __SECURITY_MANAGER_H__
#define __SECURITY_MANAGER_H__
#include <stdint.h>
#include "Gap.h"
#include "CallChainOfFunctionPointersWithContext.h"
class SecurityManagerEventHandler;
class LegacySecurityManagerEventHandler;
class SecurityManager {
public:
enum Keypress_t {
KEYPRESS_STARTED, /* Passkey entry started */
KEYPRESS_ENTERED, /* Passkey digit entered */
KEYPRESS_ERASED, /* Passkey digit erased */
KEYPRESS_CLEARED, /* Passkey cleared */
KEYPRESS_COMPLETED, /* Passkey entry completed */
};
enum SecurityMode_t {
SECURITY_MODE_NO_ACCESS,
SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< Require no protection, open link. */
SECURITY_MODE_ENCRYPTION_NO_MITM, /**< Require encryption, but no MITM protection. */
SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< Require encryption and MITM protection. */
SECURITY_MODE_SIGNED_NO_MITM, /**< Require signing or encryption, but no MITM protection. */
SECURITY_MODE_SIGNED_WITH_MITM, /**< Require signing or encryption, and MITM protection. */
};
/**
* @brief Defines possible security status or states.
*
* @details Defines possible security status or states of a link when requested by getLinkSecurity().
*/
enum LinkSecurityStatus_t {
NOT_ENCRYPTED, /**< The link is not secured. */
ENCRYPTION_IN_PROGRESS, /**< Link security is being established.*/
ENCRYPTED /**< The link is secure.*/
};
enum SecurityIOCapabilities_t {
IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display only. */
IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and yes/no entry. */
IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */
IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */
IO_CAPS_KEYBOARD_DISPLAY = 0x04, /**< Keyboard and display. */
};
enum SecurityCompletionStatus_t {
SEC_STATUS_SUCCESS = 0x00, /**< Procedure completed with success. */
SEC_STATUS_TIMEOUT = 0x01, /**< Procedure timed out. */
SEC_STATUS_PDU_INVALID = 0x02, /**< Invalid PDU received. */
SEC_STATUS_PASSKEY_ENTRY_FAILED = 0x81, /**< Passkey entry failed (user canceled or other). */
SEC_STATUS_OOB_NOT_AVAILABLE = 0x82, /**< Out of Band Key not available. */
SEC_STATUS_AUTH_REQ = 0x83, /**< Authentication requirements not met. */
SEC_STATUS_CONFIRM_VALUE = 0x84, /**< Confirm value failed. */
SEC_STATUS_PAIRING_NOT_SUPP = 0x85, /**< Pairing not supported. */
SEC_STATUS_ENC_KEY_SIZE = 0x86, /**< Encryption key size. */
SEC_STATUS_SMP_CMD_UNSUPPORTED = 0x87, /**< Unsupported SMP command. */
SEC_STATUS_UNSPECIFIED = 0x88, /**< Unspecified reason. */
SEC_STATUS_REPEATED_ATTEMPTS = 0x89, /**< Too little time elapsed since last attempt. */
SEC_STATUS_INVALID_PARAMS = 0x8A, /**< Invalid parameters. */
};
/**
* Declaration of type containing a passkey to be used during pairing. This
* is passed into initializeSecurity() to specify a pre-programmed passkey
* for authentication instead of generating a random one.
*/
static const unsigned PASSKEY_LEN = 6;
typedef uint8_t Passkey_t[PASSKEY_LEN]; /**< 6-digit passkey in ASCII ('0'-'9' digits only). */
typedef uint8_t C192_t[16];
typedef uint8_t R192_t[16];
typedef uint8_t C256_t[16];
typedef uint8_t R256_t[16];
typedef void (*HandleSpecificEvent_t)(Gap::Handle_t handle);
typedef void (*SecuritySetupInitiatedCallback_t)(Gap::Handle_t, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps);
typedef void (*SecuritySetupCompletedCallback_t)(Gap::Handle_t, SecurityCompletionStatus_t status);
typedef void (*LinkSecuredCallback_t)(Gap::Handle_t handle, SecurityMode_t securityMode);
typedef void (*PasskeyDisplayCallback_t)(Gap::Handle_t handle, const Passkey_t passkey);
public:
typedef FunctionPointerWithContext<const SecurityManager *> SecurityManagerShutdownCallback_t;
typedef CallChainOfFunctionPointersWithContext<const SecurityManager *> SecurityManagerShutdownCallbackChain_t;
/*
* The following functions are meant to be overridden in the platform-specific sub-class.
*/
public:
/**
* Enable the BLE stack's Security Manager. The Security Manager implements
* the actual cryptographic algorithms and protocol exchanges that allow two
* devices to securely exchange data and privately detect each other.
* Calling this API is a prerequisite for encryption and pairing (bonding).
*
* @param[in] enableBonding Allow for bonding.
* @param[in] requireMITM Require protection for man-in-the-middle attacks.
* @param[in] iocaps To specify the I/O capabilities of this peripheral,
* such as availability of a display or keyboard, to
* support out-of-band exchanges of security data.
* @param[in] passkey To specify a static passkey.
*
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t init(bool enableBonding = true,
bool requireMITM = true,
SecurityIOCapabilities_t iocaps = IO_CAPS_NONE,
const Passkey_t passkey = NULL) {
/* Avoid compiler warnings about unused variables. */
(void)enableBonding;
(void)requireMITM;
(void)iocaps;
(void)passkey;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/**
* @deprecated
*
* Get the security status of a connection.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[out] securityStatusP Security status.
*
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) {
/* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)securityStatusP;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t getLinkSecurity(Gap::Handle_t handle, SecurityMode_t &mode) {
(void) handle;
(void) mode;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/**
* Set the security mode on a connection. Useful for elevating the security mode
* once certain conditions are met, e.g., a particular service is found.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] securityMode Requested security mode.
*
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
virtual ble_error_t setLinkSecurity(Gap::Handle_t connectionHandle, SecurityMode_t securityMode) {
/* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)securityMode;
return BLE_ERROR_NOT_IMPLEMENTED;
}
/**
* Delete all peer device context and all related bonding information from
* the database within the security manager.
*
* @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*/
virtual ble_error_t purgeAllBondingState(void) {
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/**
* Get a list of addresses from all peers in the bond table.
*
* @param[in,out] addresses
* (on input) addresses.capacity contains the maximum
* number of addresses to be returned.
* (on output) The populated table with copies of the
* addresses in the implementation's whitelist.
*
* @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*/
virtual ble_error_t getAddressesFromBondTable(Gap::Whitelist_t &addresses) const {
/* Avoid compiler warnings about unused variables */
(void) addresses;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setPrivateAddressTimeout(uint16_t timeout_in_seconds) {
(void) timeout_in_seconds;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setAuthenticationTimeout(connection_handle_t handle, uint32_t timeout_in_ms) {
(void) handle;
(void) timeout_in_ms;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t getAuthenticationTimeout(connection_handle_t handle, uint32_t *timeout_in_ms) {
(void) handle;
(void) timeout_in_ms;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setSecureConnectionsSupport(bool enabled, bool secure_connections_only = false) {
(void) enabled;
(void) secure_connections_only;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t getSecureConnectionsSupport(bool *enabled, bool *secure_connections_only) {
(void) enabled;
(void) secure_connections_only;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t getEncryptionKeySize(Gap::Handle_t handle, uint8_t *size) {
(void) handle;
(void) size;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t requestPairing(bool authentication_required = true) {
(void) authentication_required;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setPairingRequestAuthorisation(bool required = true) {
(void) required;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t acceptPairingRequest(bool accept = true, bool authentication_required = true) {
(void) authentication_required;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t requestAuthentication() {
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setOOBDataUsage(Gap::Handle_t connectionHandle, bool useOOB, bool OOBProvidesMITM = false) {
/* Avoid compiler warnings about unused variables */
(void) connectionHandle;
(void) useOOB;
(void) OOBProvidesMITM;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setPinCode(uint8_t pinLength, uint8_t * pinCode, bool isStatic = false) {
(void) pinLength;
(void) pinCode;
(void) isStatic;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setPasskey(const Passkey_t passkey) {
(void) passkey;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t confirmationEntered(Gap::Handle_t handle, bool confirmation) {
(void) handle;
(void) confirmation;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t passkeyEntered(Gap::Handle_t handle, Passkey_t passkey) {
(void) handle;
(void) passkey;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t sendKeypressNotification(Gap::Handle_t handle, Keypress_t keypress) {
(void) handle;
(void) keypress;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setOob(Gap::Handle_t handle, C192_t* hash192, R192_t* rand192) {
(void) handle;
(void) hash192;
(void) rand192;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t setExtendedOob(Gap::Handle_t handle,
C192_t* hash192, R192_t* rand192,
C256_t* hash256, R256_t* rand256) {
(void) handle;
(void) hash192;
(void) rand192;
(void) hash256;
(void) rand256;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t getLocalOobData(Gap::Handle_t handle, C192_t* hash192, R192_t* rand192) {
(void) handle;
(void) hash192;
(void) rand192;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
virtual ble_error_t getLocalExtendedOobData(Gap::Handle_t handle,
C192_t* hash192, R192_t* rand192,
C256_t* hash256, R256_t* rand256) {
(void) handle;
(void) hash192;
(void) rand192;
(void) hash256;
(void) rand256;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/* Event callback handlers. */
public:
/**
* Setup a callback to be invoked to notify the user application that the
* SecurityManager instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
* @note It is possible to chain together multiple onShutdown callbacks
* (potentially from different modules of an application) to be notified
* before the SecurityManager is shutdown.
*
* @note It is also possible to set up a callback into a member function of
* some object.
*
* @note It is possible to unregister a callback using onShutdown().detach(callback)
*/
void onShutdown(const SecurityManagerShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
}
template <typename T>
void onShutdown(T *objPtr, void (T::*memberPtr)(const SecurityManager *)) {
shutdownCallChain.add(objPtr, memberPtr);
}
/**
* @brief provide access to the callchain of shutdown event callbacks
* It is possible to register callbacks using onShutdown().add(callback);
* It is possible to unregister callbacks using onShutdown().detach(callback)
* @return The shutdown event callbacks chain
*/
SecurityManagerShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
}
virtual void setSecurityManagerEventHandler(SecurityManagerEventHandler* handler) {
if (handler) {
if (eventHandler && (eventHandler != &defaultEventHandler)) {
delete eventHandler;
}
eventHandler = handler;
}
}
virtual ble_error_t preserveBondingStateOnReset(bool enable) {
/* Avoid compiler warnings about unused variables */
(void) enable;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
protected:
SecurityManager() {
eventHandler = &defaultEventHandler;
}
virtual ~SecurityManager() { };
public:
/**
* Notify all registered onShutdown callbacks that the SecurityManager is
* about to be shutdown and clear all SecurityManager state of the
* associated object.
*
* This function is meant to be overridden in the platform-specific
* sub-class. Nevertheless, the sub-class is only expected to reset its
* state and not the data held in SecurityManager members. This shall be
* achieved by a call to SecurityManager::reset() from the sub-class'
* reset() implementation.
*
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t reset(void) {
/* Notify that the instance is about to shutdown */
shutdownCallChain.call(this);
shutdownCallChain.clear();
if (eventHandler != &defaultEventHandler) {
delete eventHandler;
eventHandler = defaultEventHandler;
}
return BLE_ERROR_NONE;
}
/**
* @deprecated
*
* To indicate that a security procedure for the link has started.
*/
virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {
defaultEventHandler.securitySetupInitiatedCallback = callback;
}
/**
* @deprecated
*
* To indicate that the security procedure for the link has completed.
*/
virtual void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback) {
defaultEventHandler.securitySetupCompletedCallback = callback;
}
/**
* @deprecated
*
* To indicate that the link with the peer is secured. For bonded devices,
* subsequent reconnections with a bonded peer will result only in this callback
* when the link is secured; setup procedures will not occur (unless the
* bonding information is either lost or deleted on either or both sides).
*/
virtual void onLinkSecured(LinkSecuredCallback_t callback) {
defaultEventHandler.linkSecuredCallback = callback;
}
/**
* @deprecated
*
* To indicate that device context is stored persistently.
*/
virtual void onSecurityContextStored(HandleSpecificEvent_t callback) {
defaultEventHandler.securityContextStoredCallback = callback;
}
/** @deprecated
*
* To set the callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability.
*/
virtual void onPasskeyDisplay(PasskeyDisplayCallback_t callback) {
defaultEventHandler.passkeyDisplayCallback = callback;
}
/* Entry points for the underlying stack to report events back to the user. */
public:
/** @deprecated */
void processSecuritySetupInitiatedEvent(Gap::Handle_t handle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps) {
eventHandler->securitySetupInitiated(handle, allowBonding, requireMITM, iocaps);
}
/** @deprecated */
void processSecuritySetupCompletedEvent(Gap::Handle_t handle, SecurityCompletionStatus_t status) {
eventHandler->securitySetupCompleted(handle, status);
}
/** @deprecated */
void processLinkSecuredEvent(Gap::Handle_t handle, SecurityMode_t securityMode) {
eventHandler->linkSecured(handle, securityMode);
}
/** @deprecated */
void processSecurityContextStoredEvent(Gap::Handle_t handle) {
eventHandler->securityContextStored(handle);
}
/** @deprecated */
void processPasskeyDisplayEvent(Gap::Handle_t handle, const Passkey_t passkey) {
eventHandler->passkeyDisplay(handle, passkey);
}
private:
SecurityManagerEventHandler* eventHandler;
SecurityManagerShutdownCallbackChain_t shutdownCallChain;
LegacySecurityManagerEventHandler defaultEventHandler;
};
/* subclass to override handlers */
class SecurityManagerEventHandler {
public:
SecurityManagerEventHandler() {};
virtual ~SecurityManagerEventHandler() {};
virtual void securitySetupInitiated(Gap::Handle_t handle, bool allowBonding, bool requireMITM, SecurityManager::SecurityIOCapabilities_t iocaps) {
(void)handle;
(void)allowBonding;
(void)requireMITM;
(void)iocaps;
};
virtual void securitySetupCompleted(Gap::Handle_t handle, SecurityManager::SecurityCompletionStatus_t status) {
(void)handle;
(void)status;
};
virtual void linkSecured(Gap::Handle_t handle, SecurityManager::SecurityMode_t securityMode) {
(void)handle;
(void)securityMode;
};
virtual void securityContextStored(Gap::Handle_t handle) {
(void)handle;
}
virtual void passkeyDisplay(Gap::Handle_t handle, const SecurityManager::Passkey_t passkey) {
(void)handle;
(void)passkey;
};
virtual void validMicTimeout(Gap::Handle_t handle) {
(void)handle;
};
virtual void linkKeyFailure(Gap::Handle_t handle) {
(void)handle;
};
virtual void keypressNotification(Gap::Handle_t handle, SecurityManager::Keypress_t keypress) {
(void)handle;
(void)keypress;
};
virtual void legacyPairingOobRequest(Gap::Handle_t handle) {
(void)handle;
};
virtual void oobRequest(Gap::Handle_t handle) {
(void)handle;
};
virtual void pinRequest(Gap::Handle_t handle) {
(void)handle;
};
virtual void passkeyRequest(Gap::Handle_t handle) {
(void)handle;
};
virtual void confirmationRequest(Gap::Handle_t handle) {
(void)handle;
};
virtual void acceptPairingRequest(Gap::Handle_t handle) {
(void)handle;
};
};
/* legacy compatibility with old callbacks (from both sides, so combination of new and old works) */
class LegacySecurityManagerEventHandler : public SecurityManagerEventHandler {
public:
LegacySecurityManagerEventHandler() :
securitySetupInitiatedCallback(),
securitySetupCompletedCallback(),
linkSecuredCallback(),
securityContextStoredCallback(),
passkeyDisplayCallback() { };
void securitySetupInitiated(Gap::Handle_t handle, bool allowBonding, bool requireMITM, SecurityManager::SecurityIOCapabilities_t iocaps) {
if (securitySetupInitiatedCallback) {
securitySetupInitiatedCallback(handle, allowBonding, requireMITM, iocaps);
}
};
void securitySetupCompleted(Gap::Handle_t handle, SecurityManager::SecurityCompletionStatus_t status) {
if (securitySetupCompletedCallback) {
securitySetupCompletedCallback(handle, status);
}
};
void linkSecured(Gap::Handle_t handle, SecurityManager::SecurityMode_t securityMode) {
if (linkSecuredCallback) {
linkSecuredCallback(handle, securityMode);
}
};
void securityContextStored(Gap::Handle_t handle) {
if (securityContextStoredCallback) {
securityContextStoredCallback(handle);
}
}
void passkeyDisplay(Gap::Handle_t handle, const SecurityManager::Passkey_t passkey) {
if (passkeyDisplayCallback) {
passkeyDisplayCallback(handle, passkey);
}
};
private:
SecurityManager::SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
SecurityManager::SecuritySetupCompletedCallback_t securitySetupCompletedCallback;
SecurityManager::LinkSecuredCallback_t linkSecuredCallback;
SecurityManager::HandleSpecificEvent_t securityContextStoredCallback;
SecurityManager::PasskeyDisplayCallback_t passkeyDisplayCallback;
};
#endif /*__SECURITY_MANAGER_H__*/
Reference in New Issue View Git Blame Copy Permalink