跨平台 Keystore 抽象层设计：接口定义、平台适配器、密钥生命周期管理、依赖注入

1. 原理

蓝牙敏感数据的持久化必须依赖 OS 安全的 Keytore（iOS Keychain、Android Keystore、Linux Secret Service/Keyring）。直接调用平台 SDK 会导致代码高度耦合、难以测试、不利于跨平台编译。
跨平台 Keystore 抽象层的目标：

• 定义纯虚接口（Protocol/Interface），隐藏平台细节。
• 为每个平台实现一个适配器（Adapter），编译时或运行时注入。
• 统一密钥生命周期：生成、存储、读取、轮换、删除。
• 通过依赖注入（DI）容器管理适配器实例，避免全局静态单例。

抽象层核心接口 IKSCryptoStore 应包含对密钥 blob 和元数据的操作，且所有数据以二进制 buffer 传递，不暴露平台的 CFData/KeyStoreReference 等类型。

2. 架构 SVG：抽象层结构图

3. 实现流程

1. 定义接口（header-only）：创建 IKSCryptoStore.h，包含纯虚方法：storeKey、retrieveKey、deleteKey、keyExists、rotateKey。
2. 实现平台适配器：
   • iOSAdapter：调用 SecItemAdd/SecItemCopyMatching/SecItemDelete，使用 kSecClassKey。
   • AndroidAdapter：使用 java.security.KeyStore，通过 JNI 桥接或 C++ NDK attestation 库。
   • LinuxAdapter：调用 libsecret API 或直接读写 gnome-keyring D-Bus。
3. 实现密钥生命周期管理器：轮换策略（定时/事件驱动）、过期自动删除、备份标志。
4. 实现依赖注入容器：单例模板工厂，支持接口类型注册、智能指针管理、测试时传入 Mock 适配器。
5. 编译时选择适配器：通过 CMake 条件编译，仅包含目标平台的源文件。

4. 核心代码 / API 示例

4.1 接口定义（IKSCryptoStore.h）

// IKSCryptoStore.h
#pragma once
#include <string>
#include <vector>
#include <memory>

class IKSCryptoStore {
public:
    virtual ~IKSCryptoStore() = default;

    // 存储密钥数据（二进制 blob），keyId 为 UTF-8 字符串
    virtual bool storeKey(const std::string& keyId,
                          const std::vector<uint8_t>& data) = 0;

    // 读取密钥数据
    virtual std::vector<uint8_t> retrieveKey(const std::string& keyId) = 0;

    // 删除密钥
    virtual bool deleteKey(const std::string& keyId) = 0;

    // 检查密钥是否存在
    virtual bool keyExists(const std::string& keyId) = 0;

    // 轮换密钥：生成新数据，保留旧数据可选
    virtual bool rotateKey(const std::string& keyId,
                           const std::vector<uint8_t>& newData,
                           bool keepOld = false) = 0;
};

4.2 iOS 适配器（iOSAdapter.mm）

// iOSAdapter.mm
#include "IKSCryptoStore.h"
#import <Security/Security.h>

class iOSAdapter : public IKSCryptoStore {
public:
    bool storeKey(const std::string& keyId,
                  const std::vector<uint8_t>& data) override {
        CFStringRef tag = CFStringCreateWithCString(nullptr, keyId.c_str(),
                                                     kCFStringEncodingUTF8);
        NSData* keyData = [NSData dataWithBytes:data.data()
                                         length:data.size()];
        NSDictionary* attrs = @{
            (id)kSecClass : (id)kSecClassKey,
            (id)kSecAttrApplicationTag : (__bridge id)tag,
            (id)kSecValueData : keyData,
            (id)kSecAttrAccessible : (id)kSecAttrAccessibleWhenUnlockedThisDeviceOnly
        };
        OSStatus status = SecItemAdd((CFDictionaryRef)attrs, nullptr);
        CFRelease(tag);
        return status == errSecSuccess;
    }
    // … 其他方法类似
};

4.3 密钥生命周期管理器（KeyLifecycleManager.h/.cpp）

// KeyLifecycleManager.h
#pragma once
#include "IKSCryptoStore.h"
#include <chrono>
#include <functional>

class KeyLifecycleManager {
public:
    explicit KeyLifecycleManager(std::shared_ptr<IKSCryptoStore> store);

    // 注册轮换策略：定时（毫秒）或回调
    void setRotationPolicy(const std::string& keyId,
                           std::chrono::milliseconds interval,
                           std::function<std::vector<uint8_t>()> generator);

    // 启动后台轮换线程（简单示例）
    void start();

private:
    std::shared_ptr<IKSCryptoStore> store_;
    // 内部线程 + 调度映射
};

4.4 依赖注入容器（DIContainer.h）

// DIContainer.h
#pragma once
#include <unordered_map>
#include <memory>
#include <typeindex>
#include "IKSCryptoStore.h"

class DIContainer {
public:
    template<typename T>
    void registerInstance(std::shared_ptr<T> instance) {
        map_[std::type_index(typeid(T))] = instance;
    }

    template<typename T>
    std::shared_ptr<T> resolve() const {
        auto it = map_.find(std::type_index(typeid(T)));
        if (it != map_.end()) {
            return std::static_pointer_cast<T>(it->second);
        }
        return nullptr;
    }

private:
    std::unordered_map<std::type_index, std::shared_ptr<void>> map_;
};

// 使用示例（main.cpp）
DIContainer di;
di.registerInstance<IKSCryptoStore>(std::make_shared<iOSAdapter>());
auto manager = std::make_shared<KeyLifecycleManager>(
                     di.resolve<IKSCryptoStore>());

5. 调试

• 单元测试：编写 Mock 适配器（继承 IKSCryptoStore），验证 KeyLifecycleManager 调用预期方法。
• 日志注入：在适配器中记录每次操作（密钥ID、操作类型、返回值），打印到 std::clog 或 syslog。
• 平台离线测试：Linux 上使用 secret-tool 命令验证 LinuxAdapter 是否正确存储。
• Mock 示例：

// MockCryptoStore.h
class MockCryptoStore : public IKSCryptoStore {
public:
    MOCK_METHOD(bool, storeKey, (const std::string&, const std::vector<uint8_t>&), override);
    MOCK_METHOD(std::vector<uint8_t>, retrieveKey, (const std::string&), override);
    // ...
};

6. 部署

使用 CMake 条件编译，根据目标平台选择适配器源文件：

# CMakeLists.txt 片段
if(APPLE)
    set(PLATFORM_SRC src/iOSAdapter.mm)
elseif(ANDROID)
    set(PLATFORM_SRC src/AndroidAdapter.cpp)
elseif(UNIX AND NOT APPLE)
    set(PLATFORM_SRC src/LinuxAdapter.cpp)
endif()

add_library(ks_crypto
    src/IKSCryptoStore.h
    src/KeyLifecycleManager.cpp
    ${PLATFORM_SRC}
    src/DIContainer.h
)

依赖注入容器是 header-only，无需额外编译。Android 上需链接 -lssl -lcrypto（OpenSSL 辅助），iOS 需链接 Security.framework。

7. 常见错误

8. 性能与稳定性优化