服务端接入
Java版接入
SDK集成步骤
- IDEA/Eclipse中导入JAR包
在IDEA/Eclipse的项目的根路径下创建lib
目录。
拷贝服务器端安全组件的jar - netseckit-xxx.jar
到lib
目录中。
- 配置Maven
在pom.xml
中增加如下配置,以便在项目中加入netseckit-xxx.jar
依赖。
<dependency>
<groupId>com.netease.is.nisc</groupId>
<artifactId>netseckit</artifactId>
<version>xxx</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/netseckit-xxx.jar</systemPath>
</dependency>
其中,xxx
为对应的版本号。
- 注意事项
Java SDK版本最低为1.6
。
SDK接口说明
- 导入安全组件类
import
导入
import com.netease.is.nisc.SecurityCipher;
其中,SecurityCipher的构造器为私有的,不能实例化。
- 解密客户端字符串
调用方式:
public static StringDecResult decryptStringFromClient(String encString)
功能描述: 解密客户端SDK加密的字符串。
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
encString | String | 待解密的字符串 |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | StringDecResult | 解密后的对象 |
其中,StringDecResult
说明:
名称 | 类型 | 说明 |
---|---|---|
result | String | 解密后的结果 |
sk | byte[] | 加密服务端数据的密钥 |
type | Integer | 加解密方式 |
其中,type
枚举值说明:
值 | 类型 | 描述 |
---|---|---|
0 | Integer | 普通RSA+AES+HASH(默认) |
1 | Integer | 国密SM2+SM3+SM4 |
异常说明:
异常类型 | 说明 | 可能原因 |
---|---|---|
NullPointerException | 空指针异常 | encString为空/不是客户端加密的数据 |
RsaDecFailedException | RSA解密失败 | RSA私钥错误或不存在 |
AesDecFailedException | AES解密失败 | AES密钥错误 |
DataChangedException | hash值校验失败,数据被篡改 | 数据被篡改 |
SM2DecFailedException | SM2解密失败 | SM2私钥错误或不存在 |
SM4DecFailedException | SM4解密失败 | SM4密钥错误 |
- 加密服务器端字符串
调用方式:
public static String encryptStringToClient(String str, byte[] secretKey, int type)
功能描述:加密服务器端字符串。
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
str | String | 待加密的字符串 |
secretKey | byte[] | 加密密钥(解密时生成的sk) |
type | Integer | 加解密方式(解密得到的type) |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | String | 加密的字符串 |
异常说明:
异常类型 | 说明 | 可能原因 |
---|---|---|
RsaEncFailedException | 签名失败 | RSA私钥不存在 |
AesEncFailedException | AES加密失败 | AES密钥错误 |
SM4EncFailedException | SM4加密失败 | SM4密钥错误 |
- 解密客户端Buffer
调用方式:
public static BufferDecResult decryptBufferFromClient(byte[] encBuffer)
功能描述:解密客户端SDK加密的Buffer。
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
encBuffer | byte[] | 待解密的buffer |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | BufferDecResult | 解密后的对象 |
其中,BufferDecResult
说明:
名称 | 类型 | 说明 |
---|---|---|
result | byte[] | 解密后的buffer |
sk | byte[] | 加密服务端数据的密钥 |
type | Integer | 加解密方式(解密得到的type) |
其中,type
枚举值说明:
值 | 类型 | 描述 |
---|---|---|
0 | Integer | 普通RSA+AES+HASH(默认) |
1 | Integer | 国密SM2+SM3+SM4 |
异常说明:
异常类型 | 说明 | 可能原因 |
---|---|---|
NullPointerException | 解密数据为空 | encBuffer为空/不是客户端加密的数据 |
RsaDecFailedException | RSA解密失败 | RSA私钥错误或不存在 |
AesDecFailedException | AES解密失败 | AES密钥错误 |
DataChangedException | hash值校验失败,数据被篡改 | 数据被篡改 |
SM2DecFailedException | SM2解密失败 | SM2私钥错误或不存在 |
SM4DecFailedException | SM4解密失败 | SM4密钥错误 |
- 加密服务器端Buffer
调用方式:
public static byte[] encryptBufferToClient(byte[] buffer, byte[] secretKey, int type)
功能描述:加密服务器端Buffer。
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
buffer | byte[] | 待加密的buffer |
secretKey | byte[] | 加密密钥(解密时生成的sk) |
type | Integer | 加解密方式(解密得到的type) |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | byte[] | 加密的buffer |
异常说明:
异常类型 | 说明 | 可能原因 |
---|---|---|
RsaEncFailedException | 签名失败 | RSA私钥不存在 |
AesEncFailedException | AES加密失败 | AES密钥错误 |
SM4EncFailedException | SM4加密失败 | SM4密钥错误 |
Python版接入
SDK集成步骤
- 安装
解压压缩包,然后定位到setup.py
文件所在目录。
执行python setup.py install
安装。
- 配置RSA私钥路径
导入Config
类,通过set_private_key_path
方式设置私钥路径。
from netseckit.config import Config
Config.set_private_key_path("/home/appops/private.pem")
注意1:要对private.pem有读的权限。
注意2:私钥已经存放在压缩包中,请注意安全。
- 检查是否安装成功
shell>
python -c "from netseckit.NetSeckit import NetSeckit"
如果上述命令执行无任何错误,则安装成功。
- 注意事项 本SDK支持python 2.7.x 、3.5.x、3.6.x版本。
如果您使用的为其它版本,请以测试为准。
SDK接口说明
- 导入安全组件类
from netseckit.NetSeckit import NetSeckit
- 解密客户端加密字符串
调用方式:
@staticmethod
def decrypt_string_from_client(enc_string)
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
enc_string | unicode | 待解密的字符串 |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | Dict | 解密后的数据 |
其中,Dict说明:
键名称 | 类型 | 说明 |
---|---|---|
sk | byte str | 生成的用于加密服务端数据的密钥 |
data | unicode | 解密后的原始数据 |
异常说明:
异常类型 | 说明 | 可能原因 |
---|---|---|
ParseJSONDataException | 解析字符串错误 | 客户端上传数据格式非法 |
RSAException | RSA解密失败 | 服务器端RSA私钥和客户端公钥不匹配 |
AESException | AES解密失败 | 提取AES密钥错误 |
HashNotEqualException | 客户端上传的HASH值和服务器计算的不一致 | 数据被篡改 |
- 加密服务器端字符串
调用方式
@staticmethod
def encrypt_string_to_client(raw_data, secret_key)
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
raw_data | unicode | 待加密的字符串 |
secret_key | byte str | 加密密钥,解密时生成的sk |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | unicode | 加密后的字符串 |
异常:
异常类型 | 说明 | 可能原因 |
---|---|---|
RSAException | RSA加密失败 | 服务器端私钥不存在或格式错误 |
AESException | AES加密失败 | AES密钥错误或为空 |
- 解密客户端Buffer
调用方式
@staticmethod
def decrypt_buffer_from_client (byte_str)
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
byte_str | byte str | 待解密的buffer |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | Dict | 解密后数据 |
其中,Dict说明:
键名称 | 类型 | 说明 |
---|---|---|
sk | byte str | 生成的用于加密服务端数据的密钥 |
data | byte str | 解密结果 |
异常说明:
异常类型 | 说明 | 可能原因 |
---|---|---|
ParseJSONDataException | 解析byte str错误 | 客户端上传数据格式非法 |
RSAException | RSA解密失败 | 服务器端RSA私钥和客户端公钥不匹配 |
AESException | AES解密失败 | 提取AES密钥错误 |
HashNotEqualException | 客户端上传的HASH值和服务器计算的不一致 | 数据被篡改 |
- 加密服务器端Buffer
调用方式
@staticmethod
def encrypt_buffer_to_client(byte_str, secret_key)
参数说明:
参数名称 | 参数类型 | 参数说明 |
---|---|---|
byte_str | byte str | 要加密的数据,必须为utf-8编码的字节字符串 |
secret_key | byte str | 加密密钥,解密时生成的sk. |
返回值说明:
返回值名称 | 返回值类型 | 返回值说明 |
---|---|---|
-- | byte string | 加密结果 |
异常:
异常类型 | 说明 | 可能原因 |
---|---|---|
RSAException | RSA加密失败 | 服务器端私钥不存在或格式错误 |
AESException | AES加密失败 | AES密钥错误或为空 |