security_manager.hpp

Go to the documentation of this file.

 
#ifndef ELEC_C7222_BLE_SECURITY_MANAGER_H_
#define ELEC_C7222_BLE_SECURITY_MANAGER_H_
 
#include <cstdint>
#include <iosfwd>
#include <list>
 
#include "ble_error.hpp"
#include "gap.hpp"
#include "non_copyable.hpp"
 
namespace c7222 {
 
class SecurityManager : public NonCopyableNonMovable {
   public:
    enum class EventId : uint8_t {
        kJustWorksRequest,
        kNumericComparisonRequest,
        kPasskeyDisplay,
        kPasskeyInput,
        kPairingComplete,
        kReencryptionComplete,
        kAuthorizationRequest,
        kAuthorizationResult,
    };
 
    enum class IoCapability : uint8_t {
        kDisplayOnly,
        kDisplayYesNo,
        kKeyboardOnly,
        kNoInputNoOutput,
        kKeyboardDisplay,
    };
 
    enum class AuthenticationRequirement : uint8_t {
        kNone = 0,
        kBonding = 1u << 0,
        kMitmProtection = 1u << 1,
        kSecureConnections = 1u << 2,
        kKeypressNotifications = 1u << 3,
    };
 
    enum class PairingStatus : uint8_t {
        kSuccess = 0x00,
        kFailed = 0x01,
        kTimeout = 0x02,
        kUnsupported = 0x03,
        kUnknown = 0xFF,
    };
 
    enum class AuthorizationResult : uint8_t {
        kDenied = 0,
        kGranted = 1,
    };
 
    enum class FixedPasskeyRole : uint8_t {
        kNone = 0,
        kDisplay = 1,
        kKeyboard = 2,
    };
 
    enum class GattClientSecurityLevel : uint8_t {
        kLevel0 = 0,
        kLevel1 = 1,
        kLevel2 = 2,
        kLevel3 = 3,
        kLevel4 = 4,
    };
 
    struct SecurityParameters {
        IoCapability io_capability = IoCapability::kNoInputNoOutput;
        AuthenticationRequirement authentication = AuthenticationRequirement::kBonding;
        uint8_t min_encryption_key_size = 7;
        uint8_t max_encryption_key_size = 16;
        bool bondable = true;
        bool secure_connections_only = false;
        GattClientSecurityLevel gatt_client_required_security_level = GattClientSecurityLevel::kLevel0;
        uint32_t fixed_passkey = 0;
        FixedPasskeyRole fixed_passkey_role = FixedPasskeyRole::kNone;
    };
 
    struct EventHandler {
        virtual void OnJustWorksRequest(ConnectionHandle connection_handle) const {}
        virtual void OnNumericComparisonRequest(ConnectionHandle connection_handle,
                                                uint32_t numeric_value) const {}
        virtual void OnPasskeyDisplay(ConnectionHandle connection_handle, uint32_t passkey) const {}
        virtual void OnPasskeyInput(ConnectionHandle connection_handle) const {}
        virtual void OnPairingComplete(ConnectionHandle connection_handle,
                                       PairingStatus status,
                                       uint8_t status_code) const {}
        virtual void OnReencryptionComplete(ConnectionHandle connection_handle,
                                            uint8_t status_code) const {}
        virtual void OnAuthorizationRequest(ConnectionHandle connection_handle) const {}
        virtual void OnAuthorizationResult(ConnectionHandle connection_handle,
                                           AuthorizationResult result) const {}
 
       protected:
        ~EventHandler() = default;
    };
 
    static SecurityManager* GetInstance();
 
    // -----------------------------------------------------------------
    // Configuration (intended to be called before connections)
    // -----------------------------------------------------------------
 
    BleError Configure(const SecurityParameters& params);
 
    BleError SetIoCapability(IoCapability capability);
    BleError SetAuthenticationRequirements(AuthenticationRequirement auth);
    BleError SetEncryptionKeySizeRange(uint8_t min_key_size, uint8_t max_key_size);
    BleError SetBondable(bool bondable);
    BleError SetSecureConnectionsOnly(bool enabled);
    BleError SetGattClientRequiredSecurityLevel(GattClientSecurityLevel level);
    BleError SetFixedPasskeyDisplay(uint32_t passkey);
    BleError SetFixedPasskeyKeyboard(uint32_t passkey);
    BleError ClearFixedPasskey();
 
    [[nodiscard]] SecurityParameters GetSecurityParameters() const {
        return params_;
    }
 
    [[nodiscard]] bool IsConfigured() const {
        return configured_;
    }
 
    [[nodiscard]] bool IsApplied() const {
        return applied_;
    }
 
    bool ValidateConfiguration(bool authentication_required,
                               bool authorization_required,
                               bool encryption_required) const;
 
    // -----------------------------------------------------------------
    // Event handlers
    // -----------------------------------------------------------------
 
    void AddEventHandler(const EventHandler& handler);
    bool RemoveEventHandler(const EventHandler& handler);
    void AddEventHandler(const EventHandler* handler);
    bool RemoveEventHandler(const EventHandler* handler);
    void ClearEventHandlers();
    [[nodiscard]] size_t GetEventHandlerCount() const {
        return handlers_.size();
    }
    // -----------------------------------------------------------------
    // Pairing / authorization responses
    // -----------------------------------------------------------------
 
    BleError ConfirmJustWorks(ConnectionHandle con_handle);
    BleError ConfirmNumericComparison(ConnectionHandle con_handle, bool accept);
    BleError ProvidePasskey(ConnectionHandle con_handle, uint32_t passkey);
    BleError RequestPairing(ConnectionHandle con_handle);
    BleError SetAuthorization(ConnectionHandle con_handle, AuthorizationResult result);
 
    BleError DispatchBleHciPacket(uint8_t packet_type, const uint8_t* packet, uint16_t size);
 
   private:
    SecurityManager() = default;
    ~SecurityManager() = default;
 
    BleError ApplyConfiguration();
 
    void DispatchJustWorksRequest(ConnectionHandle con_handle) const;
    void DispatchNumericComparisonRequest(ConnectionHandle con_handle, uint32_t number) const;
    void DispatchPasskeyDisplay(ConnectionHandle con_handle, uint32_t passkey) const;
    void DispatchPasskeyInput(ConnectionHandle con_handle) const;
    void DispatchPairingComplete(ConnectionHandle con_handle,
                                 PairingStatus status,
                                 uint8_t status_code) const;
    void DispatchReencryptionComplete(ConnectionHandle con_handle, uint8_t status) const;
    void DispatchAuthorizationRequest(ConnectionHandle con_handle) const;
    void DispatchAuthorizationResult(ConnectionHandle con_handle, AuthorizationResult result) const;
 
    static SecurityManager* instance_;
 
    SecurityParameters params_{};
    std::list<const EventHandler*> handlers_{};
    bool configured_ = false;
    bool applied_ = false;
};
 
// ---------------------------------------------------------------------
// Bitmask helpers for AuthenticationRequirement
// ---------------------------------------------------------------------
 
constexpr SecurityManager::AuthenticationRequirement
operator|(SecurityManager::AuthenticationRequirement lhs,
          SecurityManager::AuthenticationRequirement rhs) {
    return static_cast<SecurityManager::AuthenticationRequirement>(static_cast<uint8_t>(lhs) |
                                                                   static_cast<uint8_t>(rhs));
}
 
constexpr SecurityManager::AuthenticationRequirement
operator&(SecurityManager::AuthenticationRequirement lhs,
          SecurityManager::AuthenticationRequirement rhs) {
    return static_cast<SecurityManager::AuthenticationRequirement>(static_cast<uint8_t>(lhs) &
                                                                   static_cast<uint8_t>(rhs));
}
 
constexpr SecurityManager::AuthenticationRequirement
operator^(SecurityManager::AuthenticationRequirement lhs,
          SecurityManager::AuthenticationRequirement rhs) {
    return static_cast<SecurityManager::AuthenticationRequirement>(static_cast<uint8_t>(lhs) ^
                                                                   static_cast<uint8_t>(rhs));
}
 
constexpr SecurityManager::AuthenticationRequirement
operator~(SecurityManager::AuthenticationRequirement value) {
    return static_cast<SecurityManager::AuthenticationRequirement>(~static_cast<uint8_t>(value));
}
 
inline SecurityManager::AuthenticationRequirement&
operator|=(SecurityManager::AuthenticationRequirement& lhs,
           SecurityManager::AuthenticationRequirement rhs) {
    lhs = lhs | rhs;
    return lhs;
}
 
inline SecurityManager::AuthenticationRequirement&
operator&=(SecurityManager::AuthenticationRequirement& lhs,
           SecurityManager::AuthenticationRequirement rhs) {
    lhs = lhs & rhs;
    return lhs;
}
 
inline SecurityManager::AuthenticationRequirement&
operator^=(SecurityManager::AuthenticationRequirement& lhs,
           SecurityManager::AuthenticationRequirement rhs) {
    lhs = lhs ^ rhs;
    return lhs;
}
 
std::ostream& operator<<(std::ostream& os, const SecurityManager& sm);
 
}  // namespace c7222
 
#endif  // ELEC_C7222_BLE_SECURITY_MANAGER_H_