Class KeyRotation<K>

java.lang.Object
cloud.opencode.base.crypto.rotation.KeyRotation<K>
Type Parameters:
K - the key type - 密钥类型
All Implemented Interfaces:
AutoCloseable
public final class KeyRotation<K> extends Object implements AutoCloseable
Key Rotation Manager - Automated key version management and rotation 密钥轮换管理器 - 自动化密钥版本管理和轮换

Provides automatic key rotation with version management, graceful retirement of old keys, and support for both symmetric and asymmetric keys.

提供自动密钥轮换，包括版本管理、旧密钥优雅退役，以及对称和非对称密钥的支持。

Features | 主要功能:

  • Version-based key management - 基于版本的密钥管理
  • Automatic rotation scheduling - 自动轮换调度
  • Graceful key retirement - 密钥优雅退役
  • Key derivation support - 密钥派生支持
  • Audit logging - 审计日志
  • Thread-safe operations - 线程安全操作

Usage Examples | 使用示例:

// Create a key rotation manager
KeyRotation<SecretKey> rotation = KeyRotation.<SecretKey>builder()
    .keyId("encryption-key")
    .keyGenerator(() -> KeyGenerator.generateAesKey(256))
    .rotationInterval(Duration.ofDays(90))
    .gracePeriod(Duration.ofDays(7))
    .maxVersions(3)
    .onRotation(event -> log.info("Key rotated: {}", event))
    .build();

// Start automatic rotation
rotation.startAutoRotation();

// Get current key for encryption
VersionedKey<SecretKey> current = rotation.getCurrentKey();

// Decrypt with specific version
SecretKey key = rotation.getKeyByVersion(1).key();

// Manual rotation
rotation.rotate();

// Retire old keys
rotation.retireOldVersions();

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-crypto V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • getCurrentKey

      public KeyRotation.VersionedKey<K> getCurrentKey()
      Gets the current (latest) key for encryption. 获取当前（最新）密钥用于加密。
      Returns:
      the current versioned key - 当前版本化密钥

    • getKeyByVersion

      public KeyRotation.VersionedKey<K> getKeyByVersion(long version)
      Gets a key by its version number. 根据版本号获取密钥。
      Parameters:
      version - the version number - 版本号
      Returns:
      the versioned key - 版本化密钥
      Throws:
      OpenCryptoException - if version not found - 如果版本未找到

    • getCurrentVersion

      public long getCurrentVersion()
      Gets the current version number. 获取当前版本号。
      Returns:
      the current version - 当前版本

    • getAvailableVersions

      public Set<Long> getAvailableVersions()
      Gets all available versions. 获取所有可用版本。
      Returns:
      set of version numbers - 版本号集合

    • getKeyId

      public String getKeyId()
      Gets the key ID. 获取密钥 ID。
      Returns:
      the key ID - 密钥 ID

    • rotate

      public KeyRotation.VersionedKey<K> rotate()
      Manually triggers a key rotation. 手动触发密钥轮换。
      Returns:
      the new versioned key - 新的版本化密钥

    • addKey

      public KeyRotation.VersionedKey<K> addKey(K key)
      Adds an existing key as a new version. 将现有密钥添加为新版本。
      Parameters:
      key - the key to add - 要添加的密钥
      Returns:
      the versioned key - 版本化密钥

    • importKey

      public void importKey(long version, K key, Instant createdAt)
      Imports a key with a specific version. 导入具有特定版本的密钥。
      Parameters:
      version - the version number - 版本号
      key - the key - 密钥
      createdAt - the creation time - 创建时间

    • retireOldVersions

      public int retireOldVersions()
      Retires keys older than the grace period. 退役超过宽限期的密钥。
      Returns:
      count of retired keys - 退役的密钥数量

    • deleteRetiredKeys

      public int deleteRetiredKeys()
      Removes retired keys permanently. 永久删除已退役的密钥。
      Returns:
      count of deleted keys - 删除的密钥数量

    • startAutoRotation

      public void startAutoRotation()
      Starts automatic key rotation. 启动自动密钥轮换。

    • stopAutoRotation

      public void stopAutoRotation()
      Stops automatic key rotation. 停止自动密钥轮换。

    • isRotationNeeded

      public boolean isRotationNeeded()
      Checks if a rotation is needed based on the interval. 根据间隔检查是否需要轮换。
      Returns:
      true if rotation is needed - 如果需要轮换返回 true

    • getTimeUntilNextRotation

      public Duration getTimeUntilNextRotation()
      Gets the time until next rotation. 获取到下次轮换的时间。
      Returns:
      duration until next rotation - 到下次轮换的时间

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • builder

      public static <K> KeyRotation.Builder<K> builder()
      Creates a new builder. 创建新的构建器。
      Type Parameters:
      K - the key type - 密钥类型
      Returns:
      the builder - 构建器

    • forAes

      public static KeyRotation<SecretKey> forAes(String keyId, int keyBits)
      Creates a key rotation for AES keys. 为 AES 密钥创建密钥轮换。
      Parameters:
      keyId - the key ID - 密钥 ID
      keyBits - the key size in bits (128, 192, or 256) - 密钥位数
      Returns:
      the key rotation manager - 密钥轮换管理器

    • forRsa

      public static KeyRotation<KeyPair> forRsa(String keyId, int keyBits)
      Creates a key rotation for RSA key pairs. 为 RSA 密钥对创建密钥轮换。
      Parameters:
      keyId - the key ID - 密钥 ID
      keyBits - the key size in bits - 密钥位数
      Returns:
      the key rotation manager - 密钥轮换管理器