@lingxiteam/security ·

🚀一个简单、易用、灵活的请求数据安全工具：防报文被篡改、对请求数据加解密。

环境支持

✅ web浏览器 [ ajax, fetch, axios, umi-request ]

✅ nodejs后端

✅ 微信小程序

使用文档

安装

npm install @lingxiteam/security

or

yarn add @lingxiteam/security

使用

简单使用

在web端：

import { httpEncryption } from '@lingxiteam/security';

httpEncryption.start({ mode: '1.0' });

在小程序：

const security = require('@lingxiteam/security').default;

security.httpEncryption.start({ mode: '1.0' });

安全模式

| 模式值 | 模式 | 说明 | | ------ | -------------- | ------------------------------------------------------------ | | 1.0 | 默认参数签名 | 对url地址、query参数、header参数、body参数、盐值等按照一定方式生成签名 | | 1.1 | 时间限制性签名 | 签名内容增加时间因子，在一段时间内有效 | | 1.2 | 唯一限制性签名 | 生成uuid签名，仅可使用1次 | | 2.0 | RSA参数加密 | 使用RSA非对称加密算法进行内容加密 | | 3.0 | AES参数加密 | 使用AES加密算法进行内容加密 |

[!NOTE]

1. 请求内容和响应内容模式独立，即请求时使用2.0，响应可使用3.0，我们可以针对部分服务进行差异性处理，只需在响应头部返回 Xa-type 字段告知模式值即可。

2. 签名和加解密默认使用灵犀平台预置方式，如对接其他平台，可以通过参数配置完成自定义加解密处理。

规则

mode优先级

最高：通过start方法或setConfig方法设置mode，security.httpEncryption.start({ mode: '1.0' }); 其次：后端控制，当mode配置项未设置时，将读取后端的配置 缺省值 1.1

全局忽略

有时候安全模式并不适用某些服务，如非灵犀平台服务、CORS请求，可以通过配置 ignore 规则来对符合规则的服务不触发请求和响应内容的处理。

import { setConfig } from '@lingxiteam/security';

// 指定服务地址
setConfig({
  ignore: "api/test",
});

// 正则表达式
setConfig({
  ignore: /^https/, 
});

// 函数判断，返回true表示忽略
setConfig({
  ignore: (url, {headers, body, method}) => { /* const isIgnore = ... */ return isIgnore; }, 
});

// 多条件组合, 满足其中一个即忽略
setConfig({
  ignore: [/^https/, (url, {headers, body, method}) => { /* const isIgnore = ... */ return isIgnore; }], 
});

单服务指定

在一些需求场景中，我们可以针对某一服务指定对应的安全模式，在请求头添加 Xa-type 并设置一个模式值即可，如果将该字段设置为‘false’，将不触发该请求和响应内容的处理。

注意📢：被 ignore 的服务无法进行指定

签名加盐

在使用 cookie session的场景，往往安全要求sessionId需要设置为httpOnly，这样签名程序无法对该值进行签名，攻击者通过更改sessionId对服务发起攻击，如果接口存在疏忽没有对权限正确校验，将会出现越权操作。为最大限度进行防范，建议增加一个以用户信息(userId、userCode)作为盐。

// web端
import { setConfig, lxEncrypt } from '@lingxiteam/security';
setConfig({ sign: { saltKey: 'userId' } }); // 自动从cookie上获取值

// 非web端或cookie不可使用
setConfig({ sign: { saltKey: 'userId', saltValue: '...' } });

资源地址签名

当通过 img、script、link 等标签方式加载资源时，无法通过请求头进行添加签名，我们可以使用 createHttpSignWithUrl 方法为资源地址后添加签名参数

import { createHttpSignWithUrl } from '@lingxiteam/security';

const imgSrc = createHttpSignWithUrl('/app/file/id/123');

自定义加解密

通过 setConfig 方法进行自定义配置

import { setConfig, lxEncrypt } from '@lingxiteam/security';

// 密钥配置均支持经过lxEncrypt方法二次加密内容
setConfig({
  rsa: {
    // RSA公钥
    publicKey: '...',
    // RSA私钥
    privKey: '...',
    // 自定义RSA加密，返回加密后内容
    encrypt: (conetnt, publicKey) => '...',
    // 自定义RSA解密，返回解密后内容
    decrypt: (conetnt, privKey) => '...',
  },
  
  aes: {
    // AES密钥
    key: '...',
    // 自定义AES加密，返回加密后内容
    encrypt: (conetnt, key) => '...',
    // 自定义AES解密，返回解密后内容
    decrypt: (conetnt, key) => '...',
  }

  des: {
  	// DES密钥
    key: '...',
    // 自定义DES加密，返回加密后内容
    encrypt: (conetnt, key) => '...',
    // 自定义DES解密，返回解密后内容
    decrypt: (conetnt, key) => '...',
	}
  
  // 支持密钥二次加密
  keyEncrypt: true,
});

后端控制

在web端可以引入服务器上app/env/info.js ，并通过平台界面配置来动态控制安全模式相关配置。

在小程序上可以根据服务返回的参数进行设置：

const security = require('@lingxiteam/security').default;

// 与平台对接，单点后拿到 refreshAccessToken、secretKey、secretValue、accessToken、lxServerTime、lxSecurityMode
// 启动安全签名
security.httpEncryption.start({
    mode: lxSecurityMode,
    sign: {
        saltKey: secretKey,
        saltValue: secretValue,
    },
    serverTime: lxServerTime,
});

手动模式

当执行 httpEncryption.start() 后，程序进行将自动处理所有异步请求，执行 httpEncryption.stop() 将释放控制权。如果自动模式无法满足或出现与其他程序使用不兼容，可以通过使用原始的方法自行进行处理。

import { createHttpSignStr, RSAEncrypt, RSADecrypt, AESEncrypt, AESDecrypt, DESEncrypt, DESDecrypt } from '@lingxiteam/security';

// 生成签名
const xSign = createHttpSignStr(url, { headers, body, method, saltValue }, signMode);

// 加密
const RSAEncryptContent = RSAEncrypt(content, key);
const AESEncryptContent = AESEncrypt(content, key);
const DESEncryptContent = DESEncrypt(content, key);

// 解密
const RSADecryptContent = RSADecrypt(content, key);
const AESDecryptContent = AESDecrypt(content, key);
const DESDecryptContent = DESDecrypt(content, key);

其他

空值body

当body为空时，可能出现前后端取值不一致问题。nodejs后端一般存在空字符串、空对象、undefined 等值，这取决于框架处理和使用的中间件；java后端一般为null。为避免前后端取值差异导致签名校验失败，可以通过配置项将前端空值进行转换与后端保持一致。缺省值为空字符串。

import { setConfig } from '@lingxiteam/security';

setConfig({ emptyBodyValue: '{}' });

webpack5下使用

使用webpack5工程出现 Module not found: Error: Can't resolve 'crypto', 此时需要调整webpack配置项

{
  "resolve": {
    "fallback": {
      "crypto": false
    }
  }
}

调试

设置debug模式，控制台将输出相关日志信息

// 配置设置
import { setConfig } from '@lingxiteam/security';

setConfig({ debug: true });

// or 
localStorage.setItem('lxDebug', 'true');