java.lang.Object

cloud.opencode.base.crypto.symmetric.AesCipher

All Implemented Interfaces:: SymmetricCipher

public final class AesCipher extends Object implements SymmetricCipher

AES cipher implementation supporting CBC and CTR modes. AES 加密实现，支持 CBC 和 CTR 模式。

Features | 主要功能:

AES-CBC and AES-CTR modes - AES-CBC 和 AES-CTR 模式
128/192/256-bit key support - 128/192/256 位密钥支持
Automatic IV generation and prepending - 自动 IV 生成和前置
Raw mode for protocol-specific use (fixed IV, no IV prepending) - 协议专用裸模式（固定 IV，不前置 IV）

Usage Examples | 使用示例:

AesCipher cipher = AesCipher.cbc();
cipher.setKey(secretKey);
byte[] encrypted = cipher.encrypt(plaintext);

Security | 安全性:

Thread-safe: No - 线程安全: 否
Null-safe: Partial - 空值安全: 部分

Performance | 性能特性:

Time complexity: O(n) - 时间复杂度: O(n)，n为明文长度
Space complexity: O(1) - 空间复杂度: O(1)

Since:

JDK 25, opencode-base-crypto V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

AesCipher.Builder

Builder class for AES cipher.
Method Summary

Modifier and Type

Method

Description

static AesCipher

aes128()

Create AES-128 cipher.

static AesCipher

aes256()

Create AES-256 cipher (recommended).

static AesCipher.Builder

builder()

Create a builder for AES cipher.

static AesCipher

cbc()

Create AES cipher in CBC mode.

static AesCipher

ctr()

Create AES cipher in CTR mode.

byte[]

decrypt(byte[] ciphertext)

Decrypt ciphertext bytes.

byte[]

decryptBase64(String base64Ciphertext)

Decrypt Base64 encoded ciphertext.

byte[]

decryptHex(String hexCiphertext)

Decrypt hexadecimal encoded ciphertext.

byte[]

decryptRaw(byte[] ciphertext)

Decrypt using the pre-set IV.

String

decryptToString(byte[] ciphertext)

Decrypt and convert to string.

byte[]

encrypt(byte[] plaintext)

Encrypt plaintext bytes.

byte[]

encrypt(String plaintext)

Encrypt plaintext string.

String

encryptBase64(byte[] plaintext)

Encrypt and encode as Base64.

String

encryptHex(byte[] plaintext)

Encrypt and encode as hexadecimal.

byte[]

encryptRaw(byte[] plaintext)

Encrypt using the pre-set IV without generating a new one and without prepending the IV to the output.

byte[]

generateIv()

Generate a random initialization vector.

SecretKey

generateKey(int keySize)

Generate a new secret key.

String

getAlgorithm()

Get the algorithm name.

int

getBlockSize()

Get the block size in bytes.

byte[]

getIv()

Get current IV (returns a defensive copy).

int

getIvLength()

Get the IV length in bytes.

SecretKey

getKey()

Get current key.

AesCipher

setIv(byte[] iv)

Set the initialization vector.

AesCipher

setKey(byte[] key)

Set the secret key from bytes.

AesCipher

setKey(SecretKey key)

Set the secret key.

AesCipher

setMode(CipherMode mode)

Set the cipher mode.

AesCipher

setPadding(Padding padding)

Set the padding scheme.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- aes128
  
  public static AesCipher aes128()
  
  Create AES-128 cipher. 创建 AES-128 加密器。
  
  Returns:
  
  AES-128 cipher instance / AES-128 加密实例
- aes256
  
  public static AesCipher aes256()
  
  Create AES-256 cipher (recommended). 创建 AES-256 加密器（推荐）。
  
  Returns:
  
  AES-256 cipher instance / AES-256 加密实例
- cbc
  
  public static AesCipher cbc()
  
  Create AES cipher in CBC mode. 创建 CBC 模式的 AES 加密器。
  
  Returns:
  
  AES-CBC cipher instance / AES-CBC 加密实例
- ctr
  
  public static AesCipher ctr()
  
  Create AES cipher in CTR mode. 创建 CTR 模式的 AES 加密器。
  
  Returns:
  
  AES-CTR cipher instance / AES-CTR 加密实例
- builder
  
  public static AesCipher.Builder builder()
  
  Create a builder for AES cipher. 创建 AES 加密器构建器。
  
  Returns:
  
  builder instance / 构建器实例
- setKey
  
  public AesCipher setKey(SecretKey key)
  
  Description copied from interface: SymmetricCipher
  
  Set the secret key. 设置密钥。
  
  Specified by:
  
  setKey in interface SymmetricCipher
  
  Parameters:
  
  key - secret key / 密钥
  
  Returns:
  
  this cipher instance / 当前加密实例
- setKey
  
  public AesCipher setKey(byte[] key)
  
  Description copied from interface: SymmetricCipher
  
  Set the secret key from bytes. 从字节数组设置密钥。
  
  Specified by:
  
  setKey in interface SymmetricCipher
  
  Parameters:
  
  key - key bytes / 密钥字节
  
  Returns:
  
  this cipher instance / 当前加密实例
- setIv
  
  public AesCipher setIv(byte[] iv)
  
  Description copied from interface: SymmetricCipher
  
  Set the initialization vector. 设置初始化向量。
  
  Specified by:
  
  setIv in interface SymmetricCipher
  
  Parameters:
  
  iv - initialization vector / 初始化向量
  
  Returns:
  
  this cipher instance / 当前加密实例
- setMode
  
  public AesCipher setMode(CipherMode mode)
  
  Description copied from interface: SymmetricCipher
  
  Set the cipher mode. 设置加密模式。
  
  Specified by:
  
  setMode in interface SymmetricCipher
  
  Parameters:
  
  mode - cipher mode / 加密模式
  
  Returns:
  
  this cipher instance / 当前加密实例
- setPadding
  
  public AesCipher setPadding(Padding padding)
  
  Description copied from interface: SymmetricCipher
  
  Set the padding scheme. 设置填充方案。
  
  Specified by:
  
  setPadding in interface SymmetricCipher
  
  Parameters:
  
  padding - padding scheme / 填充方案
  
  Returns:
  
  this cipher instance / 当前加密实例
- encrypt
  
  public byte[] encrypt(byte[] plaintext)
  
  Description copied from interface: SymmetricCipher
  
  Encrypt plaintext bytes. 加密明文字节。
  
  Specified by:
  
  encrypt in interface SymmetricCipher
  
  Parameters:
  
  plaintext - plaintext bytes / 明文字节
  
  Returns:
  
  ciphertext bytes / 密文字节
- encrypt
  
  public byte[] encrypt(String plaintext)
  
  Description copied from interface: SymmetricCipher
  
  Encrypt plaintext string. 加密明文字符串。
  
  Specified by:
  
  encrypt in interface SymmetricCipher
  
  Parameters:
  
  plaintext - plaintext string / 明文字符串
  
  Returns:
  
  ciphertext bytes / 密文字节
- encryptBase64
  
  public String encryptBase64(byte[] plaintext)
  
  Description copied from interface: SymmetricCipher
  
  Encrypt and encode as Base64. 加密并编码为 Base64。
  
  Specified by:
  
  encryptBase64 in interface SymmetricCipher
  
  Parameters:
  
  plaintext - plaintext bytes / 明文字节
  
  Returns:
  
  Base64 encoded ciphertext / Base64 编码的密文
- encryptHex
  
  public String encryptHex(byte[] plaintext)
  
  Description copied from interface: SymmetricCipher
  
  Encrypt and encode as hexadecimal. 加密并编码为十六进制。
  
  Specified by:
  
  encryptHex in interface SymmetricCipher
  
  Parameters:
  
  plaintext - plaintext bytes / 明文字节
  
  Returns:
  
  hex encoded ciphertext / 十六进制编码的密文
- encryptRaw
  
  public byte[] encryptRaw(byte[] plaintext)
  
  Encrypt using the pre-set IV without generating a new one and without prepending the IV to the output. The caller must have called setIv(byte[]) first. 使用预设 IV 加密，不生成新 IV，不将 IV 前置到输出。调用方必须先调用 setIv(byte[])。
  This method is intended for protocol-specific scenarios (e.g. WeCom, Feishu) where the IV is derived externally (e.g. from the key) and must not be included in the ciphertext. For general-purpose encryption, prefer encrypt(byte[]) which generates a random IV and prepends it for safe transport.
  
  此方法适用于协议特定场景（如企业微信、飞书），其中 IV 由外部派生（如从密钥中取），且不能包含在密文中。通用加密请使用 encrypt(byte[])，它会生成随机 IV 并前置。
  
  Parameters:
  
  plaintext - plaintext bytes / 明文字节
  
  Returns:
  
  ciphertext bytes (IV not included) / 密文字节（不含 IV）
  
  Throws:
  
  OpenCryptoException - if IV is not set or encryption fails / 如果未设置 IV 或加密失败
- decryptRaw
  
  public byte[] decryptRaw(byte[] ciphertext)
  
  Decrypt using the pre-set IV. The input must be pure ciphertext without a prepended IV. The caller must have called setIv(byte[]) first. 使用预设 IV 解密。输入必须是纯密文，不含前置 IV。调用方必须先调用 setIv(byte[])。
  This is the counterpart of encryptRaw(byte[]) for protocol-specific scenarios where the IV is managed externally.
  
  此方法是 encryptRaw(byte[]) 的对应解密方法，适用于 IV 由外部管理的协议场景。
  
  Parameters:
  
  ciphertext - ciphertext bytes (IV not included) / 密文字节（不含 IV）
  
  Returns:
  
  plaintext bytes / 明文字节
  
  Throws:
  
  OpenCryptoException - if IV is not set or decryption fails / 如果未设置 IV 或解密失败
- decrypt
  
  public byte[] decrypt(byte[] ciphertext)
  
  Description copied from interface: SymmetricCipher
  
  Decrypt ciphertext bytes. 解密密文字节。
  
  Specified by:
  
  decrypt in interface SymmetricCipher
  
  Parameters:
  
  ciphertext - ciphertext bytes / 密文字节
  
  Returns:
  
  plaintext bytes / 明文字节
- decryptToString
  
  public String decryptToString(byte[] ciphertext)
  
  Description copied from interface: SymmetricCipher
  
  Decrypt and convert to string. 解密并转换为字符串。
  
  Specified by:
  
  decryptToString in interface SymmetricCipher
  
  Parameters:
  
  ciphertext - ciphertext bytes / 密文字节
  
  Returns:
  
  plaintext string / 明文字符串
- decryptBase64
  
  public byte[] decryptBase64(String base64Ciphertext)
  
  Description copied from interface: SymmetricCipher
  
  Decrypt Base64 encoded ciphertext. 解密 Base64 编码的密文。
  
  Specified by:
  
  decryptBase64 in interface SymmetricCipher
  
  Parameters:
  
  base64Ciphertext - Base64 encoded ciphertext / Base64 编码的密文
  
  Returns:
  
  plaintext bytes / 明文字节
- decryptHex
  
  public byte[] decryptHex(String hexCiphertext)
  
  Description copied from interface: SymmetricCipher
  
  Decrypt hexadecimal encoded ciphertext. 解密十六进制编码的密文。
  
  Specified by:
  
  decryptHex in interface SymmetricCipher
  
  Parameters:
  
  hexCiphertext - hex encoded ciphertext / 十六进制编码的密文
  
  Returns:
  
  plaintext bytes / 明文字节
- generateIv
  
  public byte[] generateIv()
  
  Description copied from interface: SymmetricCipher
  
  Generate a random initialization vector. 生成随机初始化向量。
  
  Specified by:
  
  generateIv in interface SymmetricCipher
  
  Returns:
  
  IV bytes / 初始化向量字节
- getBlockSize
  
  public int getBlockSize()
  
  Description copied from interface: SymmetricCipher
  
  Get the block size in bytes. 获取块大小（字节）。
  
  Specified by:
  
  getBlockSize in interface SymmetricCipher
  
  Returns:
  
  block size / 块大小
- getAlgorithm
  
  public String getAlgorithm()
  
  Description copied from interface: SymmetricCipher
  
  Get the algorithm name. 获取算法名称。
  
  Specified by:
  
  getAlgorithm in interface SymmetricCipher
  
  Returns:
  
  algorithm name / 算法名称
- getIvLength
  
  public int getIvLength()
  
  Description copied from interface: SymmetricCipher
  
  Get the IV length in bytes. 获取 IV 长度（字节）。
  
  Specified by:
  
  getIvLength in interface SymmetricCipher
  
  Returns:
  
  IV length / IV 长度
- generateKey
  
  public SecretKey generateKey(int keySize)
  
  Description copied from interface: SymmetricCipher
  
  Generate a new secret key. 生成新密钥。
  
  Specified by:
  
  generateKey in interface SymmetricCipher
  
  Parameters:
  
  keySize - key size in bits / 密钥大小（比特）
  
  Returns:
  
  generated secret key / 生成的密钥
- getIv
  
  public byte[] getIv()
  
  Get current IV (returns a defensive copy). 获取当前初始化向量（返回防御性副本）。
  
  Returns:
  
  IV bytes / 初始化向量字节
- getKey
  
  public SecretKey getKey()
  
  Get current key. 获取当前密钥。
  
  Returns:
  
  secret key / 密钥

Class AesCipher

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Details

aes128

aes256

cbc

ctr

builder

setKey

setKey

setIv

setMode

setPadding

encrypt

encrypt

encryptBase64

encryptHex

encryptRaw

decryptRaw

decrypt

decryptToString

decryptBase64

decryptHex

generateIv

getBlockSize

getAlgorithm

getIvLength

generateKey

getIv

getKey