Class Sm4Cipher

java.lang.Object
cloud.opencode.base.crypto.symmetric.Sm4Cipher
All Implemented Interfaces:
AeadCipher, SymmetricCipher
public final class Sm4Cipher extends Object implements SymmetricCipher, AeadCipher
SM4 cipher implementation (Chinese national cryptographic standard). SM4 加密实现（中国国家密码标准）。

Requires Bouncy Castle provider for SM4 support. 需要 Bouncy Castle 提供商支持 SM4。

Features | 主要功能:

  • SM4-GCM and SM4-CBC modes - SM4-GCM 和 SM4-CBC 模式
  • Chinese national standard (GB/T 32907-2016) - 中国国密标准（GB/T 32907-2016）
  • Requires Bouncy Castle provider - 需要 Bouncy Castle 提供者

Usage Examples | 使用示例:

AeadCipher sm4 = Sm4Cipher.gcm();
byte[] encrypted = sm4.encrypt(plaintext, key);

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:

  • Method Details

    • cbc

      public static Sm4Cipher cbc()
      Create SM4 cipher in CBC mode. 创建 CBC 模式的 SM4 加密器。
      Returns:
      SM4-CBC cipher instance / SM4-CBC 加密实例

    • gcm

      public static Sm4Cipher gcm()
      Create SM4 cipher in GCM mode (AEAD). 创建 GCM 模式的 SM4 加密器（AEAD）。
      Returns:
      SM4-GCM cipher instance / SM4-GCM 加密实例

    • isBouncyCastleAvailable

      public static boolean isBouncyCastleAvailable()
      Check if Bouncy Castle provider is available. 检查 Bouncy Castle 提供商是否可用。
      Returns:
      true if available / 如果可用则返回 true

    • setKey

      public Sm4Cipher setKey(SecretKey key)
      Description copied from interface: SymmetricCipher
      Set the secret key. 设置密钥。
      Specified by:
      setKey in interface AeadCipher
      Specified by:
      setKey in interface SymmetricCipher
      Parameters:
      key - secret key / 密钥
      Returns:
      this cipher instance / 当前加密实例

    • setKey

      public Sm4Cipher setKey(byte[] key)
      Description copied from interface: SymmetricCipher
      Set the secret key from bytes. 从字节数组设置密钥。
      Specified by:
      setKey in interface AeadCipher
      Specified by:
      setKey in interface SymmetricCipher
      Parameters:
      key - key bytes / 密钥字节
      Returns:
      this cipher instance / 当前加密实例

    • setIv

      public Sm4Cipher setIv(byte[] iv)
      Description copied from interface: SymmetricCipher
      Set the initialization vector. 设置初始化向量。
      Specified by:
      setIv in interface AeadCipher
      Specified by:
      setIv in interface SymmetricCipher
      Parameters:
      iv - initialization vector / 初始化向量
      Returns:
      this cipher instance / 当前加密实例

    • setNonce

      public Sm4Cipher setNonce(byte[] nonce)
      Description copied from interface: AeadCipher
      Set the nonce (same as IV for most AEAD ciphers). 设置随机数（对于大多数 AEAD 密码与 IV 相同）。
      Specified by:
      setNonce in interface AeadCipher
      Parameters:
      nonce - nonce bytes / 随机数字节
      Returns:
      this cipher instance / 当前加密实例

    • setAad

      public Sm4Cipher setAad(byte[] aad)
      Description copied from interface: AeadCipher
      Set additional authenticated data (AAD). 设置附加认证数据（AAD）。
      Specified by:
      setAad in interface AeadCipher
      Parameters:
      aad - additional authenticated data / 附加认证数据
      Returns:
      this cipher instance / 当前加密实例

    • setMode

      public Sm4Cipher 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 Sm4Cipher 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 / 当前加密实例

    • setTagLength

      public Sm4Cipher setTagLength(int tagBits)
      Description copied from interface: AeadCipher
      Set authentication tag length in bits. 设置认证标签长度（比特）。
      Specified by:
      setTagLength in interface AeadCipher
      Parameters:
      tagBits - tag length in bits / 标签长度（比特）
      Returns:
      this cipher instance / 当前加密实例

    • encrypt

      public byte[] encrypt(byte[] plaintext)
      Description copied from interface: SymmetricCipher
      Encrypt plaintext bytes. 加密明文字节。
      Specified by:
      encrypt in interface AeadCipher
      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 AeadCipher
      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 AeadCipher
      Specified by:
      encryptBase64 in interface SymmetricCipher
      Parameters:
      plaintext - plaintext bytes / 明文字节
      Returns:
      Base64 encoded ciphertext / Base64 编码的密文

    • encryptBase64

      public String encryptBase64(String plaintext)
      Description copied from interface: AeadCipher
      Encrypt string and encode as Base64. 加密字符串并编码为 Base64。
      Specified by:
      encryptBase64 in interface AeadCipher
      Parameters:
      plaintext - plaintext string / 明文字符串
      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 AeadCipher
      Specified by:
      encryptHex in interface SymmetricCipher
      Parameters:
      plaintext - plaintext bytes / 明文字节
      Returns:
      hex encoded ciphertext / 十六进制编码的密文

    • encryptFile

      public void encryptFile(Path source, Path target)
      Description copied from interface: AeadCipher
      Encrypt a file. 加密文件。
      Specified by:
      encryptFile in interface AeadCipher
      Parameters:
      source - source file path / 源文件路径
      target - target file path / 目标文件路径

    • encryptStream

      public OutputStream encryptStream(OutputStream output)
      Description copied from interface: AeadCipher
      Create an encrypting output stream. 创建加密输出流。
      Specified by:
      encryptStream in interface AeadCipher
      Parameters:
      output - underlying output stream / 底层输出流
      Returns:
      encrypting output stream / 加密输出流

    • decrypt

      public byte[] decrypt(byte[] ciphertext)
      Description copied from interface: SymmetricCipher
      Decrypt ciphertext bytes. 解密密文字节。
      Specified by:
      decrypt in interface AeadCipher
      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 AeadCipher
      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 AeadCipher
      Specified by:
      decryptBase64 in interface SymmetricCipher
      Parameters:
      base64Ciphertext - Base64 encoded ciphertext / Base64 编码的密文
      Returns:
      plaintext bytes / 明文字节

    • decryptBase64ToString

      public String decryptBase64ToString(String base64Ciphertext)
      Description copied from interface: AeadCipher
      Decrypt Base64 encoded ciphertext to string. 解密 Base64 编码的密文为字符串。
      Specified by:
      decryptBase64ToString in interface AeadCipher
      Parameters:
      base64Ciphertext - Base64 encoded ciphertext / Base64 编码的密文
      Returns:
      plaintext string / 明文字符串

    • decryptHex

      public byte[] decryptHex(String hexCiphertext)
      Description copied from interface: SymmetricCipher
      Decrypt hexadecimal encoded ciphertext. 解密十六进制编码的密文。
      Specified by:
      decryptHex in interface AeadCipher
      Specified by:
      decryptHex in interface SymmetricCipher
      Parameters:
      hexCiphertext - hex encoded ciphertext / 十六进制编码的密文
      Returns:
      plaintext bytes / 明文字节

    • decryptFile

      public void decryptFile(Path source, Path target)
      Description copied from interface: AeadCipher
      Decrypt a file. 解密文件。
      Specified by:
      decryptFile in interface AeadCipher
      Parameters:
      source - source file path / 源文件路径
      target - target file path / 目标文件路径

    • decryptStream

      public InputStream decryptStream(InputStream input)
      Description copied from interface: AeadCipher
      Create a decrypting input stream. 创建解密输入流。
      Specified by:
      decryptStream in interface AeadCipher
      Parameters:
      input - underlying input stream / 底层输入流
      Returns:
      decrypting input stream / 解密输入流

    • generateIv

      public byte[] generateIv()
      Description copied from interface: SymmetricCipher
      Generate a random initialization vector. 生成随机初始化向量。
      Specified by:
      generateIv in interface AeadCipher
      Specified by:
      generateIv in interface SymmetricCipher
      Returns:
      IV bytes / 初始化向量字节

    • generateNonce

      public byte[] generateNonce()
      Description copied from interface: AeadCipher
      Generate a random nonce. 生成随机随机数。
      Specified by:
      generateNonce in interface AeadCipher
      Returns:
      nonce 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 / 块大小

    • getIvLength

      public int getIvLength()
      Description copied from interface: SymmetricCipher
      Get the IV length in bytes. 获取 IV 长度（字节）。
      Specified by:
      getIvLength in interface AeadCipher
      Specified by:
      getIvLength in interface SymmetricCipher
      Returns:
      IV length / IV 长度

    • getAlgorithm

      public String getAlgorithm()
      Description copied from interface: SymmetricCipher
      Get the algorithm name. 获取算法名称。
      Specified by:
      getAlgorithm in interface AeadCipher
      Specified by:
      getAlgorithm in interface SymmetricCipher
      Returns:
      algorithm name / 算法名称

    • 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:
      IV bytes / 初始化向量字节

    • getKey

      public SecretKey getKey()
      Get current key. 获取当前密钥。
      Returns:
      secret key / 密钥