5.14 HWCrypto设备

📚 本节导读

学习时长: 约 40 分钟
难度级别: ⭐⭐⭐⭐☆
前置知识: C 语言基础、密码学基础概念（AES/SHA）、5.1 设备驱动框架

🎯 学习目标

• 理解 OneOS HWCrypto 硬件加密框架的抽象设计
• 掌握加密上下文（ctx）的创建、初始化、销毁流程
• 了解对称加密（AES/DES/3DES/RC4/GCM）和哈希（MD5/SHA1/SHA2/CRC）的硬件加速
• 了解 RNG 随机数生成和 BIGNUM 大数运算

一、概述

HWCrypto（Hardware Crypto）是 OneOS 提供的硬件加密抽象层，利用 MCU 内置的硬件加密引擎（如 STM32 的 CRYP/HASH 模块）来加速加解密运算。HWCrypto 设备驱动位于 drivers/hwcrypto/ 目录下，核心头文件为 hwcrypto.h，实现文件为 hwcrypto.c。

注意：使用 HWCrypto 需要在 oneos_config.h 中启用 OS_USING_HWCRYPTO。

二、支持的算法类型

2.1 对称加密

主类型	子类型	说明
HWCRYPTO_TYPE_AES	AES_ECB / AES_CBC / AES_CFB / AES_CTR / AES_OFB	AES 加密（128/192/256 位）
HWCRYPTO_TYPE_DES	DES_ECB / DES_CBC	DES 加密
HWCRYPTO_TYPE_3DES	3DES_ECB / 3DES_CBC	3DES 加密
HWCRYPTO_TYPE_RC4	—	RC4 流加密
HWCRYPTO_TYPE_GCM	—	AES-GCM 认证加密

2.2 哈希（Hash）

主类型	子类型	说明
HWCRYPTO_TYPE_MD5	—	MD5 哈希（16 字节输出）
HWCRYPTO_TYPE_SHA1	—	SHA-1 哈希（20 字节输出）
HWCRYPTO_TYPE_SHA2	SHA224 / SHA256 / SHA384 / SHA512	SHA-2 系列哈希

2.3 其他

类型	说明
HWCRYPTO_TYPE_RNG	硬件真随机数生成器
HWCRYPTO_TYPE_CRC	硬件 CRC 校验
HWCRYPTO_TYPE_BIGNUM	硬件大数运算（RSA/ECC 加速）

三、核心数据结构

3.1 加密设备 os_hwcrypto_device

struct os_hwcrypto_device
{
    struct os_device              parent;    /* 继承自 os_device_t */
    const struct os_hwcrypto_ops *ops;       /* 硬件加密操作接口 */
    uint64_t                   id;        /* 设备唯一 ID */
    void                         *user_data; /* 用户私有数据 */
};

3.2 加密上下文 os_hwcrypto_ctx

struct os_hwcrypto_ctx
{
    struct os_hwcrypto_device *device;  /* 绑定的加密设备 */
    hwcrypto_type              type;    /* 加密类型 */
    void                      *contex;  /* 硬件上下文（HAL 层私有数据） */
};

3.3 操作接口 os_hwcrypto_ops

struct os_hwcrypto_ops
{
    os_err_t (*create)(struct os_hwcrypto_ctx *ctx);                                   /* 创建硬件上下文 */
    void     (*destroy)(struct os_hwcrypto_ctx *ctx);                                  /* 销毁硬件上下文 */
    os_err_t (*copy)(struct os_hwcrypto_ctx *des, const struct os_hwcrypto_ctx *src);  /* 复制硬件上下文 */
    void     (*reset)(struct os_hwcrypto_ctx *ctx);                                    /* 重置硬件上下文 */
};

3.4 哈希操作接口 hwcrypto_hash_ops

struct hwcrypto_hash_ops
{
    os_err_t (*update)(struct hwcrypto_hash *hash_ctx, const uint8_t *in, os_size_t length);
    os_err_t (*finish)(struct hwcrypto_hash *hash_ctx, uint8_t *out, os_size_t length);
};

struct hwcrypto_hash
{
    struct os_hwcrypto_ctx          parent;  /* 继承加密上下文 */
    const struct hwcrypto_hash_ops *ops;     /* 哈希操作接口 */
};

四、API 详解

4.1 上下文管理

/* 创建加密上下文 */
struct os_hwcrypto_ctx *
os_hwcrypto_ctx_create(struct os_hwcrypto_device *device, hwcrypto_type type, uint32_t obj_size);

/* 销毁加密上下文 */
void os_hwcrypto_ctx_destroy(struct os_hwcrypto_ctx *ctx);

/* 复制加密上下文 */
os_err_t os_hwcrypto_ctx_cpy(struct os_hwcrypto_ctx *des, const struct os_hwcrypto_ctx *src);

/* 重置加密上下文 */
void os_hwcrypto_ctx_reset(struct os_hwcrypto_ctx *ctx);

4.2 哈希运算

struct os_hwcrypto_ctx *os_hwcrypto_hash_create(hwcrypto_type type);
os_err_t os_hwcrypto_hash_update(struct os_hwcrypto_ctx *ctx, const uint8_t *input, os_size_t length);
os_err_t os_hwcrypto_hash_finish(struct os_hwcrypto_ctx *ctx, uint8_t *output, os_size_t length);
void os_hwcrypto_hash_destroy(struct os_hwcrypto_ctx *ctx);
os_err_t os_hwcrypto_hash_cpy(struct os_hwcrypto_ctx *des, const struct os_hwcrypto_ctx *src);
void os_hwcrypto_hash_reset(struct os_hwcrypto_ctx *ctx);

4.3 设备管理

os_err_t os_hwcrypto_register(struct os_hwcrypto_device *device, const char *name);
uint64_t os_hwcrypto_id(struct os_hwcrypto_device *device);

五、代码示例

5.1 SHA256 哈希计算

#include <oneos_config.h>
#include <hwcrypto/hwcrypto.h>
#include <hwcrypto/hw_hash.h>

void sha256_example(void)
{
    struct os_hwcrypto_ctx *ctx;
    uint8_t  input[]  = "Hello OneOS HWCrypto!";
    uint8_t  output[32];  /* SHA256 输出 32 字节 */
    int      i;

    /* 创建 SHA256 哈希上下文 */
    ctx = os_hwcrypto_hash_create(HWCRYPTO_TYPE_SHA256);
    if (ctx == OS_NULL)
    {
        os_kprintf("SHA256 context create failed!\r\n");
        return;
    }

    /* 更新数据 */
    os_hwcrypto_hash_update(ctx, input, sizeof(input) - 1);

    /* 完成计算 */
    os_hwcrypto_hash_finish(ctx, output, sizeof(output));

    /* 输出结果 */
    os_kprintf("SHA256(\"%s\") = ", input);
    for (i = 0; i < 32; i++)
        os_kprintf("%02x", output[i]);
    os_kprintf("\r\n");

    /* 销毁上下文 */
    os_hwcrypto_hash_destroy(ctx);
}

5.2 分段哈希计算

void sha256_stream_example(void)
{
    struct os_hwcrypto_ctx *ctx;
    uint8_t  output[32];
    uint8_t  chunk1[] = "Hello ";
    uint8_t  chunk2[] = "OneOS ";
    uint8_t  chunk3[] = "World!";

    ctx = os_hwcrypto_hash_create(HWCRYPTO_TYPE_SHA256);

    /* 分多次输入数据 */
    os_hwcrypto_hash_update(ctx, chunk1, sizeof(chunk1) - 1);
    os_hwcrypto_hash_update(ctx, chunk2, sizeof(chunk2) - 1);
    os_hwcrypto_hash_update(ctx, chunk3, sizeof(chunk3) - 1);

    /* 最终完成计算 */
    os_hwcrypto_hash_finish(ctx, output, sizeof(output));

    os_hwcrypto_hash_destroy(ctx);
}

5.3 MD5 哈希计算

void md5_example(void)
{
    struct os_hwcrypto_ctx *ctx;
    uint8_t  input[] = "test data for MD5";
    uint8_t  output[16];  /* MD5 输出 16 字节 */
    int      i;

    ctx = os_hwcrypto_hash_create(HWCRYPTO_TYPE_MD5);
    if (ctx == OS_NULL) return;

    os_hwcrypto_hash_update(ctx, input, sizeof(input) - 1);
    os_hwcrypto_hash_finish(ctx, output, sizeof(output));

    os_kprintf("MD5: ");
    for (i = 0; i < 16; i++) os_kprintf("%02x", output[i]);
    os_kprintf("\r\n");

    os_hwcrypto_hash_destroy(ctx);
}

5.4 硬件随机数生成

void rng_example(void)
{
    struct os_hwcrypto_ctx *ctx;
    uint8_t  random_data[32];
    int      i;

    ctx = os_hwcrypto_ctx_create(gs_hw_device, HWCRYPTO_TYPE_RNG,
                                 sizeof(struct os_hwcrypto_ctx));
    if (ctx == OS_NULL) return;

    /* 生成 32 字节随机数 */
    os_hwcrypto_rng_generate(ctx, random_data, sizeof(random_data));

    os_kprintf("Random: ");
    for (i = 0; i < 32; i++) os_kprintf("%02x", random_data[i]);
    os_kprintf("\r\n");

    os_hwcrypto_ctx_destroy(ctx);
}

六、注意事项

1. 硬件依赖：HWCrypto 依赖 MCU 硬件加密引擎，软件模拟场景下应使用 MBED TLS / OneTLS
2. 上下文大小：os_hwcrypto_ctx_create 的 obj_size 必须至少为 sizeof(struct os_hwcrypto_ctx)
3. 类型兼容性：复制上下文时，源和目标必须是相同的设备和相同的主类型
4. 中断安全：加密运算可能在中断上下文中进行，HAL 层需确保操作不阻塞
5. 与软件加密配合：HWCrypto 可与 MBED TLS 配合，通过 MBEDTLS_AES_ALT 等宏启用硬件加速

📝 本节小结

1. HWCrypto 是 OneOS 的硬件加密抽象层，利用 MCU 硬件加密引擎加速运算
2. 支持 AES/DES/3DES/RC4/GCM 对称加密、MD5/SHA1/SHA2 哈希、RNG/CRC/BIGNUM 等
3. 通过 os_hwcrypto_ctx 管理加密上下文，支持创建/复制/重置/销毁
4. 哈希运算使用 update + finish 模式，支持分段输入
5. 典型应用：固件签名验证、安全通信、数据完整性校验

🔗 相关链接

• 5.1 设备驱动框架
• 7.3 Mbed TLS 加密组件
• 第5章 README