SIMKEY 开放平台

# ClientRemoteEncryption 业务密钥用法

​ 调用服务端实现生成用户密钥，加解密等功能

# 生成用户密钥

  • 定义：
接口说明
接口名称 genUserKey
接口描述 生成用户密钥(数据密钥)
使用者 应用方
  • 输入参数：
参数 数据类型 说明
  • 返回类型：KMSUserKey
    返回用户密钥的加解密密钥密文 和 HMac密钥密文, 都需要存储在数据库。

# 重新保护用户密钥

  • 定义：
接口说明
接口名称 reProtectUserKey
接口描述 重新保护用户密钥(数据密钥)
用户密钥是使用业务密钥保护的, 这里重新保护指的是申请了新的业务密钥,
使用新的业务密钥保护用户密钥, 用户密钥的实际内容不变
即使申请了新的业务密钥, 现有的用户密钥都是可以使用的,
如果怕有泄露的风险, 可以重新保护一下,
更好的建议是按周期申请新的用户密钥, 后续使用新的用户密钥
使用者 应用方
  • 输入参数：
参数 数据类型 说明
userkey String 用户密钥, BASE64格式
  • 返回类型：String
    返回 BASE64 格式的用户密钥, 需要存储在数据库。

# 计算SM3HMAC值(输入为byte[])

  • 定义：
接口说明
接口名称 sm3HMAC
接口描述 使用 hmac key对输入数据计算 sm3hmac
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data byte[] 要计算hmac的数据
outputFormat OutputFormat 输出格式 有长格式和短格式
  • 返回类型：String
    返回字符串格式的SM3HMAC值

# 计算SM3HMAC值(输入为Map<String,String>)

  • 定义：
接口说明
接口名称 sm3HMAC
接口描述 使用 hmac key对输入数据计算 sm3hmac
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data Map<String,String> 数据库中的一行,包括需要进行完整性校验的字段
map 对应数据库密文的一行
map的value从这两个接口直接得到 行数据加密 和 行数据加密并计算SM3HMAC
outputFormat OutputFormat 输出格式 有长格式和短格式
  • 返回类型：String
    返回字符串格式的SM3HMAC值

# 数据加密

  • 定义：
接口说明
接口名称 encryptBytes2Str
接口描述 对数据进行加密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data byte[] 需要加密的数据
outputFormat OutputFormat 输出格式 有长格式和短格式
  • 返回类型：String
    返回字符串类型的加密结果，内部为私有格式，不通用。
  • 注意:使用长格式输出时, 内部使用了随机的向量, 每次加密结果都不一样, 故无法用于有搜索的情况

# 数据解密

  • 定义：
接口说明
接口名称 decryptStr2Bytes
接口描述 对数据进行解密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
ciphertext String 需要解密的数据，必须为 数据加密 返回的结果
  • 返回类型： byte[]
    返回byte[]类型的结果

# UTF8字符串加密

  • 定义：
接口说明
接口名称 encryptUTF8ToStr
接口描述 加密, 将 UTF-8 编码的字符串 加密后以字符串格式返回
使用者 应用方
  • 输入参数：
参数 数据类型 说明
plaintext String 需要加密的数据, 当UTF8字符串处理
outputFormat OutputFormat 输出格式 有长格式和短格式
  • 返回类型： String
    返回字符串, 密文为私有格式, 不通用
  • 注意:业务密钥 短格式 加密结果是不是BASE64
  • 注意:使用长格式输出时, 内部使用了随机的向量, 每次加密结果都不一样, 故无法用于有搜索的情况

# 解密为UTF8字符串

  • 定义：
接口说明
接口名称 decryptStrToUTF8
接口描述 解密, 将字符串的密文 解密后 以 UTF-8 编码的格式返回
使用者 应用方
  • 输入参数：
参数 数据类型 说明
ciphertext String 需要解密的数据，必须为 UTF8字符串加密 返回的结果
  • 返回类型： String
    返回UTF8格式的字符串

# 行数据加密

  • 定义：
接口说明
接口名称 encryptMap
接口描述 对数据库中的一行数据进行加密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data Map<String, String> Key为数据库的列名，
Value为列名对应的值, 按 UTF-8 处理
outputFormat OutputFormat 输出格式 有长格式和短格式

  • 返回类型： Map<String, String>

    返回Map<String, String>类型的加密结果，

    Key为数据库的列名

    Value为数据库列名对应的值的加密结果

  • 注意:使用长格式输出时, 内部使用了随机的向量, 每次加密结果都不一样, 故无法用于有搜索的情况

# 行数据解密

  • 定义：
接口说明
接口名称 decryptMap
接口描述 对数据库中的一行数据进行解密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data Map<String, String> Key为数据库的列名，
Value为列名对应的密文

  • 返回类型： Map<String, String>

    返回Map<String, String>类型的结果，

    Key为数据库的列名

    Value为数据库列名对应的值的解密结果, 按 UTF-8 格式返回

  • 注意:使用长格式输出时, 内部使用了随机的向量, 每次加密结果都不一样, 故无法用于有搜索的情况

# 行数据加密并计算SM3HMAC

  • 定义：
接口说明
接口名称 encryptMapWithSm3hmac
接口描述 对数据库中的一行数据进行加密，并计算sm3hmac值。
返回的map添加"sm3hmac"为key的一项返回
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data Map<String, String> Key为数据库的列名，
Value为列名对应的值, 按 UTF-8 处理
outputFormat OutputFormat 输出格式 有长格式和短格式

  • 返回类型： Map<String, String>

    返回Map<String, String>类型的加密结果，

    Key为数据库的列名

    Value为数据库列名对应的值的加密结果，添加"sm3hmac"为key的一项返回

    Value不能单独更新，计算SM3HMAC的所有字段都当做是一个整体，需要重新计算SM3HMAC值，否则验证SM3HMAC会失败。

  • 注意:使用长格式输出时, 内部使用了随机的向量, 每次加密结果都不一样, 故无法用于有搜索的情况

# 行数据解密并验证SM3HMAC

  • 定义：
接口说明
接口名称 decryptMapAndVerifySm3hmac
接口描述 对数据库中的一行数据进行验证并解密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data Map<String, String> Key为数据库的列名，
Value为列名对应的密文
Key必须包含"sm3hmac"，否则验证失败

  • 返回类型： Map<String, String>

    返回Map<String, String>类型的结果，

    Key为数据库的列名

    Value为数据库列名对应的值的解密结果, 按 UTF-8 格式返回

    如果SM3HMAC验证失败，不会返回解密结果

# 格式保留加密

  • 定义：
接口说明
接口名称 fpeEncrypt
接口描述 格式保留加密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
simkeyFpeAlphabets List< SimkeyFpeAlphabet > 字符集, 大小写敏感
SimkeyFpeAlphabet支持的类型有:
Numeric 数字 0-9
LowerCaseLetter 小写字母 a-z
UpperCaseLetter 大写字母 A-Z
ChinaResidentIDNumber 居民身份证号码 0-9,X
UpperCaseHexNumeric 大写的十六进制字符 0-9,A-F
GB2312 GB/T 2312标准, 共收录6763个汉字
tweak byte[] 调整参数, 作用类似于对称加密里的向量
Tweak是任意长度的byte[]，不是保密的, Tweak是为了解决因局部加密而导致结果冲突问题，通常情况下将数据的不可变部分作为Tweak
例如，在对手机号中间4位进行加密的场景中，132-1234-1111，132-1234-2222，如果没有tweak的参与，那么两者的加密结果肯定相同，因为key相同，被加密的原文都是1234，此时把手机号码的不可变部分1321111和1322222分别作为tweak参与加密，即可得到不一样的加密结果
注意解密时应使用加密时相同的tweak。
originalText String 原文, 每个字符都属于字符集里面的字符
  • 返回类型：String
    返回加密后的字符串, 加密后的字符串的字符串依然在 simkeyFpeAlphabets 里面 比如: 1234 fpe加密结果:3757

# 格式保留解密

  • 定义：
接口说明
接口名称 fpeDecrypt
接口描述 格式保留解密
使用者 应用方
  • 输入参数：
参数 数据类型 说明
simkeyFpeAlphabets List< SimkeyFpeAlphabet > 字符集, 大小写敏感
SimkeyFpeAlphabet支持的类型有:
Numeric 数字 0-9
LowerCaseLetter 小写字母 a-z
UpperCaseLetter 大写字母 A-Z
ChinaResidentIDNumber 居民身份证号码 0-9,X
UpperCaseHexNumeric 大写的十六进制字符 0-9,A-F
GB2312 GB/T 2312标准, 共收录6763个汉字
tweak byte[] 调整参数, 作用类似于对称加密里的向量
Tweak是任意长度的byte[]，不是保密的, Tweak是为了解决因局部加密而导致结果冲突问题，通常情况下将数据的不可变部分作为Tweak
例如，在对手机号中间4位进行加密的场景中，132-1234-1111，132-1234-2222，如果没有tweak的参与，那么两者的加密结果肯定相同，因为key相同，被加密的原文都是1234，此时把手机号码的不可变部分1321111和1322222分别作为tweak参与加密，即可得到不一样的加密结果
注意解密时应使用加密时相同的tweak。
cipherText String 密文, 每个字符都属于字符集里面的字符

  • 返回类型：String
    返回加密后的字符串, 加密后的字符串的字符串依然在 simkeyFpeAlphabets 里面

    比如: 3757 fpe解密结果: 1234

# SM4 GCM 加密

  • 定义：
接口说明
接口名称 sm4GcmEncrypt
接口描述 SM4 GCM加密, 返回的是 对原始密文 直接 BASE64格式编码得到的字符串, 适用于数据加密传输
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data byte[] 要加密的数据
iv byte[] 向量
aad byte[] 附加身份验证数据
  • 返回类型： String
    返回 String 类型的结果

# SM4 GCM 解密

  • 定义：
接口说明
接口名称 sm4GcmDecrypt
接口描述 SM4 GCM解密, 适用于数据加密传输
使用者 应用方
  • 输入参数：
参数 数据类型 说明
data String 要解密的数据
iv byte[] 向量
aad byte[] 附加身份验证数据
  • 返回类型： byte[]
    返回 byte[] 类型的结果

← ClientLocalEncryption 用户密钥用法 →