Class EnvelopeCrypto

java.lang.Object
cloud.opencode.base.crypto.envelope.EnvelopeCrypto
public final class EnvelopeCrypto extends Object
Envelope encryption implementation - Combines asymmetric and symmetric encryption for secure data encryption 信封加密实现 - 结合非对称和对称加密实现安全的数据加密

Features | 主要功能:

  • Envelope encryption (RSA + AES-GCM) - 信封加密（RSA + AES-GCM）
  • Data encryption key wrapping - 数据加密密钥包装

Usage Examples | 使用示例:

EnvelopeCrypto crypto = EnvelopeCrypto.rsaAesGcm();
EncryptedEnvelope envelope = crypto.encrypt(data, publicKey);
byte[] decrypted = crypto.decrypt(envelope, privateKey);

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

    • rsaAesGcm

      public static EnvelopeCrypto rsaAesGcm()
      Create envelope crypto with RSA-OAEP and AES-GCM (Recommended) 创建使用 RSA-OAEP 和 AES-GCM 的信封加密（推荐）
      Returns:
      new EnvelopeCrypto instance

    • ecdhAesGcm

      public static EnvelopeCrypto ecdhAesGcm()
      Create envelope crypto with ECDH key agreement and AES-GCM. 创建使用 ECDH 密钥协商和 AES-GCM 的信封加密。

      Not yet implemented. ECDH key agreement requires a different key wrapping mechanism than RSA OAEP. Use rsaAesGcm() instead.

      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always — ECDH key agreement is not yet implemented

    • x25519ChaCha20

      public static EnvelopeCrypto x25519ChaCha20()
      Create envelope crypto with X25519 key agreement and ChaCha20-Poly1305. 创建使用 X25519 密钥协商和 ChaCha20-Poly1305 的信封加密。

      Not yet implemented. X25519 key agreement requires a different key wrapping mechanism than RSA OAEP. Use rsaAesGcm() instead.

      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always — X25519 key agreement is not yet implemented

    • setRecipientPublicKey

      public EnvelopeCrypto setRecipientPublicKey(PublicKey publicKey)
      Set recipient public key for encryption 设置接收者公钥用于加密
      Parameters:
      publicKey - recipient's public key
      Returns:
      this instance for method chaining
      Throws:
      NullPointerException - if publicKey is null

    • setRecipientPrivateKey

      public EnvelopeCrypto setRecipientPrivateKey(PrivateKey privateKey)
      Set recipient private key for decryption 设置接收者私钥用于解密
      Parameters:
      privateKey - recipient's private key
      Returns:
      this instance for method chaining
      Throws:
      NullPointerException - if privateKey is null

    • encrypt

      public EncryptedEnvelope encrypt(byte[] plaintext)
      Encrypt plaintext using envelope encryption 使用信封加密加密明文

      Process: 1. Generate random DEK (Data Encryption Key) 2. Encrypt plaintext with DEK using symmetric algorithm 3. Encrypt DEK with recipient's public key 4. Return EncryptedEnvelope containing all components

      Parameters:
      plaintext - data to encrypt
      Returns:
      encrypted envelope
      Throws:
      NullPointerException - if plaintext is null
      IllegalStateException - if public key is not set
      OpenCryptoException - if encryption fails

    • encrypt

      public EncryptedEnvelope encrypt(byte[] plaintext, byte[] aad)
      Encrypt plaintext using envelope encryption with additional authenticated data 使用信封加密加密明文，支持附加认证数据
      Parameters:
      plaintext - data to encrypt
      aad - additional authenticated data (can be null)
      Returns:
      encrypted envelope
      Throws:
      NullPointerException - if plaintext is null
      IllegalStateException - if public key is not set
      OpenCryptoException - if encryption fails

    • encryptBase64

      public String encryptBase64(byte[] plaintext)
      Encrypt plaintext and return Base64 encoded result 加密明文并返回 Base64 编码结果
      Parameters:
      plaintext - data to encrypt
      Returns:
      Base64 encoded encrypted envelope
      Throws:
      NullPointerException - if plaintext is null
      IllegalStateException - if public key is not set
      OpenCryptoException - if encryption fails

    • decrypt

      public byte[] decrypt(EncryptedEnvelope envelope)
      Decrypt encrypted envelope 解密加密信封

      Process: 1. Decrypt DEK using recipient's private key 2. Decrypt ciphertext using DEK

      Parameters:
      envelope - encrypted envelope
      Returns:
      decrypted plaintext
      Throws:
      NullPointerException - if envelope is null
      IllegalStateException - if private key is not set
      OpenCryptoException - if decryption fails

    • decrypt

      public byte[] decrypt(EncryptedEnvelope envelope, byte[] aad)
      Decrypt encrypted envelope with additional authenticated data 解密加密信封，支持附加认证数据
      Parameters:
      envelope - encrypted envelope
      aad - additional authenticated data (must match encryption AAD)
      Returns:
      decrypted plaintext
      Throws:
      NullPointerException - if envelope is null
      IllegalStateException - if private key is not set
      OpenCryptoException - if decryption fails or authentication fails

    • decryptBase64

      public byte[] decryptBase64(String base64Envelope)
      Decrypt Base64 encoded encrypted envelope 解密 Base64 编码的加密信封
      Parameters:
      base64Envelope - Base64 encoded encrypted envelope
      Returns:
      decrypted plaintext
      Throws:
      NullPointerException - if base64Envelope is null
      IllegalStateException - if private key is not set
      OpenCryptoException - if decryption fails

    • getAsymmetricAlgorithm

      public AsymmetricAlgorithm getAsymmetricAlgorithm()
      Get the asymmetric algorithm
      Returns:
      asymmetric algorithm

    • getSymmetricAlgorithm

      public SymmetricAlgorithm getSymmetricAlgorithm()
      Get the symmetric algorithm
      Returns:
      symmetric algorithm