# tls

**Repository Path**: rippleos/tls

## Basic Information

- **Project Name**: tls
- **Description**: MOSS TLS 安全传输模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mtls - 安全传输层模块

## 概述

mtls 是 MOSS 中间件的安全传输层模块，提供 TLS/DTLS 加密通信，为 V2X 通信、OTA 升级、远程诊断等场景提供安全基础。

## 架构设计

### 模块定位

```
┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  (upgrade/OTA, diag/UDS, someip/V2X, com/RPC...)       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       mtls (NEW)                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ CertManager  │  │  TLSContext  │  │  DTLSContext │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ TLSSocket    │  │ DTLSocket    │  │ SecureConfig │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    mbed TLS Library                          │
│         (轻量级 TLS/DTLS 实现，适合嵌入式/汽车)               │
└─────────────────────────────────────────────────────────────┘
```

### 依赖关系

```yaml
mtls:
  depends_on:
    - mruntime  # Clock, 工具类
    - mlog      # 日志
  external:
    - mbed TLS (v3.x)  # 推荐：轻量级、适合嵌入式
```

### 为什么选择 mbed TLS

| 特性 | mbed TLS | OpenSSL | wolfSSL |
|------|----------|---------|---------|
| 代码体积 | ~200KB | ~2MB | ~200KB |
| 内存占用 | 低 | 高 | 低 |
| DTLS 支持 | ✅ | ✅ | ✅ |
| C++17 兼容 | ✅ | ✅ | ✅ |
| 汽车认证 | 易于 | 困难 | 易于 |
| 许可证 | Apache 2.0 | Apache 2.0 | GPL/商业 |
| 嵌入式优化 | ✅ | ❌ | ✅ |

### 目录结构

```
moss/tls/
├── CMakeLists.txt
├── README.md
├── include/tls/
│   ├── mtls.h                 # 模块入口
│   ├── types.h                # 类型定义
│   ├── cert_manager.h         # 证书管理
│   ├── tls_context.h          # TLS 上下文
│   ├── dtls_context.h         # DTLS 上下文
│   ├── tls_socket.h           # TLS Socket 封装
│   ├── dtls_socket.h          # DTLS Socket 封装
│   └── secure_config.h        # 安全配置
├── src/
│   ├── mtls.cpp
│   ├── cert_manager.cpp
│   ├── tls_context.cpp
│   ├── dtls_context.cpp
│   ├── tls_socket.cpp
│   ├── dtls_socket.cpp
│   └── secure_config.cpp
├── test/
│   ├── test_cert_manager.cpp
│   ├── test_tls_context.cpp
│   ├── test_dtls_context.cpp
│   └── test_tls_socket.cpp
└── cmake/
    └── mtlsConfig.cmake.in
```

## 核心组件

### 1. CertManager - 证书管理器

管理 X.509 证书、私钥和 CA 证书链。

```cpp
namespace moss {
namespace mtls {

enum class CertFormat {
    PEM,
    DER
};

struct CertInfo {
    std::string subject;
    std::string issuer;
    std::string serial_number;
    uint64_t not_before{0};
    uint64_t not_after{0};
    bool is_ca{false};
    bool is_valid{false};
};

class CertManager {
public:
    static CertManager& instance();

    // 证书加载
    bool load_ca_cert(const std::string& path, CertFormat format = CertFormat::PEM);
    bool load_cert(const std::string& path, CertFormat format = CertFormat::PEM);
    bool load_private_key(const std::string& path, CertFormat format = CertFormat::PEM);

    // 内存加载
    bool load_ca_cert(const uint8_t* data, size_t len, CertFormat format);
    bool load_cert(const uint8_t* data, size_t len, CertFormat format);
    bool load_private_key(const uint8_t* data, size_t len, CertFormat format);

    // 证书验证
    bool verify_cert();
    CertInfo get_cert_info() const;

    // 导出
    std::vector<uint8_t> export_cert_der() const;

private:
    CertManager();
    ~CertManager();

    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mtls
}  // namespace moss
```

### 2. TLSContext - TLS 上下文

配置 TLS 连接参数，管理 SSL 上下文。

```cpp
namespace moss {
namespace mtls {

enum class TLSVersion {
    TLS_1_2,
    TLS_1_3
};

enum class VerifyMode {
    NONE,           // 不验证
    OPTIONAL,       // 可选验证
    REQUIRED,       // 必须验证
    REQUIRED_STRICT // 严格验证 + 主机名检查
};

struct TLSConfig {
    TLSVersion min_version{TLSVersion::TLS_1_2};
    TLSVersion max_version{TLSVersion::TLS_1_3};
    VerifyMode verify_mode{VerifyMode::REQUIRED};

    // 推荐的汽车级密码套件
    std::vector<std::string> cipher_suites = {
        // TLS 1.3
        "TLS_AES_256_GCM_SHA384",
        "TLS_CHACHA20_POLY1305_SHA256",
        "TLS_AES_128_GCM_SHA256",
        // TLS 1.2
        "ECDHE-ECDSA-AES256-GCM-SHA384",
        "ECDHE-ECDSA-AES128-GCM-SHA256",
        "ECDHE-RSA-AES256-GCM-SHA384",
        "ECDHE-RSA-AES128-GCM-SHA256"
    };

    bool enable_session_resumption{true};
    bool enable_ocsp_stapling{false};
    std::string server_name;  // SNI
};

class TLSContext {
public:
    TLSContext();
    ~TLSContext();

    // 配置
    void set_config(const TLSConfig& config);
    void set_cert_manager(CertManager& manager);

    // 角色
    void set_server_mode();
    void set_client_mode();

    // 内部上下文
    void* native_handle();

private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mtls
}  // namespace moss
```

### 3. DTLSContext - DTLS 上下文

配置 DTLS (Datagram TLS) 连接参数，用于 UDP 场景如 SOME/IP。

```cpp
namespace moss {
namespace mtls {

struct DTLSConfig : public TLSConfig {
    // DTLS 特定配置
    uint32_t handshake_timeout_ms{10000};
    uint32_t retransmit_timeout_ms{1000};
    uint16_t mtu{1400};  // 避免 IP 分片
};

class DTLSContext {
public:
    DTLSContext();
    ~DTLSContext();

    void set_config(const DTLSConfig& config);
    void set_cert_manager(CertManager& manager);

    void set_server_mode();
    void set_client_mode();

    void* native_handle();

private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mtls
}  // namespace moss
```

### 4. TLSSocket - TLS Socket 封装

封装 TCP + TLS，提供安全的流式 Socket。

```cpp
namespace moss {
namespace mtls {

class TLSSocket {
public:
    using ReadCallback = std::function<void(const uint8_t* data, size_t len)>;
    using ErrorCallback = std::function<void(int error_code, const std::string& msg)>;

    TLSSocket(TLSContext& context);
    ~TLSSocket();

    // 客户端
    bool connect(const std::string& host, uint16_t port);
    void disconnect();

    // 服务端
    bool bind(uint16_t port);
    bool listen(int backlog = 5);
    std::shared_ptr<TLSSocket> accept();

    // 数据传输
    ssize_t send(const uint8_t* data, size_t len);
    ssize_t send(const std::vector<uint8_t>& data);
    ssize_t recv(uint8_t* buffer, size_t max_len);
    std::vector<uint8_t> recv_all(size_t max_len = 4096);

    // 异步模式
    void set_nonblocking(bool enable);
    void set_read_callback(ReadCallback callback);
    void set_error_callback(ErrorCallback callback);

    // 状态
    bool is_connected() const;
    bool is_secure() const;
    std::string peer_cert_subject() const;

    // Socket 选项
    void set_timeout_ms(uint32_t timeout_ms);

private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mtls
}  // namespace moss
```

### 5. DTLSocket - DTLS Socket 封装

封装 UDP + DTLS，用于 SOME/IP 等基于 UDP 的协议。

```cpp
namespace moss {
namespace mtls {

class DTLSocket {
public:
    using ReadCallback = std::function<void(const uint8_t* data, size_t len,
                                            const std::string& from_ip, uint16_t from_port)>;

    DTLSocket(DTLSContext& context);
    ~DTLSocket();

    // 服务端模式
    bool bind(uint16_t port);
    void start_handshake();

    // 客户端模式
    bool connect(const std::string& host, uint16_t port);
    void disconnect();

    // 数据报传输
    ssize_t send(const uint8_t* data, size_t len);
    ssize_t send(const std::vector<uint8_t>& data);
    ssize_t recv(uint8_t* buffer, size_t max_len);

    // 发送到特定地址 (服务端)
    ssize_t send_to(const uint8_t* data, size_t len,
                    const std::string& ip, uint16_t port);

    // 异步模式
    void set_nonblocking(bool enable);
    void set_read_callback(ReadCallback callback);

    // 状态
    bool is_connected() const;
    std::string peer_cert_subject() const;

private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mtls
}  // namespace moss
```

### 6. SecureConfig - 安全配置

集中管理安全配置参数。

```cpp
namespace moss {
namespace mtls {

struct SecureConfig {
    // 证书路径
    std::string ca_cert_path;
    std::string cert_path;
    std::string key_path;

    // 或内存数据
    std::vector<uint8_t> ca_cert_data;
    std::vector<uint8_t> cert_data;
    std::vector<uint8_t> key_data;

    // 验证模式
    VerifyMode verify_mode{VerifyMode::REQUIRED};

    // 协议版本
    TLSVersion min_version{TLSVersion::TLS_1_2};

    // 是否为服务端
    bool is_server{false};

    // 日志级别 (0=静默, 1=错误, 2=警告, 3=信息, 4=调试)
    int debug_level{0};
};

class SecureConfigManager {
public:
    static SecureConfigManager& instance();

    void load_from_file(const std::string& config_path);
    void save_to_file(const std::string& config_path) const;

    void set_config(const SecureConfig& config);
    const SecureConfig& config() const;

    // 证书路径解析
    std::string resolve_path(const std::string& path) const;

private:
    SecureConfigManager();
    SecureConfig config_;
};

}  // namespace mtls
}  // namespace moss
```

## 模块集成

### mcom 集成

```cpp
// mcom TLS Transport
namespace moss {
namespace mcom {

class TLSTransport : public Transport {
public:
    TLSTransport(mtls::TLSContext& context);

    bool connect(const std::string& host, uint16_t port) override;
    ssize_t send(const uint8_t* data, size_t len) override;
    ssize_t recv(uint8_t* buffer, size_t max_len) override;

private:
    mtls::TLSSocket socket_;
};

}  // namespace mcom
}  // namespace moss
```

### msomeip DTLS 集成

```cpp
// msomeip DTLS Endpoint
namespace moss {
namespace msomeip {

class DTLSEndpoint : public UDPEndpoint {
public:
    DTLSEndpoint(mtls::DTLSContext& context);

    bool bind(uint16_t port) override;
    ssize_t send_to(const uint8_t* data, size_t len,
                   const std::string& ip, uint16_t port) override;

private:
    mtls::DTLSocket socket_;
};

}  // namespace msomeip
}  // namespace moss
```

### mupgrade HTTPS 集成

```cpp
// mupgrade HTTPS Client
namespace moss {
namespace mupgrade {

class HTTPSClient {
public:
    HTTPSClient();

    bool set_ca_cert(const std::string& path);
    Response get(const std::string& url);
    Response post(const std::string& url, const std::vector<uint8_t>& body);

private:
    mtls::TLSContext context_;
    mtls::CertManager cert_manager_;
};

}  // namespace mupgrade
}  // namespace moss
```

## 汽车安全考量

### 推荐密码套件

```cpp
// 汽车级安全配置
inline std::vector<std::string> automotive_cipher_suites() {
    return {
        // TLS 1.3 (推荐)
        "TLS_AES_256_GCM_SHA384",        // AES-256-GCM
        "TLS_CHACHA20_POLY1305_SHA256",  // ChaCha20-Poly1305

        // TLS 1.2 (兼容)
        "ECDHE-ECDSA-AES256-GCM-SHA384", // ECDSA + AES-256
        "ECDHE-ECDSA-AES128-GCM-SHA256", // ECDSA + AES-128
    };
}
```

### 证书管理

```cpp
// ECU 证书生命周期
class ECUCertManager {
public:
    // 加载 ECU 身份证书
    bool load_ecu_cert(const std::string& path);

    // 加载 CA 证书链
    bool load_ca_chain(const std::string& path);

    // 证书过期检查
    bool check_expiry(uint32_t days_before = 30);

    // 证书更新 (OTA)
    bool update_cert(const std::vector<uint8_t>& new_cert);

private:
    CertManager cert_manager_;
};
```

### 安全日志

```cpp
// 安全事件日志
enum class SecurityEvent {
    CERT_EXPIRED,
    CERT_INVALID,
    HANDSHAKE_FAILED,
    VERIFY_FAILED,
    CIPHER_MISMATCH
};

void log_security_event(SecurityEvent event, const std::string& detail);
```

## CMake 配置

```cmake
cmake_minimum_required(VERSION 3.14)
project(mtls VERSION 0.1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# mbed TLS
find_package(MbedTLS REQUIRED)

add_library(mtls SHARED
    src/mtls.cpp
    src/cert_manager.cpp
    src/tls_context.cpp
    src/dtls_context.cpp
    src/tls_socket.cpp
    src/dtls_socket.cpp
    src/secure_config.cpp
)

target_include_directories(mtls PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>
)

target_link_libraries(mtls PUBLIC
    MbedTLS::mbedtls
    MbedTLS::mbedx509
    MbedTLS::mbedcrypto
)

target_compile_options(mtls PRIVATE -Wall -Wextra -Wpedantic)

# 安装...
```

## 测试计划

| 测试文件 | 覆盖范围 |
|----------|----------|
| test_cert_manager.cpp | 证书加载、验证、导出 |
| test_tls_context.cpp | TLS 配置、上下文创建 |
| test_dtls_context.cpp | DTLS 配置、上下文创建 |
| test_tls_socket.cpp | TLS 连接、数据传输 |
| test_dtls_socket.cpp | DTLS 连接、数据报传输 |

## 里程碑

| 里程碑 | 内容 | 预计工时 |
|--------|------|----------|
| mtls-ms1 | 证书管理 + TLS/DTLS Context | 2天 |
| mtls-ms2 | TLSSocket 实现 | 1天 |
| mtls-ms3 | DTLSocket 实现 | 1天 |
| mtls-ms4 | 测试 + 文档 | 1天 |

**总计: 5个工作日**