/**
 * @file mqtt_crypto.h
 * @brief MQTT客户端SDK 加密模块（极简通用接口，静态内存轻量版）
 * @copyright Copyright (c) 2025 芯祥联科技
 * @author MQTT项目组
 * @version V1.0
 * @date 2025-12-30
 * @website https://www.xxltech.cn
 * @contact 合作邮箱：hezuo@xxltech.cn
 *
 * 核心特性：
 * 1. 接口极简通用：2种基础类型+4个核心接口，接入成本极低，与MQTT协议层完全解耦；
 * 2. 纯静态实现：无动态内存申请/释放，无内存泄漏风险，适配所有嵌入式/MCU场景；
 * 3. 轻量高效：代码精简，无冗余逻辑，纯二进制数据处理，无业务语义依赖；
 * 4. 多模式兼容：0=透传不加密、3=XOR+CRC16轻量加密校验，无缝切换；
 * 5. 安全可靠：内置完整性校验、敏感数据清零，缓冲区溢出校验，防篡改防泄露；
 * 6. 易扩展：用户可基于源码极简扩展动态内存/国密SM4/国际AES算法，无侵入性。
 */
#ifndef MQTT_CRYPTO_H
#define MQTT_CRYPTO_H

#include "type.h"

/**
 * @brief 加密操作返回值
 * 极简设计：仅区分成功与失败，降低用户错误处理成本
 */
typedef enum {
    CRYPTO_OK   = 0,  // 操作成功
    CRYPTO_ERR  = 1   // 操作失败（含参数错误、校验失败、缓冲区不足等）
} Crypto_Status;

/**
 * @brief 加密句柄
 * 内部封装加密上下文信息，一个句柄对应一个独立加密实例，与MQTT客户端一一绑定
 * 静态内存实现，无需动态申请，用户直接定义结构体变量传入即可
 */
typedef void* Crypto_Handle;

/**
 * @brief 加密配置结构体
 * 收敛所有算法配置参数，新增算法仅扩展alg_type，不修改接口，业务层直接填充
 */
typedef struct {
    uint8_xxl  alg_type;    // 加密算法类型：0=不加密（透传），1=SM4，2=AES-128，3=XOR+CRC16，4=TLS1.2，5=SM9（可扩展）
    uint8_xxl  key[32];     // 密钥缓冲区：兼容所有算法密钥长度（SM4/AES-128=16字节，AES-256=32字节）
    uint32_xxl key_len;     // 实际密钥长度（必须与所选算法匹配，否则初始化失败）
    uint8_xxl  iv[16];      // IV向量：块加密算法（SM4/AES）必填，流加密/XOR算法填0即可
    uint8_xxl  enable_check;// 完整性校验开关：0=关闭，1=开启（XOR+CRC16自动校验，防数据篡改）
} Crypto_Config;

/**
 * @brief 加密上下文结构体【静态内存核心】
 * 用户直接定义该结构体变量，传入crypto_create作为句柄，无需动态申请内存
 * 所有加密配置/状态均存储在此结构体，轻量无冗余，大小固定
 */
typedef struct {
    Crypto_Config cfg;    // 加密配置副本，内部留存密钥/算法参数
} Crypto_Ctx;

/**
 * @brief 创建加密器句柄
 * @param crypto_cfg 加密配置结构体（业务层填充，含算法类型、密钥等参数）
 * @param ctx        加密上下文结构体指针（用户定义的静态变量，核心句柄载体）
 * @return Crypto_Status 初始化结果 CRYPTO_OK/CRYPTO_ERR
 * @note 1. 静态内存实现，用户只需定义 Crypto_Ctx 变量，无内存申请释放
 *       2. 每个MQTT客户端对应一个独立Ctx，互不干扰，支持多客户端差异化加密
 *       3. 配置alg_type=0为透传模式，加解密接口自动拷贝数据，无加密处理
 */
Crypto_Status crypto_create(const Crypto_Config* crypto_cfg, Crypto_Ctx* ctx);

/**
 * @brief 数据加密（纯二进制数据处理，无业务语义依赖，极简实现）
 * @param handle 加密器句柄（即Crypto_Ctx静态结构体指针）
 * @param in     输入明文数据（MQTT业务层原始Payload）
 * @param in_len 明文数据长度（字节数）
 * @param out    输出密文缓冲区（业务层提前分配，建议in_len+2字节应对CRC校验）
 * @param out_len [入参]缓冲区最大长度；[出参]实际密文长度（含CRC校验数据）
 * @return Crypto_Status 加密结果 CRYPTO_OK/CRYPTO_ERR
 * @note 1. XOR+CRC16自动追加2字节校验值，开启enable_check后生效，防数据篡改
 *       2. 输入输出缓冲区独立，不覆盖原始明文，透传模式直接拷贝数据
 */
Crypto_Status crypto_encrypt(Crypto_Handle handle, const uint8_xxl* in, size_xxl in_len,
                             uint8_xxl* out, size_xxl* out_len);

/**
 * @brief 数据解密（与加密接口对称，纯二进制数据处理，极简实现）
 * @param handle 加密器句柄（即Crypto_Ctx静态结构体指针）
 * @param in     输入密文数据（MQTT接收的原始Payload）
 * @param in_len 密文数据长度（字节数）
 * @param out    输出明文缓冲区（业务层提前分配，长度建议不小于密文长度）
 * @param out_len [入参]缓冲区最大长度；[出参]实际明文长度（剔除CRC校验数据）
 * @return Crypto_Status 解密结果 CRYPTO_OK/CRYPTO_ERR
 * @note 1. 自动校验CRC完整性，校验失败返回CRYPTO_ERR，有效防止数据篡改
 *       2. 透传模式直接拷贝数据，out_len与in_len完全一致，无额外处理
 */
Crypto_Status crypto_decrypt(Crypto_Handle handle, const uint8_xxl* in, size_xxl in_len,
                             uint8_xxl* out, size_xxl* out_len);

/**
 * @brief 销毁加密器句柄
 * @param handle 加密器句柄（即Crypto_Ctx静态结构体指针）
 * @note 1. 静态内存实现，无内存释放操作，仅做敏感数据清零，防止内存残留
 *       2. 销毁后句柄可重新调用crypto_create初始化复用，无资源占用
 */
void crypto_destroy(Crypto_Handle handle);

#endif // MQTT_CRYPTO_H
