Package cn.gmkit.sm4

Class SM4

java.lang.Object
cn.gmkit.sm4.SM4
public final class SM4 extends Object
SM4 对象式入口。

适合在一个实例上重复执行密钥生成、分组模式配置下的加解密，以及绑定安全上下文后的持续调用。

如果业务更习惯工具类风格，可使用 SM4Util 的静态方法。两套接口共享同一套底层实现， 因此默认行为、错误提示和兼容策略保持一致。

兼容性说明： 支持 JDK 8 及以上版本，依赖 BouncyCastle Provider 提供 SM4 算法实现。

  • Constructor Details

    • SM4

      public SM4()
      创建一个使用默认安全上下文的 SM4 实例。

    • SM4

      public SM4(GmSecurityContext securityContext)
      创建一个绑定指定安全上下文的 SM4 实例。
      Parameters:
      securityContext - Provider 和随机源配置；传入 null 时回退为默认配置

  • Method Details

    • securityContext

      public GmSecurityContext securityContext()
      返回当前实例绑定的安全上下文。
      Returns:
      当前实例使用的安全上下文

    • generateKey

      public byte[] generateKey()
      生成 SM4 密钥。
      Returns:
      16 字节密钥

    • generateKeyHex

      public String generateKeyHex()
      生成十六进制形式的 SM4 密钥。
      Returns:
      十六进制密钥

    • encryptHex

      public SM4CipherResult encryptHex(String keyHex, String data, SM4Options options)
      使用十六进制密钥加密 UTF-8 文本。
      Parameters:
      keyHex - 十六进制密钥
      data - UTF-8 文本
      options - 加密配置
      Returns:
      密文结果

    • encryptHex

      public SM4CipherResult encryptHex(String keyHex, byte[] data, SM4Options options)
      使用十六进制密钥加密字节数组。
      Parameters:
      keyHex - 十六进制密钥
      data - 明文字节数组
      options - 加密配置
      Returns:
      密文结果

    • encrypt

      public SM4CipherResult encrypt(byte[] key, byte[] data)
      使用默认配置加密。
      Parameters:
      key - 16 字节密钥
      data - 明文字节数组
      Returns:
      密文结果

    • encrypt

      public SM4CipherResult encrypt(byte[] key, String data, SM4Options options)
      使用 UTF-8 文本加密。
      Parameters:
      key - 16 字节密钥
      data - 明文字符串
      options - 加密配置
      Returns:
      密文结果

    • encrypt

      public SM4CipherResult encrypt(byte[] key, String data, Charset charset, SM4Options options)
      使用指定字符集编码文本后加密。
      Parameters:
      key - 16 字节密钥
      data - 明文字符串
      charset - 字符集；传入 null 时默认使用 UTF-8
      options - 加密配置
      Returns:
      密文结果

    • encrypt

      public SM4CipherResult encrypt(byte[] key, byte[] data, SM4Options options)
      使用指定配置加密。
      Parameters:
      key - 16 字节密钥
      data - 明文字节数组
      options - 加密配置，传入 null 时使用默认值
      Returns:
      密文结果

    • decryptHex

      public byte[] decryptHex(String keyHex, String ciphertextHex, SM4Options options)
      使用十六进制密钥解密十六进制密文。
      Parameters:
      keyHex - 十六进制密钥
      ciphertextHex - 十六进制密文
      options - 解密配置
      Returns:
      明文字节数组

    • decryptToUtf8

      public String decryptToUtf8(byte[] key, byte[] ciphertext, SM4Options options)
      解密并按 UTF-8 解码返回字符串。
      Parameters:
      key - 16 字节密钥
      ciphertext - 密文字节数组
      options - 解密配置
      Returns:
      UTF-8 字符串

    • decryptToUtf8

      public String decryptToUtf8(byte[] key, SM4CipherResult result, SM4Options options)
      解密 SM4CipherResult 并按 UTF-8 解码返回字符串。
      Parameters:
      key - 16 字节密钥
      result - 密文结果，若包含 AEAD tag 会自动并入配置
      options - 解密配置
      Returns:
      UTF-8 字符串

    • decryptToString

      public String decryptToString(byte[] key, byte[] ciphertext, Charset charset, SM4Options options)
      解密并使用指定字符集解码。
      Parameters:
      key - 16 字节密钥
      ciphertext - 密文字节数组
      charset - 字符集；传入 null 时默认使用 UTF-8
      options - 解密配置
      Returns:
      解码后的字符串

    • decryptToString

      public String decryptToString(byte[] key, SM4CipherResult result, Charset charset, SM4Options options)
      解密并使用指定字符集解码。
      Parameters:
      key - 16 字节密钥
      result - 密文结果
      charset - 字符集；传入 null 时默认使用 UTF-8
      options - 解密配置
      Returns:
      解码后的字符串

    • decrypt

      public byte[] decrypt(byte[] key, SM4CipherResult result, SM4Options options)
      解密 SM4CipherResult。
      Parameters:
      key - 16 字节密钥
      result - 密文结果，若包含 AEAD tag 会自动并入配置
      options - 解密配置
      Returns:
      明文字节数组

    • decrypt

      public byte[] decrypt(byte[] key, byte[] ciphertext)
      使用默认配置解密。
      Parameters:
      key - 16 字节密钥
      ciphertext - 密文字节数组
      Returns:
      明文字节数组

    • decrypt

      public byte[] decrypt(byte[] key, byte[] ciphertext, SM4Options options)
      使用指定配置解密。
      Parameters:
      key - 16 字节密钥
      ciphertext - 密文字节数组
      options - 解密配置，传入 null 时使用默认值
      Returns:
      明文字节数组