Matthew Lister
BLE_API
Diff: public/BLE.h
- Revision:
- 546:9fdf3d960d12
- Parent:
- 545:45bbdb1d5eca
- Child:
- 547:f84c514eee35
--- a/public/BLE.h Fri Jun 19 15:52:09 2015 +0100
+++ b/public/BLE.h Fri Jun 19 15:52:09 2015 +0100
@@ -96,6 +96,18 @@
return transport->getGattClient();
}
+ /*
+ * Accessors to Security Manager. Please refer to SecurityManager.h. All
+ * SecurityManager related functionality requires going through this
+ * accessor.
+ */
+ const SecurityManager& securityManager() const {
+ return transport->getSecurityManager();
+ }
+ SecurityManager& securityManager() {
+ return transport->getSecurityManager();
+ }
+
/**
* Yield control to the BLE stack or to other tasks waiting for events. This
* is a sleep function which will return when there is an application
@@ -107,88 +119,6 @@
transport->waitForEvent();
}
- /**
- * 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 IO 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.
- */
- ble_error_t initializeSecurity(bool enableBonding = true,
- bool requireMITM = true,
- Gap::SecurityIOCapabilities_t iocaps = Gap::IO_CAPS_NONE,
- const Gap::Passkey_t passkey = NULL);
-
- /**
- * Setup a callback for when the security setup procedure (key generation
- * and exchange) for a link has started. This will be skipped for bonded
- * devices. The callback is passed in parameters received from the peer's
- * security request: bool allowBonding, bool requireMITM, and
- * SecurityIOCapabilities_t.
- */
- void onSecuritySetupInitiated(Gap::SecuritySetupInitiatedCallback_t callback);
-
- /**
- * Setup a callback for when the security setup procedure (key generation
- * and exchange) for a link has completed. This will be skipped for bonded
- * devices. The callback is passed in the success/failure status of the
- * security setup procedure.
- */
- void onSecuritySetupCompleted(Gap::SecuritySetupCompletedCallback_t callback);
-
- /**
- * Setup a callback for when a link with the peer is secured. For bonded
- * devices, subsequent reconnections with bonded peer will result only in
- * this callback when the link is secured and setup procedures will not
- * occur unless the bonding information is either lost or deleted on either
- * or both sides. The callback is passed in a Gap::SecurityMode_t according
- * to the level of security in effect for the secured link.
- */
- void onLinkSecured(Gap::LinkSecuredCallback_t callback);
-
- /**
- * Setup a callback for successful bonding; i.e. that link-specific security
- * context is stored persistently for a peer device.
- */
- void onSecurityContextStored(Gap::HandleSpecificEvent_t callback);
-
- /**
- * Setup a callback for when the passkey needs to be displayed on a
- * peripheral with DISPLAY capability. This happens when security is
- * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey)
- * needs to be exchanged between the peers to authenticate the connection
- * attempt.
- */
- void onPasskeyDisplay(Gap::PasskeyDisplayCallback_t callback);
-
- /**
- * Get the security status of a connection.
- *
- * @param[in] connectionHandle Handle to identify the connection.
- * @param[out] securityStatusP security status.
- *
- * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
- */
- ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, Gap::LinkSecurityStatus_t *securityStatusP);
-
- /**
- * 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 and/or
- * application registration.
- */
- ble_error_t purgeAllBondingState(void);
-
/*
* Deprecation alert!
* All of the following are deprecated and may be dropped in a future
@@ -1054,6 +984,67 @@
}
/**
+ * 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 IO 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.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.initializeSecurity(...) should be replaced with
+ * ble.securityManager().init(...).
+ */
+ ble_error_t initializeSecurity(bool enableBonding = true,
+ bool requireMITM = true,
+ SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
+ const SecurityManager::Passkey_t passkey = NULL) {
+ return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
+ }
+
+ /**
+ * Get the security status of a connection.
+ *
+ * @param[in] connectionHandle Handle to identify the connection.
+ * @param[out] securityStatusP security status.
+ *
+ * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.getLinkSecurity(...) should be replaced with
+ * ble.securityManager().getLinkSecurity(...).
+ */
+ ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
+ return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
+ }
+
+ /**
+ * 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 and/or
+ * application registration.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.purgeAllBondingState() should be replaced with
+ * ble.securityManager().purgeAllBondingState().
+ */
+ ble_error_t purgeAllBondingState(void) {
+ return securityManager().purgeAllBondingState();
+ }
+
+ /**
* Setup a callback for timeout events. Refer to Gap::TimeoutSource_t for
* possible event types.
*
@@ -1184,6 +1175,83 @@
void onUpdatesDisabled(GattServer::EventCallback_t callback);
void onConfirmationReceived(GattServer::EventCallback_t callback);
+ /**
+ * Setup a callback for when the security setup procedure (key generation
+ * and exchange) for a link has started. This will be skipped for bonded
+ * devices. The callback is passed in parameters received from the peer's
+ * security request: bool allowBonding, bool requireMITM, and
+ * SecurityIOCapabilities_t.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecuritySetupInitiated(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupInitiated(callback).
+ */
+ void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
+ securityManager().onSecuritySetupInitiated(callback);
+ }
+
+ /**
+ * Setup a callback for when the security setup procedure (key generation
+ * and exchange) for a link has completed. This will be skipped for bonded
+ * devices. The callback is passed in the success/failure status of the
+ * security setup procedure.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecuritySetupCompleted(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupCompleted(callback).
+ */
+ void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
+ securityManager().onSecuritySetupCompleted(callback);
+ }
+
+ /**
+ * Setup a callback for when a link with the peer is secured. For bonded
+ * devices, subsequent reconnections with bonded peer will result only in
+ * this callback when the link is secured and setup procedures will not
+ * occur unless the bonding information is either lost or deleted on either
+ * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
+ * to the level of security in effect for the secured link.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onLinkSecured(callback) should be replaced with
+ * ble.securityManager().onLinkSecured(callback).
+ */
+ void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
+ securityManager().onLinkSecured(callback);
+ }
+
+ /**
+ * Setup a callback for successful bonding; i.e. that link-specific security
+ * context is stored persistently for a peer device.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecurityContextStored(callback) should be replaced with
+ * ble.securityManager().onSecurityContextStored(callback).
+ */
+ void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
+ securityManager().onSecurityContextStored(callback);
+ }
+
+ /**
+ * Setup a callback for when the passkey needs to be displayed on a
+ * peripheral with DISPLAY capability. This happens when security is
+ * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey)
+ * needs to be exchanged between the peers to authenticate the connection
+ * attempt.
+ *
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onPasskeyDisplay(callback) should be replaced with
+ * ble.securityManager().onPasskeyDisplay(callback).
+ */
+ void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
+ return securityManager().onPasskeyDisplay(callback);
+ }
+
public:
BLE() : transport(createBLEInstance()) {
/* empty */
@@ -1247,55 +1315,4 @@
transport->getGattServer().setOnConfirmationReceived(callback);
}
-inline ble_error_t
-BLE::initializeSecurity(bool enableBonding,
- bool requireMITM,
- Gap::SecurityIOCapabilities_t iocaps,
- const Gap::Passkey_t passkey)
-{
- return transport->initializeSecurity(enableBonding, requireMITM, iocaps, passkey);
-}
-
-inline void
-BLE::onSecuritySetupInitiated(Gap::SecuritySetupInitiatedCallback_t callback)
-{
- gap().setOnSecuritySetupInitiated(callback);
-}
-
-inline void
-BLE::onSecuritySetupCompleted(Gap::SecuritySetupCompletedCallback_t callback)
-{
- gap().setOnSecuritySetupCompleted(callback);
-}
-
-inline void
-BLE::onLinkSecured(Gap::LinkSecuredCallback_t callback)
-{
- gap().setOnLinkSecured(callback);
-}
-
-inline void
-BLE::onSecurityContextStored(Gap::HandleSpecificEvent_t callback)
-{
- gap().setOnSecurityContextStored(callback);
-}
-
-inline void
-BLE::onPasskeyDisplay(Gap::PasskeyDisplayCallback_t callback)
-{
- return gap().setOnPasskeyDisplay(callback);
-}
-
-inline ble_error_t
-BLE::getLinkSecurity(Gap::Handle_t connectionHandle, Gap::LinkSecurityStatus_t *securityStatusP)
-{
- return gap().getLinkSecurity(connectionHandle, securityStatusP);
-}
-
-inline ble_error_t
-BLE::purgeAllBondingState(void)
-{
- return gap().purgeAllBondingState();
-}
-
#endif // ifndef __BLE_H__
\ No newline at end of file