Add missing documentation to btle_security for whitelisting

This commit is contained in:
Andres Amaya Garcia 2016-01-08 11:15:35 +00:00
parent 2ebbcb08b5
commit 9d0c6381d4
3 changed files with 71 additions and 7 deletions

View file

@ -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.

View file

@ -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;

View file

@ -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;