服务端接入

2022.02.14 18:32:34

    Java版接入

    SDK集成步骤

    • IDEA/Eclipse中导入JAR包

    在IDEA/Eclipse的项目的根路径下创建lib目录。

    拷贝服务器端安全组件的jar - netseckit-xxx.jarlib目录中。

    • 配置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密钥错误或为空
    Online Chat Tel:95163223