mirror of https://github.com/ARMmbed/mbed-os.git
252 lines
9.0 KiB
C++
252 lines
9.0 KiB
C++
/* mbed Microcontroller Library
|
|
* Copyright (c) 2020 ARM Limited
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* 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 BLE_PAL_PRIVATE_ADDRESS_CONTROLLER_H
|
|
#define BLE_PAL_PRIVATE_ADDRESS_CONTROLLER_H
|
|
|
|
#if BLE_FEATURE_PRIVACY
|
|
|
|
#include "ble/common/BLETypes.h"
|
|
#include "ble/common/blecommon.h"
|
|
#include "GapTypes.h"
|
|
|
|
namespace ble {
|
|
|
|
/**
|
|
* Control the controller resolution list, resolve private addresses and generate
|
|
* new ones.
|
|
*/
|
|
struct PalPrivateAddressController {
|
|
struct EventHandler {
|
|
#if BLE_GAP_HOST_BASED_PRIVATE_ADDRESS_RESOLUTION
|
|
/** Called when the address resolution request has completed.
|
|
*
|
|
* @param success true if the address has been resolved and false otherwise.
|
|
*/
|
|
virtual void on_private_address_resolved(bool success) = 0;
|
|
#endif // BLE_GAP_HOST_BASED_PRIVATE_ADDRESS_RESOLUTION
|
|
|
|
/** Called when the resolvable private address request has completed.
|
|
*
|
|
* @param rpa The address generated. In case of failure, the address is
|
|
* equal to an invalid address (default value from address_t).
|
|
*/
|
|
virtual void on_resolvable_private_address_generated(const address_t &rpa) = 0;
|
|
|
|
/**
|
|
* Called when a new item has been added or removed to the resolving list
|
|
* or if the resolving list has been cleared.
|
|
*/
|
|
virtual void on_resolving_list_action_complete() = 0;
|
|
};
|
|
|
|
/**
|
|
* Initialize the address registry module
|
|
* @return BLE_ERROR_NONE in case of success.
|
|
*/
|
|
virtual ble_error_t initialize() = 0;
|
|
|
|
/**
|
|
* Terminate the address registry module
|
|
* @return BLE_ERROR_NONE in case of success.
|
|
*/
|
|
virtual ble_error_t terminate() = 0;
|
|
|
|
/** Generate a new resolvable private address from an IRK
|
|
*
|
|
* The completion of the request is signaled by the stack with a call to
|
|
* PalPrivateAddressController::on_resolvable_private_address_generated.
|
|
*
|
|
* @param local_irk The IRK to use to generate the address.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note Addresses are generated one at a time, this function should not be
|
|
* called while an address is being generated.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 6 PartB: 1.3.2.2 Private Device Address Generation
|
|
*/
|
|
virtual ble_error_t generate_resolvable_private_address(const irk_t& local_irk) = 0;
|
|
|
|
/** Generate a new non-resolvable private address
|
|
*
|
|
* @return The address generated.
|
|
*
|
|
* @note The address generated might be invalid (all zeros).
|
|
*
|
|
* @note: See Bluetooth 5 Vol 6 PartB: 1.3.2.2 Private Device Address Generation
|
|
*/
|
|
virtual address_t generate_non_resolvable_private_address() = 0;
|
|
|
|
/** Attempt to resolve a resolvable private address received with an IRK.
|
|
*
|
|
* The completion of the request is signaled by the stack with a call to
|
|
* PalGapEventHandler::on_private_address_resolved.
|
|
*
|
|
* @param address The address to resole
|
|
* @param irk The IRK used for the resolution of the address.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note Addresses are resolved one at a time, this function should not be
|
|
* called while an address is being resolved.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 6 PartB: 1.3.2.3 Private Device Address Resolution
|
|
*/
|
|
virtual ble_error_t resolve_private_address(
|
|
const address_t &address,
|
|
const irk_t& irk
|
|
) = 0;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// LL resolution and generation management
|
|
//
|
|
|
|
/** Check if privacy feature is supported by LL implementation
|
|
*
|
|
* @return true if privacy is supported, false otherwise.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 3 Part C: 10.7 Privacy feature.
|
|
*/
|
|
virtual bool is_ll_privacy_supported() = 0;
|
|
|
|
/** Enable or disable private addresses resolution
|
|
*
|
|
* @param enable whether to enable private addresses resolution
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.44 LE Set Address Resolution Enable command.
|
|
*/
|
|
virtual ble_error_t set_ll_address_resolution(
|
|
bool enable
|
|
) = 0;
|
|
|
|
/** Set the timeout for LL resolvable private address rotation.
|
|
*
|
|
* @param timeout The timeout after which the resolvable private address in
|
|
* the controller is changed.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.45 LE Set Resolvable Private Address Timeout Command
|
|
*/
|
|
virtual ble_error_t set_ll_resolvable_private_address_timeout(resolvable_address_timeout_t timeout) = 0;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Resolving list management
|
|
//
|
|
|
|
/** Return the resolving list capacity
|
|
*
|
|
* @return A positive number if LL privacy is supported, 0 if not.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.41 LE Read Resolving List Size Command.
|
|
*/
|
|
virtual uint8_t read_resolving_list_capacity() = 0;
|
|
|
|
/** Add a device definition into the resolving list.
|
|
*
|
|
* @param peer_address_type The type of the identity address received from the
|
|
* peer during bonding.
|
|
* @param peer_identity_address The identity address of the peer received
|
|
* during bonding.
|
|
* @param peer_irk The irk of the peer.
|
|
* @param local_irk The irk sent to the peer during bonding.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note: Cannot be used if address translation is enabled and the device is
|
|
* advertising/scanning or initiating.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.38 LE Add Device To Resolving List Command
|
|
*/
|
|
virtual ble_error_t add_device_to_resolving_list(
|
|
target_peer_address_type_t peer_address_type,
|
|
const address_t &peer_identity_address,
|
|
const irk_t& peer_irk,
|
|
const irk_t& local_irk
|
|
) = 0;
|
|
|
|
/** Remove a device definition from the resolving list.
|
|
*
|
|
* @param peer_address_type The type of the identity address received from the
|
|
* peer during bonding.
|
|
* @param peer_identity_address The identity address of the peer received
|
|
* during bonding.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note: Cannot be used if address translation is enabled and the device is
|
|
* advertising/scanning or initiating.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.39 LE Remove Device From Resolving List Command
|
|
*/
|
|
virtual ble_error_t remove_device_from_resolving_list(
|
|
target_peer_address_type_t peer_address_type,
|
|
const address_t &peer_identity_address
|
|
) = 0;
|
|
|
|
/** Remove all entries from the resolving list.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note: Cannot be used if address translation is enabled and the device is
|
|
* advertising/scanning or initiating.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.40 LE Clear Resolving List Command
|
|
*/
|
|
virtual ble_error_t clear_resolving_list() = 0;
|
|
|
|
/** Set the privacy mode (for LL controllers)
|
|
*
|
|
* @param peer_address_type The identity address type of the peer
|
|
* @param peer_address The identity address of the peer
|
|
* @param privacy_mode whether network or device privacy should be used for
|
|
* the peer.
|
|
*
|
|
* @return BLE_ERROR_NONE if the request has been successfully sent or the
|
|
* appropriate error otherwise.
|
|
*
|
|
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.77 LE Set Privacy Mode Command
|
|
*/
|
|
virtual ble_error_t set_peer_privacy_mode(
|
|
target_peer_address_type_t peer_address_type,
|
|
const address_t &peer_address,
|
|
privacy_mode_t privacy_mode
|
|
) = 0;
|
|
|
|
/**
|
|
* Set the event handler receiving events from this instance.
|
|
* @param handler The handler to use when an event happen.
|
|
*/
|
|
virtual void set_event_handler(EventHandler *handler) = 0;
|
|
};
|
|
|
|
} // namespace ble
|
|
|
|
#endif // BLE_FEATURE_PRIVACY
|
|
|
|
#endif //BLE_PAL_PRIVATE_ADDRESS_CONTROLLER_H
|