★ FEATURED ARTICLE 人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载com.openjiuwen.memory.common.MemoryCrypto是 openJiuwen agent-core-java 记忆模块提供的 AES-256-GCM 记忆内容加解密工具用于对写入持久化存储的长期记忆、消息与变量进行落盘加密防止敏感对话内容以明文形式暴露在数据库或 KV 存储中。本文将基于 MemoryCrypto API 文档 的类骨架结合 core 模块的密码学底层实现与 memory 模块的存储接入源码完整讲解其常量定义、加解密行为、密钥配置方式与可验证的工程实践帮助读者在构建 AI Agent 记忆能力时正确启用与验证加密链路。MemoryCrypto 在记忆模块中的定位记忆模块memory工程对应包com.openjiuwen.memory负责 Agent 长期记忆的存取、检索与摘要管理其公共工具包com.openjiuwen.memory.common提供了四类共享基础设施参见 common.README.md类型职责DistributedLock基于BaseKVStore.exclusive_set(...)的同步分布式锁KvPrefixRegistry统一管理记忆模块使用的 KV 前缀MemoryCrypto提供 AES-256-GCM 记忆内容加解密能力MemoryUtils检索命中解析与静态工具方法MemoryCrypto是一个public final类不可继承、不可实例化的工具类形态其声明如下public final class MemoryCrypto它作为记忆模块对外暴露的统一加密入口在调用链上承接两类使用方一类是记忆管理器的按需加解密辅助方法如BaseMemoryManager.encryptMemoryIfNeeded / decryptMemoryIfNeeded另一类是存储编解码器如AesStorageCodec从而让密钥为空则明文透传、配置密钥则静默加密的策略贯穿整个记忆读写路径。常量字段一组与 AES-256-GCM 算法对齐的固定参数MemoryCrypto暴露了四个int类型常量字段字段类型说明NONCE_LENGTHintGCM 模式随机数nonce的长度参数TAG_LENGTHintGCM 认证标签tag的长度参数AES_KEY_LENGTHintAES 密钥的字节长度参数BIT_LENGTHint与位长度相关的换算参数这四个常量并非孤立的数字而是与 core 模块密码学实现的常量严格对齐。在 AesGcmCrypt.java 中可以看到底层取值static final int NONCE_LENGTH 12; // 12 字节 nonce96 位GCM 推荐值 static final int AES_KEY_LENGTH 32; // 32 字节密钥即 AES-256 static final int TAG_LENGTH 16; // 16 字节认证标签128 位CryptUtils将这些常量以public static final形式统一对外公开CryptUtils.java而BIT_LENGTH一类参数在加解密实现中体现为 tag 的位长度换算——例如 AesGcmCrypt.java 中new GCMParameterSpec(TAG_LENGTH * 8, nonce)即使用16 × 8 128位的认证标签位长。从该实现可以推断MemoryCrypto的常量与CryptUtils/AesGcmCrypt出自同一套算法规格保证上层 API 与底层AES/GCM/NoPadding变换的参数完全一致。公开方法encrypt 与 decrypt 的签名与语义MemoryCrypto提供了两个静态方法构成完整的加解密闭环签名说明public static String[] encrypt(byte[] key, String plaintext)执行加密返回密文相关分量public static String decrypt(byte[] key, String ciphertext, String nonce, String tag)基于密钥、密文、nonce 与 tag 执行解密值得注意的两个签名细节encrypt 返回String[]将密文拆分为多个分量返回与AesGcmCrypt的nonce tag ciphertext 三段拼接输出格式见下文相对应调用方可按需组合或持久化decrypt 显式接收nonce与tagGCM 模式解密必须同时提供 nonce 与认证标签缺少任一分量都无法通过完整性校验这从 API 层强制了 GCM 的认证加密AEAD语义。底层实现三段式十六进制密文格式尽管MemoryCrypto.java的类本体在 memory 工程中属于文档描述的公共 API 层其算法落地由 core 模块的 AesGcmCrypt.java 承担。加密流程如下使用SecureRandom生成 12 字节随机 nonce每次加密不重复保证 GCM 安全性以AES/GCM/NoPadding变换、32 字节密钥与 128 位 tag 初始化Cipher对明文 UTF-8 字节执行doFinal得到密文 tag的拼接结果将结果切分为密文与 tag最终输出hex(nonce) hex(tag) hex(ciphertext)的小写十六进制字符串。解密时按nonce(24 位十六进制) tag(32 位十六进制) 剩余密文的顺序切分并回填若密文长度不足、nonce/tag 长度异常或 GCM 完整性校验失败会分别抛出COMMON_ENCRYPTION_ERROR/COMMON_DECRYPTION_ERROR状态码对应的BaseError见 AesGcmCrypt.java。测试 BaseMemoryManagerCryptoTest.java 验证了密文为全小写十六进制、且用错密钥解密必然失败这两条关键性质。可插拔的密码学注册表MemoryCrypto的加密能力通过 CryptUtils.java 维护的全局注册表获取默认注册名为aes_gcmAES_GCM_CRYPT_NAME。CryptUtils.registerCrypt / unregisterCrypt / getCrypt允许在运行时替换或移除加密实现BaseCrypt抽象类BaseCrypt.java定义了encrypt(byte[] key, String origin)与decrypt(byte[] key, String encryptStr)两个抽象方法AesGcmCrypt是其默认的 AES-GCM 实现。这意味着记忆模块的解密逻辑不绑定具体算法为未来算法演进预留了扩展点。密钥配置crypto_key 的字节长度约束MemoryCrypto的密钥由记忆引擎配置项crypto_key提供定义于 MemoryEngineConfig.javaJsonProperty(crypto_key) private byte[] cryptoKey new byte[0];该配置项在校验逻辑上有两条硬性规则MemoryEngineConfig.java密钥必须为空或恰好 32 字节256 位即CryptUtils.AES_KEY_LENGTH其余长度的密钥会直接抛出MEMORY_SET_CONFIG_EXECUTION_ERROR默认值为空字节数组new byte[0]此时整个加密链路处于关闭状态明文透传。对应的单元测试 MemoryConfigModelsTest.java 分别验证了32 字节密钥可正常设置与31 字节密钥抛错两条路径。构建时通过 Builder 或全参构造器传入byte[] key 0123456789abcdef0123456789abcdef.getBytes(StandardCharsets.UTF_8); // 恰好 32 字节 MemoryEngineConfig config MemoryEngineConfig.builder() .cryptoKey(key) .build();加密在记忆引擎中的完整接入链路密钥配置后LongTermMemory会将config.getCryptoKey()分发到各记忆子组件LongTermMemory.javaFragmentMemoryManager、SummaryManager、VariableManager、SearchManager以及消息存储SqlMessageStore均持有该密钥副本。各组件通过以下两条路径实际使用加密路径一存储编解码器AesStorageCodecAesStorageCodec.java 实现了StorageCodec接口在写入存储前encode、读取后decode密钥为空、文本为空或CryptUtils未注册aes_gcm实现时原样返回文本不加密、不报错否则调用crypt.encrypt(key, text)/crypt.decrypt(key, data)加解密异常仅记录MEMORY_PROCESS事件类型的 warning 日志返回原始文本兜底避免存储链路因加密问题整体不可用。VariableManagerVariableManager.java与SqlMessageStoreSqlMessageStore.java均通过new AesStorageCodec(cryptoKey)接入该编解码器。路径二内存管理器的按需加解密BaseMemoryManager.java 提供了一对静态工具方法供各记忆管理器在写入/读取记忆单元时调用public static String encryptMemoryIfNeeded(byte[] key, String plaintext) public static String decryptMemoryIfNeeded(byte[] key, String ciphertext)两者的共同语义是if needed按需密钥为空、输入为空或加密实现缺失时直接透传加密/解密异常时记录 warning 日志并返回原始值。这一设计保证了加密是可选的增强能力未配置密钥的系统行为与未加密时代完全一致。测试验证加密链路的可观察行为与MemoryCrypto直接对应的测试文件为MemoryCryptoTest.java见 common.README.md此外仓库中还提供了多层级的加密行为验证BaseMemoryManagerCryptoTest.java覆盖完整加解密往返、空密钥透传、空串处理、加密实现缺失时的降级返回、密钥不一致时解密必须失败、Unicode 与 emoji 明文往返以及新旧密文格式兼容等 13 个场景AesStorageCodecTest.java验证存储编解码器的 encode/decode 行为CryptUtilsTest.java验证密码学注册表与常量的一致性。其中encryptDecryptWithDifferentKeysFailsBaseMemoryManagerCryptoTest.java直接验证了 GCM 认证标签对密钥错误的强校验使用不同密钥解密必然抛出异常这是认证加密区别于普通 AES 加密的关键安全特性。实践要点与安全建议密钥必须是 32 字节256 位crypto_key过长或过短都会在配置阶段被拒绝测试中常见的合法示例为0123456789abcdef0123456789abcdef32 个 ASCII 字符。加密是可选的、渐进式的能力不配置密钥时全文透传不会破坏已有功能配置密钥后新写入内容即被加密存量明文数据仍可通过decryptMemoryIfNeeded与 legacy 兼容逻辑正常读取见 BaseMemoryManagerCryptoTest.java。GCM 的 nonce 由系统随机生成且每次不同不要自行复用或固定 nonceMemoryCrypto.encrypt返回String[]的原因就在于需要将 nonce/tag 与密文分开管理。密钥即安全边界一旦密钥泄露或丢失密文将无法解密GCM 认证会拒绝任何错误密钥。生产环境应通过密钥管理服务注入crypto_key并留意MemoryEngineConfig的校验逻辑MemoryEngineConfig.java保证配置源头合法。理解异常降级语义加密实现缺失或加解密异常时系统会记 warning 并返回原始数据而非抛错中断这保证了存储链路的可用性优先但应在日志中及时发现Encrypt/Decrypt error via crypt类告警。通过 MemoryCrypto、common.README.md 与本仓库源码对照阅读开发者可以快速定位记忆加密的 API 层、算法层、配置层与存储接入层完整掌握 openJiuwen 记忆引擎的数据加密机制。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen agent-core 加密解密抽象层详解CryptUtils 注册表与 AES-256-GCM 实战指南openJiuwen agent core 加密解密抽象层详解CryptUtils 注册表与 AES 256 GCM 实战指南 本篇技术指南深入剖析 open人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 通用模块安全加密实践基于 CryptUtils 的 AES-256-GCM 加解密体系解析openJiuwen agent core 通用模块安全加密实践基于 CryptUtils 的 AES 256 GCM 加解密体系解析 导读 本文基于 ope人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习快速用 Etcher 把系统镜像写入 SD 卡和 U 盘安全烧录完整指南快速用 Etcher 把系统镜像写入 SD 卡和 U 盘安全烧录完整指南 EtcherbalenaEtcher是 Balena 出品的开源操作系统镜像烧录桌面应用开发工具智能硬件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
