Class VersionedCipher

java.lang.Object
cloud.opencode.base.crypto.versioned.VersionedCipher
public final class VersionedCipher extends Object
Versioned cipher supporting multiple algorithm versions for seamless key/algorithm rotation. 支持多个算法版本的版本化加密器，用于无缝密钥/算法轮换。

Encrypts with the current version and decrypts with any registered version, enabling zero-downtime algorithm migration.

使用当前版本加密，使用任何已注册版本解密，实现零停机算法迁移。

Features | 主要功能:

  • Multi-version cipher management - 多版本加密管理
  • Transparent version detection on decrypt - 解密时透明的版本检测
  • Base64 convenience methods - Base64 便捷方法
  • Builder pattern construction - Builder 模式构建

Usage Examples | 使用示例:

VersionedCipher vc = VersionedCipher.builder()
    .addVersion(1, cipherV1)
    .addVersion(2, cipherV2)
    .currentVersion(2)
    .build();

byte[] encrypted = vc.encrypt(plaintext);
byte[] decrypted = vc.decrypt(encrypted); // auto-detects version

Security | 安全性:

  • Thread-safe: Yes (immutable map) - 线程安全: 是（不可变 map）
Since:
JDK 25, opencode-base-crypto V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • builder

      public static VersionedCipher.Builder builder()
      Creates a new Builder for constructing a VersionedCipher. 创建用于构建 VersionedCipher 的 Builder。
      Returns:
      a new Builder instance | 新的 Builder 实例

    • encrypt

      public byte[] encrypt(byte[] plaintext)
      Encrypts plaintext using the current version cipher. 使用当前版本加密器加密明文。
      Parameters:
      plaintext - the plaintext bytes to encrypt | 要加密的明文字节
      Returns:
      serialized VersionedPayload containing version, algorithm, and ciphertext | 序列化的 VersionedPayload

    • decrypt

      public byte[] decrypt(byte[] payload)
      Decrypts a serialized VersionedPayload, auto-detecting the version. 解密序列化的 VersionedPayload，自动检测版本。
      Parameters:
      payload - the serialized payload | 序列化的负载
      Returns:
      decrypted plaintext bytes | 解密的明文字节
      Throws:
      OpenCryptoException - if the version is not registered | 当版本未注册时抛出

    • encryptBase64

      public String encryptBase64(byte[] plaintext)
      Encrypts plaintext and returns the result as a Base64 string. 加密明文并返回 Base64 编码的结果。
      Parameters:
      plaintext - the plaintext bytes to encrypt | 要加密的明文字节
      Returns:
      Base64 encoded encrypted payload | Base64 编码的加密负载

    • decryptBase64

      public byte[] decryptBase64(String base64)
      Decrypts a Base64 encoded payload. 解密 Base64 编码的负载。
      Parameters:
      base64 - Base64 encoded payload | Base64 编码的负载
      Returns:
      decrypted plaintext bytes | 解密的明文字节

    • encryptBase64

      public String encryptBase64(String plaintext)
      Encrypts a plaintext string and returns the result as a Base64 string. 加密明文字符串并返回 Base64 编码的结果。
      Parameters:
      plaintext - the plaintext string | 明文字符串
      Returns:
      Base64 encoded encrypted payload | Base64 编码的加密负载

    • decryptBase64ToString

      public String decryptBase64ToString(String base64)
      Decrypts a Base64 encoded payload and returns the result as a string. 解密 Base64 编码的负载并返回字符串结果。
      Parameters:
      base64 - Base64 encoded payload | Base64 编码的负载
      Returns:
      decrypted plaintext string | 解密的明文字符串