未来之窗kas加解密

一、功能概述

未来之窗kas加解密（$cq.system_security_cryptography_kas）是一个带时效控制与完整性校验的对称加解密函数。该函数基于流密码对数据进行异或混淆，加密时自动写入过期时间戳与签名摘要，解密时校验时效与签名，通过后才还原原文。适用于临时令牌、接口参数加密、短时敏感数据传输等场景，可有效防止密文被篡改或长期复用。

二、核心函数与调用格式

1. $cq.system_security_cryptography_kas

$cq.system_security_cryptography_kas(options, operation, key, expiry);

该函数为加解密统一入口，通过 operation 参数区分加密与解密模式。加密时返回可传输的密文字符串，解密时返回原始明文或空字符串（校验失败时）。

三、参数说明

四、返回值

• 加密模式（ENCODE）：返回密文字符串，由 4 位随机前缀 + Base64 编码（已去除补位符 =）组成，可直接用于 URL 或接口传输。
• 解密模式（DECODE）：校验通过且未过期时返回原始明文字符串；签名不匹配或已过期时返回空字符串 ""。

五、使用示例

1. 加密示例：生成带时效的密文

const plain = "东方仙盟·混沌架构";
const cipher = $cq.system_security_cryptography_kas(
    plain,
    "ENCODE",
    "my_secret_key",
    3600  // 1小时后过期
);
console.log(cipher);
// 输出示例：a1b2xxxxxxxxxxxxxxxxxxxxxx（4位前缀 + Base64密文）
                

2. 解密示例：还原原文

const cipher = "a1b2xxxxxxxxxxxxxxxxxxxxxx";
const plain = $cq.system_security_cryptography_kas(
    cipher,
    "DECODE",
    "my_secret_key"
);
console.log(plain);
// 输出：东方仙盟·混沌架构
// 若密钥错误或已过期，输出：""
                

3. 往返校验示例：加密后立即解密

const original = "未来之窗昭和仙君";
const key = "fairy_alliance_2026";
const encrypted = $cq.system_security_cryptography_kas(original, "ENCODE", key, 1800);
const decrypted = $cq.system_security_cryptography_kas(encrypted, "DECODE", key);
console.log(decrypted === original);
// 输出：true
                

4. 永不过期示例

// expiry 设为 0，密文永久有效（仍受签名校验保护）
const cipher = $cq.system_security_cryptography_kas("永久数据", "ENCODE", "key", 0);
                

六、注意事项

• 加密与解密必须使用相同的 key，密钥错误时解密返回空字符串，不会抛出异常。
• 密文内置过期时间戳，默认有效期 3600 秒（1小时），过期后解密返回空字符串；设为 0 可永久有效。
• 密文内置签名摘要，任何对密文的篡改都会导致签名校验失败，解密返回空字符串。
• 加密结果每次不同（含随机前缀），即使原文与密钥完全相同，两次加密输出也不一致，这是正常现象。
• 本算法为轻量级对称混淆，适用于业务层数据保护，不可替代 TLS/HTTPS 等传输层安全机制，也不建议用于高安全等级的密码存储场景。