package com.ruoyi.crypto.service;

import com.ruoyi.crypto.enums.CryptoDataType;

/**
 * 统一密码服务接口（国密 SM3 / SM4）。
 * <p>
 * <b>设计约束</b>（等保 / 密码应用要求）：
 * <ul>
 *   <li>业务代码禁止直接调用密码机厂商 SDK，一律经本接口</li>
 *   <li>主密钥不出机，应用仅持有密码机内的密钥索引（见 {@code crypto.keys.*}）</li>
 *   <li>日志中禁止输出明文、密钥材料或完整密文</li>
 * </ul>
 * 一期提供 {@link com.ruoyi.crypto.service.impl.StubCryptoServiceImpl} 用于开发联调；
 * 生产环境替换为对接 HSM 的实现，接口签名保持不变。
 * </p>
 *
 * @see com.ruoyi.crypto.enums.CryptoDataType
 * @see doc/密码改造/应用密码改造技术方案.md
 */
public interface CryptoService
{
    /**
     * 计算 SM3-HMAC 完整性值。
     *
     * @param plain    待保护字节（调用方按 Canonical 规则拼接）
     * @param dataType 数据分类，决定使用哪组密钥索引
     * @return Base64 编码的 HMAC 值，写入库中 {@code *_hmac} 或 {@code integrity_hmac}
     */
    String hmacSm3(byte[] plain, CryptoDataType dataType);

    /**
     * SM4 对称加密（机密性保护）。
     *
     * @param plainText 明文字符串，如手机号、邮箱
     * @param dataType  数据分类，决定 SM4 密钥索引
     * @return Base64 密文，写入 {@code *_cipher} 列
     */
    String encryptSm4(String plainText, CryptoDataType dataType);

    /**
     * SM4 对称解密。
     *
     * @param cipherText Base64 密文
     * @param dataType   须与加密时一致
     * @return 明文字符串
     */
    String decryptSm4(String cipherText, CryptoDataType dataType);

    /**
     * 校验存储的 HMAC 是否与当前明文一致（防篡改）。
     *
     * @param plain       按 Canonical 规则拼接的待校验字节
     * @param storedHmac  库中已存的 Base64 HMAC
     * @param dataType    数据分类
     * @return true 表示完整性校验通过
     */
    boolean verifyHmac(byte[] plain, String storedHmac, CryptoDataType dataType);
}
