/*
 * 模块名称：sha256
 * 模块功能：SHA-256 安全散列（FIPS 180-4）——流式 + 一次性接口，外加摘要与
 *           64 位 hex 串的恒定时间比较；纯标准库、零堆分配，MCU 与主机侧
 *           单测共用（无平台依赖）
 * 适用平台：STM32F407ZGTx / PC 主机侧单测（双端共用）
 * 作者：王建锋
 * 创建日期：2026-10-11
 * 修改记录：
 *     v1.0  2026-10-11  王建锋  创建初始版本（N-19 FTP 鉴权：[ftp] pwd_hash 校验）
 */

#ifndef SHA256_H
#define SHA256_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stddef.h>
#include <stdint.h>

#define SHA256_DIGEST_SIZE  32u   /* 摘要字节数 */
#define SHA256_BLOCK_SIZE   64u   /* 分组字节数 */

/* 散列上下文（≈108 B，调用方栈上或静态均可） */
typedef struct {
    uint32_t state[8];              /* 链接变量 */
    uint64_t bitlen;                /* 已处理的完整分组累计比特数 */
    uint8_t  buf[SHA256_BLOCK_SIZE];/* 未满分组的暂存区 */
    uint32_t buf_len;               /* 暂存区已用字节数 */
} sha256_ctx_t;

/*
 * 函数功能：初始化散列上下文
 * 入口参数：p_ctx - 上下文（不可为 NULL）  sha256_ctx_t *
 * 返回值：无
 * 限定条件：无
 */
void sha256_init(sha256_ctx_t *p_ctx);

/*
 * 函数功能：喂入一段消息（可多次调用，任意切分）
 * 入口参数：p_ctx - 上下文  p_data - 数据  len - 字节数
 * 返回值：无
 * 限定条件：p_ctx 已 init；p_data 为 NULL 或 len=0 时空操作
 */
void sha256_update(sha256_ctx_t *p_ctx, const void *p_data, size_t len);

/*
 * 函数功能：补位收尾并输出 32 B 摘要（调用后上下文被清零，不可续用）
 * 入口参数：p_ctx - 上下文  p_out - 32 B 输出缓冲（不可为 NULL）
 * 返回值：无
 * 限定条件：p_ctx 已 init
 */
void sha256_final(sha256_ctx_t *p_ctx, uint8_t p_out[SHA256_DIGEST_SIZE]);

/*
 * 函数功能：一次性计算整段消息的 SHA-256
 * 入口参数：p_data - 数据  len - 字节数  p_out - 32 B 输出缓冲
 * 返回值：无
 * 限定条件：p_data/p_out 非空
 */
void sha256_calc(const void *p_data, size_t len, uint8_t p_out[SHA256_DIGEST_SIZE]);

/*
 * 函数功能：恒定时间比较 32 B 摘要与 64 字符 hex 串（大小写不敏感）
 * 入口参数：p_digest - 32 B 摘要  p_hex - 64 字符 hex 串（可 NULL）
 * 返回值：1 - 相等；0 - 不等 / hex 非法 / 参数为空  int
 * 函数说明：hex 来自配置文件（可信来源），格式非法早退不构成侧信道；
 *          摘要与 hex 内容的比较逐字节累积异或，耗时只随长度（固定 64）变化
 */
int sha256_hex_eq(const uint8_t p_digest[SHA256_DIGEST_SIZE], const char *p_hex);

#ifdef __cplusplus
}
#endif

#endif /* SHA256_H */