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

1207 lines
53 KiB
C++
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

/* 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 "ble/common/StaticInterface.h"
#include "ble/blecommon.h"
#include "ble/BLETypes.h"
#include "ble/Gap.h"
#include "CallChainOfFunctionPointersWithContext.h"
#include "BleImplementationForward.h"
#if !defined(DOXYGEN_ONLY)
namespace ble {
namespace interface {
#endif
/**
* Overview
*
* Security Manager is used to provide link security through encryption, signing and authentication
* which are made possible by pairing and optionally bonding. Pairing is the process of establishing
* and/or exchanging keys used for the current connection. Bonding means saving this information so that
* it can later be used after reconnecting without having to pair again. This saves time and power.
*
* @par Paring
*
* There are several ways to provide different levels of security during pairing depending on your requirements
* and the facilities provided by the application. The process starts with initialising the SecurityManager
* with default options for new connections. Some settings can later be changed per link or globally.
*
* The important settings in the init() function are the MITM requirement and IO capabilities. Man in the
* Middle (MITM) protection prevents an attack where one device can impersonate another device by
* pairing with both devices at the same time. This protection is achieved by sharing some information
* between the devices through some independent channel. The IO capabilities of both devices dictate
* what algorithm is used. For details @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.3.5.1.
* You can change the IO capabilities after initialisation with setIoCapability(). This will take effect
* for all subsequent pairings.
*
* @par Out of Band data used in pairing
*
* Sharing this information through IO capabilities means user interaction which limits the degree of
* protection due to the limit of the amount of data that we can expect the user to transfer. Another
* solution is using OOB (out of band) communication to transfer this data instead which can send much
* more data making MITM attack even less likely to succeed. OOB data has to be exchanged by the application
* and provided to the Security Manager. Use setOOBDataUsage() to indicate you want to use it. The same call also
* allows you to set whether or not the communication channel you are using to transmit the OOB data is
* itself secure against MITM protection - this will set the level of the link security achieved using pairing
* that uses this data.
*
* The most secure pairing is provided by Secure Connections which relies on Elliptical Curve Cryptography.
* Support for Secure Connections is dependent on both the stack and controller on both sides supporting
* it. If either side doesn't support it Legacy Pairing will be used. This is an older standard of pairing.
* If higher security is required legacy pairing can be disabled by calling allowLegacyPairing(false);
*
* @par Signing
*
* Applications may require a level of security providing confidence that data transfers are coming
* from a trusted source. This can be achieved by encrypting the link which also provides added confidentiality.
* Encryption is a good choice when a device stays connected but introduces latency due to the need of encrypting the
* link if the device only connects periodically to transfer data. If confidentiality is not required data GATT
* server may allow writes to happen over an unencrypted link but authenticated by a signature present in each packet.
* This signature relies on having sent a signing key to the peer during pairing prior to sending any signed packets.
*
* @par Persistence of Security information
*
* Security Manager stores all the data required for its operation on active links. Depending on resources
* available on the device it will also attempt to store data for disconnected devices which have bonded to be
* reused when reconnected.
*
* If the application has initialised a filesystem and the Security Manager has been provided with a
* filepath during the init() call it may also provide data persistence across resets. This must be enabled by
* calling preserveBondingStateOnReset(). Persistence is not guaranteed and may fail if abnormally terminated.
* The Security Manager may also fall back to a non-persistent implementation if the resources are too limited.
*
* @par How to use
*
* First thing you need to do is to initialise the manager by calling init() with your chosen settings.
*
* The SecurityManager communicates with your application through events. These will trigger calls in
* the EventHandler which you must provide by calling the setSecurityManagerEventHandler() function.
*
* The most important process is pairing. This may be triggered manually by calling requestPairing() or
* may be called as a result of the application requiring encryption by calling setLinkEncryption() or
* as a result of the application requiring MITM protection through requestAuthentication().
*
* All these can be implicitly called by using setLinkSecurity() to conveniently set the required
* security for the link. The SecurityManager will trigger all the process required to achieve the set
* security level. Security level can only be escalated. Asking the Security Manager for a lower
* security level than the existing one will not fail but will result in a event informing the
* application through linkEncryptionResult() of the current level (which remains unchanged).
*
* Depending on the IO capabilities and OOB usage settings different pairing algorithms will be chosen.
* They will produce appropriate events which must be handled by your EventHandler. If your event handler
* doesn't support all the calls you must not set IO capabilities or set OOB usage in such a way that would
* trigger them or else the pairing will fail (usually by timing out).
*
* The simplest example is a pairing of a device with no IO capabilities and no OOB data available.
* With such limited pairing capabilities the "just works" method will be employed. This does not provide
* any MITM protection. The pairing (triggered implicitly or called explicitly) will result in an event
* being generated on the peer calling pairingRequest(). The event handler must make a decision (either in
* the application itself or based on user interaction) whether to accept the pairing and call
* accetPairing() or cancelPairing(). The result will be communicated on both peers through an event calling
* pairingResult() in the EventHandler.
*
* @par Sequence diagrams
*
* Sequence diagram "Just Works" pairing
*
* \verbatim
* /----------- Device 1 --------------\ *------ BLE link ------* /-------------- Device 2 -------------\
*
* App EventHandler SecurityManager SecurityManager EventHandler App
* | | | | | |
* |---------------------------> requestPairing() | | |
* | | |------[pairing start]------>| | |
* | | | |----------------> pairingRequest() ->|
* | | | acceptPairing() <------------------------ |
* | | |<---[pairing complete]----->| | |
* |<- pairingResult() <---------------| |----------------> pairingResult() -->|
* | | | | | |
* @endverbatim
*
* @note the requestPairing() call isn't required to trigger pairing. Pairing will also be triggered
* if you request encryption and authentication and no bonding information is available. The sequence will
* be the same save for the lack of explicit requestPairing() call.
*
*
* Sequence diagram Encryption request when bonding information is available
*
* \verbatim
* /----------- Device 1 --------------\ *------ BLE link ------* /-------------- Device 2 -------------\
*
* App EventHandler SecurityManager SecurityManager EventHandler App
* | | | | | |
* |---------------------------> setLinkEncryption() | | |
* | | |<-[encryption established]->| | |
* |<- linkEncryptionResult() <--------| |---------> linkEncryptionResult() -->|
* | | | | | |
* @endverbatim
*
* @note if bonding information is not available, pairing will be triggered
*
*
* Sequence diagram for Secure Connections passkey entry pairing with one device having a display only
* and other a keyboard
*
* \verbatim
* /----------- Device 1 (keyboard) ---\ *------ BLE link ------* /-------------- Device 2 (display) ---\
*
* App EventHandler SecurityManager SecurityManager EventHandler App
* | | | | | |
* |---------------------------> requestPairing() | | |
* | | |------[pairing start]------>| | |
* | | | |----------------> pairingRequest() ->|
* | | | acceptPairing() <------------------------ |
* | | |<---[secure con. pairing]-->| | |
* |<- passkeyRequest() <--------------| |----------------> passkeyDisplay() ->|
* | | | | | |
*
* user reads the passkey on Device 2 and inputs it on Device 1
*
* | | | | | |
* |-------------------------->passkeyEntered() | | |
* | | |<---[pairing complete]----->| | |
* |<- pairingResult() <---------------| |----------------> pairingResult() -->|
* | | | | | |
* @endverbatim
*
*/
#if !defined(DOXYGEN_ONLY)
template <class Impl>
class SecurityManager : public StaticInterface<Impl, SecurityManager> {
#else
class SecurityManager {
#endif
using StaticInterface<Impl, ::ble::interface::SecurityManager>::impl;
public:
/** events sent and received when passkey is being entered */
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 */
};
/** level of security required from the link by the application */
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.*/
};
/** Input/output capability of the device and application */
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. */
};
/** Result of security requests */
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 cancelled 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. */
SEC_STATUS_DHKEY_CHECK_FAILED = 0x8B, /**< DHKey received doesn’t match locally calculated one. */
SEC_STATUS_COMPARISON_FAILED = 0x8C, /**< Values in the numeric comparison protocol do not match. */
};
/**
* 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 FunctionPointerWithContext<const SecurityManager *> SecurityManagerShutdownCallback_t;
typedef CallChainOfFunctionPointersWithContext<const SecurityManager *> SecurityManagerShutdownCallbackChain_t;
/* legacy callbacks, please use SecurityManagerEventHandler instead */
typedef void (*HandleSpecificEvent_t)(ble::connection_handle_t connectionHandle);
typedef void (*SecuritySetupInitiatedCallback_t)(ble::connection_handle_t, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps);
typedef void (*SecuritySetupCompletedCallback_t)(ble::connection_handle_t, SecurityCompletionStatus_t status);
typedef void (*LinkSecuredCallback_t)(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode);
typedef void (*PasskeyDisplayCallback_t)(ble::connection_handle_t connectionHandle, const Passkey_t passkey);
/** The stack will use these functions to signal events to the application,
* subclass to override handlers. Use SecurityManager::setSecurityManagerEventHandler
* to set the interface implementation to be used. */
class EventHandler {
public:
EventHandler() {};
virtual ~EventHandler() {};
////////////////////////////////////////////////////////////////////////////
// Pairing
//
/**
* Request application to accept or reject pairing. Application should respond by
* calling the appropriate function: acceptPairingRequest or cancelPairingRequest
*
* @param[in] connectionHandle connection connectionHandle
*/
virtual void pairingRequest(ble::connection_handle_t connectionHandle) {
(void)connectionHandle;
}
/**
* Indicate to the application that pairing has completed.
*
* @param[in] connectionHandle connection connectionHandle
* @param[in] result result of the pairing indicating success or reason for failure
*/
virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result) {
(void)connectionHandle;
(void)result;
}
////////////////////////////////////////////////////////////////////////////
// Security
//
/**
* Deliver the requested whitelist to the application.
*
* @param[in] whitelist pointer to the whitelist filled with entries based on bonding information
*/
virtual void whitelistFromBondTable(::Gap::Whitelist_t* whitelist) {
(void)whitelist;
}
////////////////////////////////////////////////////////////////////////////
// Encryption
//
/**
* Inform the device of the encryption state of a given link.
*
* @param[in] connectionHandle connection connectionHandle
* @param[in] result encryption state of the link
*/
virtual void linkEncryptionResult(ble::connection_handle_t connectionHandle, ble::link_encryption_t result) {
(void)connectionHandle;
(void)result;
}
////////////////////////////////////////////////////////////////////////////
// MITM
//
/**
* Display the given passkey on the local device.
*
* @param[in] connectionHandle connection connectionHandle
* @param[in] passkey 6 digit passkey to be displayed
*/
virtual void passkeyDisplay(ble::connection_handle_t connectionHandle, const SecurityManager::Passkey_t passkey) {
(void)connectionHandle;
(void)passkey;
}
/**
* Indicate to the application that a confirmation is required. This is used
* when the device does not have a keyboard but has a yes/no button. The device
* displays numbers on its display in response to passkeyDisplay and the user
* checks if they are the same on both devices. The application should proceed
* by supplying the confirmation using the confirmationEntered function.
*
* @param[in] connectionHandle connection connectionHandle
*/
virtual void confirmationRequest(ble::connection_handle_t connectionHandle) {
(void)connectionHandle;
}
/**
* Indicate to the application that a passkey is required. The application should
* proceed by supplying the passkey through the passkeyEntered function.
*
* @param[in] connectionHandle connection connectionHandle
*/
virtual void passkeyRequest(ble::connection_handle_t connectionHandle) {
(void)connectionHandle;
}
/**
* Notify the application that a key was pressed by the peer during passkey entry.
*
* @param[in] connectionHandle connection connectionHandle
* @param[in] keypress type of keypress event
*/
virtual void keypressNotification(ble::connection_handle_t connectionHandle, SecurityManager::Keypress_t keypress) {
(void)connectionHandle;
(void)keypress;
}
/**
* Indicate to the application it needs to return legacy pairing OOB to the stack.
*
* @param[in] connectionHandle connection connectionHandle
*/
virtual void legacyPairingOobRequest(ble::connection_handle_t connectionHandle) {
(void)connectionHandle;
}
/**
* Indicate that the application needs to send legacy pairing OOB data to the peer.
*
* @param[in] address address that will be used in the pairing
* @param[in] temporaryKey temporary key to be used in legacy pairing
*/
virtual void legacyPairingOobGenerated(const ble::address_t *address,
const ble::oob_tk_t *temporaryKey) {
(void)address;
(void)temporaryKey;
}
/**
* Indicate that the application needs to send secure connections OOB data to the peer.
*
* @param[in] address address that will be used in the pairing
* @param[in] random random number used to generate the confirmation
* @param[in] confirm confirmation value to be use for authentication
* in secure connections pairing
*/
virtual void oobGenerated(const ble::address_t *address,
const ble::oob_lesc_value_t *random,
const ble::oob_confirm_t *confirm) {
(void)address;
(void)random;
(void)confirm;
}
////////////////////////////////////////////////////////////////////////////
// Keys
//
/**
* Deliver the signing key to the application.
*
* @param[in] connectionHandle connection connectionHandle
* @param[in] csrk signing key, pointer only valid during call
* @param[in] authenticated indicates if the signing key is authenticated
*/
virtual void signingKey(ble::connection_handle_t connectionHandle, const ble::csrk_t *csrk, bool authenticated) {
(void)connectionHandle;
(void)csrk;
(void)authenticated;
}
};
/*
* The following functions are meant to be overridden in the platform-specific sub-class.
*/
public:
////////////////////////////////////////////////////////////////////////////
// SM lifecycle management
//
/**
* 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.
* @param[in] signing Generate and distribute signing key during pairing
* @param[in] dbFilepath Path to the file used to store keys in the filesystem,
* if NULL keys will be only stored in memory
*
*
* @return BLE_ERROR_NONE on success.
*/
ble_error_t init(
bool enableBonding = true,
bool requireMITM = true,
SecurityIOCapabilities_t iocaps = IO_CAPS_NONE,
const Passkey_t passkey = NULL,
bool signing = true,
const char *dbFilepath = NULL
);
/**
* Change the file used for the security database. If path is invalid or a NULL is passed
* keys will only be stored in memory.
*
* @note This operation is only allowed with no active connections.
*
* @param[in] dbFilepath Path to the file used to store keys in the filesystem,
* if NULL keys will be only stored in memory
*
* @return BLE_ERROR_NONE on success.
*/
ble_error_t setDatabaseFilepath(const char *dbFilepath = NULL);
/**
* 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.
*/
ble_error_t reset(void);
/**
* Normally all bonding information is lost when device is reset, this requests that the stack
* attempts to save the information and reload it during initialisation. This is not guaranteed.
*
* @param[in] enable if true the stack will attempt to preserve bonding information on reset.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t preserveBondingStateOnReset(bool enable);
////////////////////////////////////////////////////////////////////////////
// List management
//
/**
* 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.
*/
ble_error_t purgeAllBondingState(void);
/**
* Create a list of addresses from all peers in the bond table and generate
* an event which returns it as a whitelist. Pass in the container for the whitelist.
* This will be returned by the event.
*
* @param[in] whitelist Preallocated whitelist which will be filled up to its capacity.
* If whitelist already contains entries this will be appended to.
* Do not access the whitelist until callback has been called,
* returning the filled whitelist.
*
* @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure
*/
ble_error_t generateWhitelistFromBondTable(::Gap::Whitelist_t *whitelist) const;
////////////////////////////////////////////////////////////////////////////
// Pairing
//
/**
* Request pairing with the peer. Called by the master.
* @note Slave can call requestAuthentication or setLinkEncryption to achieve security.
*
* @param[in] connectionHandle Handle to identify the connection.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t requestPairing(ble::connection_handle_t connectionHandle);
/**
* Accept the pairing request. Called as a result of pairingRequest being called
* on the event handler.
*
* @param[in] connectionHandle Handle to identify the connection.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t acceptPairingRequest(ble::connection_handle_t connectionHandle);
/**
* Reject pairing request if the local device is the slave or cancel an outstanding
* pairing request if master.
*
* @param[in] connectionHandle Handle to identify the connection.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t cancelPairingRequest(ble::connection_handle_t connectionHandle);
/**
* Tell the stack whether the application needs to authorise pairing requests or should
* they be automatically accepted.
*
* @param[in] required If set to true, pairingRequest in the event handler will
* will be called and will require an action from the application
* to continue with pairing by calling acceptPairingRequest
* or cancelPairingRequest if the user wishes to reject it.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setPairingRequestAuthorisation(bool required = true);
////////////////////////////////////////////////////////////////////////////
// Feature support
//
/**
* Allow of disallow the use of legacy pairing in case the application only wants
* to force the use of Secure Connections. If legacy pairing is disallowed and either
* side doesn't support Secure Connections the pairing will fail.
*
* @param[out] allow If true legacy pairing will be used if either side doesn't support Secure Connections.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t allowLegacyPairing(bool allow = true);
/**
* Check if the Secure Connections feature is supported by the stack and controller.
*
* @param[out] enabled true if SC are supported
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t getSecureConnectionsSupport(bool *enabled);
////////////////////////////////////////////////////////////////////////////
// Security settings
//
/**
* Set the IO capability of the local device.
*
* @param[in] iocaps type of IO capabilities available on the local device
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setIoCapability(SecurityIOCapabilities_t iocaps);
/**
* Set the passkey that is displayed on the local device instead of using
* a randomly generated one
*
* @param[in] passkey ASCII string of 6 digits
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setDisplayPasskey(const Passkey_t passkey);
/**
* 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.
*/
ble_error_t setLinkSecurity(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode);
/**
* Set whether or not we want to send and receive keypress notifications
* during passkey entry.
*
* @param[in] enabled if true pairing will try to enable keypress notifications
* (dependent on other side supporting it)
*
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setKeypressNotification(bool enabled = true);
#if BLE_FEATURE_SIGNING
/**
* Request generation and exchange of signing keys so that packet signing can be utilised
* on this connection.
* @note This does not generate a signingKey event. Use getSigningKey for that.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] enabled If set to true, signing keys will be exchanged
* during subsequent pairing.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t enableSigning(ble::connection_handle_t connectionHandle, bool enabled = true);
#endif // BLE_FEATURE_SIGNING
/**
* Give a hint to the stack that the master/slave role might change in the future.
*
* @param[in] enable If set to true it hints the roles are likely to swap in the future.
*
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setHintFutureRoleReversal(bool enable = true);
////////////////////////////////////////////////////////////////////////////
// Encryption
//
/**
* Current state of encryption on the link.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[out] encryption
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t getLinkEncryption(ble::connection_handle_t connectionHandle, ble::link_encryption_t *encryption);
/**
* Enabled or disable encryption on the link. The result of this request will be indicated
* by a call to linkEncryptionResult in the event handler when the action is completed.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] encryption encryption state requested
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setLinkEncryption(ble::connection_handle_t connectionHandle, ble::link_encryption_t encryption);
/**
* Set the requirements for encryption key size. If the peer cannot comply with the requirements
* paring will fail.
*
* @param[in] minimumByteSize Smallest allowed encryption key size in bytes. (no smaller than 7)
* @param[in] maximumByteSize Largest allowed encryption key size in bytes. (no larger than 16)
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setEncryptionKeyRequirements(uint8_t minimumByteSize, uint8_t maximumByteSize);
////////////////////////////////////////////////////////////////////////////
// Authentication
//
/**
* Request that the link be authenticated (keys with MITM protection). This might trigger encryption
* or pairing/re-pairing. The success will be indicated through an event indicating security level change.
*
* @param[in] connectionHandle Handle to identify the connection.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t requestAuthentication(ble::connection_handle_t connectionHandle);
////////////////////////////////////////////////////////////////////////////
// MITM
//
/**
* Generate OOB data with the given address. If Secure Connections is supported this will
* also generate Secure Connections OOB data on top of legacy pairing OOB data. This can be used
* to generate such data before the connection takes place.
*
* In this model the OOB exchange takes place before the devices connect. Devices should establish
* communication over another channel and exchange the OOB data. The address provided will be used
* by the peer to associate the received data with the address of the device it will then connect
* to over BLE.
*
* @param[in] address The local address you will use in the connection using this OOB data. This
* address will be returned along with the rest of the OOB data when generation
* is complete. Using an invalid address is illegal.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t generateOOB(const ble::address_t *address);
/**
* Enable OOB data usage during paring. If Secure Connections is supported enabling useOOB will
* generate Secure Connections OOB data through oobGenerated() on top of legacy pairing OOB data.
*
* You do not have to call this function to return received OOB data. Use legacyPairingOobReceived
* or oobReceived to hand it in. This will allow the stack to use it if possible. You only need to
* call this function to attempt legacy OOB data exchange after pairing start and to inform
* the stack OOB data does not provide MITM protection (by default it is set to provide this).
*
* In this model the OOB exchange takes places after the devices have connected but possibly
* prior to pairing. For secure connections pairing must not be started until after the OOB
* data has been sent and/or received. The address in the OOB data generated will match
* the original address used to establish the connection and will be used by the peer to
* identify which connection the OOB data belongs to.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] useOOB If set to true, authenticate using OOB data.
* @param[in] OOBProvidesMITM If set to true keys exchanged during pairing using OOB data
* will provide Man-in-the-Middle protection. This indicates that
* the form of exchange used by the OOB data itself provides MITM
* protection.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t setOOBDataUsage(ble::connection_handle_t connectionHandle, bool useOOB, bool OOBProvidesMITM = true);
/**
* Report to the stack if the passkey matches or not. Used during pairing to provide MITM protection.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] confirmation True value indicates the passkey displayed matches.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t confirmationEntered(ble::connection_handle_t connectionHandle, bool confirmation);
/**
* Supply the stack with the user entered passkey.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] passkey ASCII string of digits entered by the user.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t passkeyEntered(ble::connection_handle_t connectionHandle, Passkey_t passkey);
/**
* Send a notification to the peer that the user pressed a key on the local device.
* @note This will only be delivered if the keypress notifications have been enabled during pairing.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] keypress Type of keypress event.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t sendKeypressNotification(ble::connection_handle_t connectionHandle, Keypress_t keypress);
/**
* Supply the stack with the OOB data for legacy connections.
*
* @param[in] address address of the peer device this data comes from
* @param[in] tk pointer to out of band data received containing the temporary key.
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t legacyPairingOobReceived(const ble::address_t *address, const ble::oob_tk_t *tk);
/**
* Supply the stack with the OOB data for secure connections.
*
* @param[in] address address of the peer device this data comes from
* @param[in] random random number used to generate the confirmation
* @param[in] confirm confirmation value to be use for authentication
* in secure connections pairing
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t oobReceived(const ble::address_t *address, const ble::oob_lesc_value_t *random, const ble::oob_confirm_t *confirm);
////////////////////////////////////////////////////////////////////////////
// Keys
//
/**
* Retrieves a signing key through a signingKey event.
* If a signing key is not present, pairing/authentication will be attempted.
* @note This will attempt to retrieve the key even if enableSigning hasn't been called prior to pairing.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[in] authenticated Whether the signing key needs to be authenticated
* (provide MITM protection).
*
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t getSigningKey(ble::connection_handle_t connectionHandle, bool authenticated);
/* 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);
}
/**
* 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;
}
/**
* Assign the event handler implementation that will be used by the stack to signal events
* back to the application.
*
* @param[in] handler Event Handler interface implementation.
*/
void setSecurityManagerEventHandler(EventHandler* handler) {
if (handler) {
eventHandler = handler;
} else {
eventHandler = &defaultEventHandler;
}
}
protected:
SecurityManager() {
eventHandler = &defaultEventHandler;
}
~SecurityManager() { };
public:
/**
* @deprecated use generateWhitelistFromBondTable instead
*
* 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.
*/
ble_error_t getAddressesFromBondTable(::Gap::Whitelist_t &addresses) const;
/**
* @deprecated
*
* Get the security status of a connection.
*
* @param[in] connectionHandle Handle to identify the connection.
* @param[out] securityStatus Security status.
*
* @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
ble_error_t getLinkSecurity(ble::connection_handle_t connectionHandle, LinkSecurityStatus_t *securityStatus) {
ble::link_encryption_t encryption(ble::link_encryption_t::NOT_ENCRYPTED);
ble_error_t err = getLinkEncryption(connectionHandle, &encryption);
if (err) {
return err;
}
switch (encryption.value()) {
case ble::link_encryption_t::NOT_ENCRYPTED:
*securityStatus = NOT_ENCRYPTED;
break;
case ble::link_encryption_t::ENCRYPTION_IN_PROGRESS:
*securityStatus = ENCRYPTION_IN_PROGRESS;
break;
case ble::link_encryption_t::ENCRYPTED:
case ble::link_encryption_t::ENCRYPTED_WITH_MITM:
case ble::link_encryption_t::ENCRYPTED_WITH_SC_AND_MITM:
*securityStatus = ENCRYPTED;
break;
default:
// should never happen
MBED_ASSERT(false);
*securityStatus = NOT_ENCRYPTED;
break;
}
return BLE_ERROR_NONE;
}
/**
* @deprecated
*
* To indicate that a security procedure for the link has started.
*/
void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {
defaultEventHandler.securitySetupInitiatedCallback = callback;
}
/**
* @deprecated
*
* To indicate that the security procedure for the link has completed.
*/
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).
*/
void onLinkSecured(LinkSecuredCallback_t callback) {
defaultEventHandler.linkSecuredCallback = callback;
}
/**
* @deprecated
*
* To indicate that device context is stored persistently.
*/
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.
*/
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(ble::connection_handle_t connectionHandle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps) {
if (defaultEventHandler.securitySetupInitiatedCallback) {
defaultEventHandler.securitySetupInitiatedCallback(connectionHandle, allowBonding, requireMITM, iocaps);
}
}
/** @deprecated */
void processSecuritySetupCompletedEvent(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t status) {
eventHandler->pairingResult(connectionHandle, status);
}
/** @deprecated */
void processLinkSecuredEvent(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode) {
if (securityMode == SECURITY_MODE_ENCRYPTION_NO_MITM) {
eventHandler->linkEncryptionResult(connectionHandle, ble::link_encryption_t::ENCRYPTED);
} else {
eventHandler->linkEncryptionResult(connectionHandle, ble::link_encryption_t::NOT_ENCRYPTED);
}
}
/** @deprecated */
void processSecurityContextStoredEvent(ble::connection_handle_t connectionHandle) {
if (defaultEventHandler.securityContextStoredCallback) {
defaultEventHandler.securityContextStoredCallback(connectionHandle);
}
}
/** @deprecated */
void processPasskeyDisplayEvent(ble::connection_handle_t connectionHandle, const Passkey_t passkey) {
eventHandler->passkeyDisplay(connectionHandle, passkey);
}
protected:
/* --- _virtual_ implementations declaration --- */
/* Note: implementation must call the base class definition */
ble_error_t reset_();
ble_error_t init_(
bool enableBonding,
bool requireMITM,
SecurityIOCapabilities_t iocaps,
const Passkey_t passkey,
bool signing,
const char *dbFilepath
);
ble_error_t setDatabaseFilepath_(const char *dbFilepath);
ble_error_t preserveBondingStateOnReset_(bool enable);
ble_error_t purgeAllBondingState_(void);
ble_error_t generateWhitelistFromBondTable_(
::Gap::Whitelist_t *whitelist
) const;
ble_error_t requestPairing_(
ble::connection_handle_t connectionHandle
);
ble_error_t acceptPairingRequest_(
ble::connection_handle_t connectionHandle
);
ble_error_t cancelPairingRequest_(
ble::connection_handle_t connectionHandle
);
ble_error_t setPairingRequestAuthorisation_(
bool required
);
ble_error_t allowLegacyPairing_(bool allow);
ble_error_t getSecureConnectionsSupport_(bool *enabled);
ble_error_t setIoCapability_(SecurityIOCapabilities_t iocaps);
ble_error_t setDisplayPasskey_(const Passkey_t passkey);
ble_error_t setLinkSecurity_(
ble::connection_handle_t connectionHandle,
SecurityMode_t securityMode
);
ble_error_t setKeypressNotification_(bool enabled);
ble_error_t enableSigning_(
ble::connection_handle_t connectionHandle,
bool enabled
);
ble_error_t setHintFutureRoleReversal_(bool enable);
ble_error_t getLinkEncryption_(
ble::connection_handle_t connectionHandle,
ble::link_encryption_t *encryption
);
ble_error_t setLinkEncryption_(
ble::connection_handle_t connectionHandle,
ble::link_encryption_t encryption
);
ble_error_t setEncryptionKeyRequirements_(
uint8_t minimumByteSize,
uint8_t maximumByteSize
);
ble_error_t requestAuthentication_(
ble::connection_handle_t connectionHandle
);
ble_error_t generateOOB_(const ble::address_t *address);
ble_error_t setOOBDataUsage_(
ble::connection_handle_t connectionHandle,
bool useOOB,
bool OOBProvidesMITM
);
ble_error_t confirmationEntered_(
ble::connection_handle_t connectionHandle,
bool confirmation
);
ble_error_t passkeyEntered_(
ble::connection_handle_t connectionHandle,
Passkey_t passkey
);
ble_error_t sendKeypressNotification_(
ble::connection_handle_t connectionHandle,
Keypress_t keypress
);
ble_error_t legacyPairingOobReceived_(
const ble::address_t *address,
const ble::oob_tk_t *tk
);
ble_error_t oobReceived_(
const ble::address_t *address,
const ble::oob_lesc_value_t *random,
const ble::oob_confirm_t *confirm
);
ble_error_t getSigningKey_(
ble::connection_handle_t connectionHandle,
bool authenticated
);
ble_error_t getAddressesFromBondTable_(::Gap::Whitelist_t &addresses) const;
private:
/* Legacy compatibility with old callbacks (from both sides so any
* combination of new and old works) */
class LegacyEventHandler : public EventHandler {
public:
LegacyEventHandler() :
securitySetupInitiatedCallback(),
securitySetupCompletedCallback(),
linkSecuredCallback(),
securityContextStoredCallback(),
passkeyDisplayCallback() { };
virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result) {
if (securitySetupCompletedCallback) {
securitySetupCompletedCallback(connectionHandle, result);
}
}
virtual void linkEncryptionResult(ble::connection_handle_t connectionHandle, ble::link_encryption_t result) {
if (linkSecuredCallback) {
SecurityMode_t securityMode;
if (result == ble::link_encryption_t::ENCRYPTED) {
securityMode = SECURITY_MODE_ENCRYPTION_NO_MITM;
} else if (
result == ble::link_encryption_t::ENCRYPTED_WITH_MITM ||
result == ble::link_encryption_t::ENCRYPTED_WITH_SC_AND_MITM
) {
securityMode = SECURITY_MODE_ENCRYPTION_WITH_MITM;
} else {
securityMode = SECURITY_MODE_ENCRYPTION_OPEN_LINK;
}
linkSecuredCallback(connectionHandle, securityMode);
}
};
virtual void passkeyDisplay(ble::connection_handle_t connectionHandle, const Passkey_t passkey) {
if (passkeyDisplayCallback) {
passkeyDisplayCallback(connectionHandle, passkey);
}
};
SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
SecuritySetupCompletedCallback_t securitySetupCompletedCallback;
LinkSecuredCallback_t linkSecuredCallback;
HandleSpecificEvent_t securityContextStoredCallback;
PasskeyDisplayCallback_t passkeyDisplayCallback;
};
private:
SecurityManagerShutdownCallbackChain_t shutdownCallChain;
protected:
EventHandler* eventHandler;
LegacyEventHandler defaultEventHandler;
};
#if !defined(DOXYGEN_ONLY)
} // interface
} // ble
using ble::impl::SecurityManager;
#endif
#endif /*SECURITY_MANAGER_H_*/
Reference in New Issue View Git Blame Copy Permalink