From 9d0c6381d49ba56742608c4d72581e59ebc05907 Mon Sep 17 00:00:00 2001 From: Andres Amaya Garcia Date: Fri, 8 Jan 2016 11:15:35 +0000 Subject: [PATCH] Add missing documentation to btle_security for whitelisting --- source/btle/btle_security.h | 27 +++++++++++++++++------- source/nRF5xGap.cpp | 42 +++++++++++++++++++++++++++++++++++++ source/nRF5xGap.h | 9 ++++++++ 3 files changed, 71 insertions(+), 7 deletions(-) diff --git a/source/btle/btle_security.h b/source/btle/btle_security.h index af4084f..54f5f5e 100644 --- a/source/btle/btle_security.h +++ b/source/btle/btle_security.h @@ -20,6 +20,15 @@ #include "ble/Gap.h" #include "ble/SecurityManager.h" +/** + * Function to test whether the SecurityManager has been initialized. + * Possible by a call to @ref btle_initializeSecurity(). + * + * @return True if the SecurityManager was previously initialized, false + * otherwise. + */ +bool btle_hasInitializedSecurity(void); + /** * Enable Nordic's Device Manager, which brings in functionality from the * stack's Security Manager. The Security Manager implements the actual @@ -40,8 +49,6 @@ ble_error_t btle_initializeSecurity(bool en SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE, const SecurityManager::Passkey_t passkey = NULL); -ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist); - /** * Get the security status of a link. * @@ -78,13 +85,19 @@ ble_error_t btle_setLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager ble_error_t btle_purgeAllBondingState(void); /** - * Function to test whether the SecurityManager has been initialized. - * Possible by a call to @ref btle_initializeSecurity(). + * Query the SoftDevice bond table to extract a whitelist containing the BLE + * addresses and IRKs of bonded devices. * - * @return True if the SecurityManager was previously initialized, false - * otherwise. + * @param[in/out] p_whitelist + * (on input) p_whitelist->addr_count and + * p_whitelist->irk_count specify the maximum number of + * addresses and IRKs added to the whitelist structure. + * (on output) *p_whitelist is a whitelist containing the + * addresses and IRKs of the bonded devices. + * + * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure. */ -bool btle_hasInitializedSecurity(void); +ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist); /** * Function to test whether a BLE address is generated using an IRK. diff --git a/source/nRF5xGap.cpp b/source/nRF5xGap.cpp index 99f7d14..5f1df7f 100644 --- a/source/nRF5xGap.cpp +++ b/source/nRF5xGap.cpp @@ -642,6 +642,48 @@ Gap::InitiatorPolicyMode_t nRF5xGap::getInitiatorPolicyMode(void) const return Gap::INIT_POLICY_IGNORE_WHITELIST; } +/**************************************************************************/ +/*! + @brief Helper function used to populate the ble_gap_whitelist_t that + will be used by the SoftDevice for filtering requests. + + @param[in] params + Basic advertising details, including the advertising + delay, timeout and how the device should be advertised + @params[in] advData + The primary advertising data payload + @params[in] scanResponse + The optional Scan Response payload if the advertising + type is set to \ref GapAdvertisingParams::ADV_SCANNABLE_UNDIRECTED + in \ref GapAdveritinngParams + + @returns \ref ble_error_t + + @retval BLE_ERROR_NONE + Everything executed properly + + @retval BLE_ERROR_BUFFER_OVERFLOW + The proposed action would cause a buffer overflow. All + advertising payloads must be <= 31 bytes, for example. + + @retval BLE_ERROR_NOT_IMPLEMENTED + A feature was requested that is not yet supported in the + nRF51 firmware or hardware. + + @retval BLE_ERROR_PARAM_OUT_OF_RANGE + One of the proposed values is outside the valid range. + + @note This function is needed because for the BLE API the whitelist + is just a collection of keys, but for the stack it also includes + the IRK table. + + @section EXAMPLE + + @code + + @endcode +*/ +/**************************************************************************/ ble_error_t nRF5xGap::generateStackWhitelist(void) { ble_gap_whitelist_t whitelistFromBondTable; diff --git a/source/nRF5xGap.h b/source/nRF5xGap.h index 751133b..c417239 100644 --- a/source/nRF5xGap.h +++ b/source/nRF5xGap.h @@ -92,6 +92,10 @@ public: virtual ble_error_t reset(void); + /* + * The following functions are part of the whitelisting experimental API. + * Therefore, this functionality can change in the near future. + */ virtual uint8_t getMaxWhitelistSize(void) const; virtual ble_error_t getWhitelist(Gap::Whitelist_t &whitelistOut) const; virtual ble_error_t setWhitelist(const Gap::Whitelist_t &whitelistIn); @@ -118,6 +122,10 @@ public: #endif private: + /* + * Whitelisting API related structures and helper functions. + */ + /* Policy modes set by the user. By default these are set to ignore the whitelist */ Gap::AdvertisingPolicyMode_t advertisingPolicyMode; Gap::ScanningPolicyMode_t scanningPolicyMode; @@ -139,6 +147,7 @@ private: */ ble_error_t generateStackWhitelist(void); +private: bool radioNotificationCallbackParam; /* parameter to be passed into the Timeout-generated radio notification callback. */ Timeout radioNotificationTimeout;