gws-client 0.5.2 → 0.5.3

package/README.md

@@ -1 +1,626 @@
-# gws-client
+## 简介
+
+用于web前端调用GZCA数字证书客户端UKEY证书应用接口，调用前需确保已安装GZCA数字证书客户端并启动，支持TypeScript。
+
+## 快速开始
+
+### 安装
+
+#### 使用包管理器
+
+Install with npm
+
+```sh
+npm install gws-client --save
+```
+
+Install with yarn
+
+```sh
+yarn add gws-client
+```
+
+Install with pnpm
+
+```sh
+pnpm add gws-client
+```
+
+### 使用
+
+#### ES Module
+
+使用包管理器
+
+```ts
+import { GwsService } from "gws-client";
+const gwsService = new GwsService(gwsServiceConfig);
+```
+
+```ts
+import { createService } from "gws-client";
+async function foo() {
+  const gwsService = await createService(gwsServiceConfig);
+}
+```
+
+使用本地文件
+
+```ts
+import { GwsService } from "./index.es.js"; // SDK文件地址
+const gwsService = new GwsService(gwsServiceConfig);
+```
+
+```ts
+import { createService } from "./index.es.js"; // SDK文件地址
+async function foo() {
+  const gwsService = await createService(gwsServiceConfig);
+}
+```
+
+#### UMD
+
+```html
+<script src="./index.umd.js"></script>
+```
+
+```ts
+const gwsService = new GWS_CLIENT.GwsService(gwsServiceConfig);
+```
+
+```ts
+async function foo() {
+  const gwsService = await GWS_CLIENT.createService(gwsServiceConfig);
+}
+```
+
+#### 实例化参数说明
+
+| 属性          | 说明                       | 类型                                  | 默认值  |
+| ------------- | -------------------------- | ------------------------------------- | ------- |
+| isRememberPin | 可选，是否记住pin码        | `Boolean`                             | `false` |
+| pinPolicy     | 可选，口令安全策略         | `0` \| `1`\| `2`\| `3`                | `0`     |
+| onOpen        | 可选，socket连接成功回调   | `(event: Event) => void`              | --      |
+| onError       | 可选，socket错误时回调     | `(event: Event) => void`              | --      |
+| onClose       | 可选，socket关闭时回调     | `(event: Event) => void`              | --      |
+| onMessage     | 可选，socket收到消息时回调 | `(data: Record<string, any>) => void` | --      |
+| onUkeyEvent   | 可选，Ukey插入拔出时回调   | `(data: Record<string, any>) => void` | --      |
+
+#### 示例
+
+链式调用
+
+```ts
+// PKCS1签名
+import { createService } from "gws-client";
+function pkcs1Sign() {
+  createService(gwsServiceConfig).then((gwsService) => {
+    gwsService
+      .pkcs1Sign({ Data: "hello world" })
+      .then((res) => {
+        console.log("签名值", res);
+      })
+      .catch((error) => {
+        console.log("签名失败原因", error);
+      });
+  });
+}
+```
+
+同步调用
+
+```ts
+// PKCS1签名
+import { createService } from "gws-client";
+async function pkcs1Sign() {
+  try {
+    const gwsService = await createService(); 
+    const res = await gwsService.pkcs1Sign({ Data: "hello world" });
+    console.log("签名值", res);
+  } catch (error) {
+    console.log("签名失败原因", error);
+  }
+}
+```
+
+## API接口
+
+### 销毁
+
+断开socket连接
+
+#### 接口名称
+
+destroy
+
+#### 函数签名
+
+```ts
+type Destroy = () => void;
+```
+
+### 重启
+
+重新连接socket，可重新传入新配置
+
+#### 接口名称
+
+restart
+
+#### 函数签名
+
+```ts
+type Restart = (config?: GwsServiceConfigType) => void;
+```
+
+### PKCS1签名
+
+PKCS1签名，返回签名值
+
+#### 接口名称
+
+pkcs1Sign
+
+#### 函数签名
+
+```ts
+type Pkcs1Sign = (params: { Data: string }) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性 | 说明             | 类型     | 默认值 |
+| ---- | ---------------- | -------- | ------ |
+| Data | 必填，待签名原文 | `String` | --     |
+
+### PKCS1验签
+
+PKCS1验签，返回验签结果，`true`为验签成功，验签失败时返回`Promise.reject`
+
+#### 接口名称
+
+pkcs1VerifySignature
+
+#### 函数签名
+
+```ts
+type Pkcs1VerifySignature = (params: {
+  CertB64?: string;
+  Data: string;
+  SignData: string;
+}) => Promise<boolean>;
+```
+
+#### 参数说明
+
+| 属性     | 说明                       | 类型     | 默认值 |
+| -------- | -------------------------- | -------- | ------ |
+| Data     | 必填，待签名原文           | `String` | --     |
+| SignData | 必填，Base64编码的签名值   | `String` | --     |
+| CertB64  | 可选，Base64编码的签名证书 | `String` | --     |
+
+### PKCS1 B64签名
+
+PKCS1 base64签名，返回签名值
+
+#### 接口名称
+
+pkcs1Base64Sign
+
+#### 函数签名
+
+```ts
+type Pkcs1Base64Sign = (params: {
+  Data?: string;
+  DataB64?: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性    | 说明                                                          | 类型     | 默认值 |
+| ------- | ------------------------------------------------------------- | -------- | ------ |
+| Data    | 与DataB64二选一，待签名原文                                   | `String` | --     |
+| DataB64 | 与Data二选一 ， Base64编码的待签名原文，同时存在时使用DataB64 | `String` | --     |
+
+### PKCS1 B64验签
+
+PKCS1 base64验签，返回验签结果，`true`为验签成功，验签失败时返回`Promise.reject`
+
+#### 接口名称
+
+pkcs1Base64VerifySignature
+
+#### 函数签名
+
+```ts
+type Pkcs1Base64VerifySignature = (params: {
+  Data?: string;
+  DataB64?: string;
+  SignData: string;
+  CertB64?: string;
+}) => Promise<boolean>;
+```
+
+#### 参数说明
+
+| 属性     | 说明                                                          | 类型     | 默认值 |
+| -------- | ------------------------------------------------------------- | -------- | ------ |
+| Data     | 与DataB64二选一，待签名原文                                   | `String` | --     |
+| DataB64  | 与Data二选一 ， Base64编码的待签名原文，同时存在时使用DataB64 | `String` | --     |
+| SignData | 必填，Base64编码的签名值                                      | `String` | --     |
+| CertB64  | 可选，Base64编码的签名证书                                    | `String` | --     |
+
+### PKCS1哈希签名
+
+PKCS1哈希签名，返回签名值
+
+#### 接口名称
+
+pkcs1HashSign
+
+```ts
+type Pkcs1HashSign = (params: {
+  DataB64: string;
+  HashAlg?: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性    | 说明                                   | 类型                       | 默认值 |
+| ------- | -------------------------------------- | -------------------------- | ------ |
+| DataB64 | 必填，Base64编码带签名原文的预处理哈希 | `String`                   | --     |
+| HashAlg | 可选，哈希算法                         | `sm3` \| `sha1`\| `sha256` | `sm3`  |
+
+### PKCS1哈希验签
+
+PKCS1哈希验签，返回验签结果，`true`为验签成功，验签失败时返回`Promise.reject`
+
+#### 接口名称
+
+pkcs1Base64VerifySignature
+
+#### 函数签名
+
+```ts
+type Pkcs1Base64VerifySignature = (params: {
+  DataB64: string;
+  SignData: string;
+  CertB64?: string;
+  HashAlg?: string;
+}) => Promise<boolean>;
+```
+
+#### 参数说明
+
+| 属性     | 说明                                     | 类型                       | 默认值 |
+| -------- | ---------------------------------------- | -------------------------- | ------ |
+| DataB64  | 必填，Base64编码的待签名的原文预处理哈希 | `String`                   | --     |
+| SignData | 必填，签名值                             | `String`                   | --     |
+| CertB64  | 可选，Base64编码的签名证书               | `String`                   | --     |
+| HashAlg  | 可选，哈希算法                           | `sm3` \| `sha1`\| `sha256` | `sm3`  |
+
+### PKCS7签名
+
+PKCS7签名，返回签名值
+
+#### 接口名称
+
+pkcs7Sign
+
+#### 函数签名
+
+```ts
+type Pkcs7Sign = (params: {
+  Data?: string;
+  DataB64?: string;
+  IsDetached: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性       | 说明                                                          | 类型       | 默认值 |
+| ---------- | ------------------------------------------------------------- | ---------- | ------ |
+| Data       | 与DataB64二选一，待签名原文                                   | `String`   | --     |
+| DataB64    | 与Data二选一 ， Base64编码的待签名原文，同时存在时使用DataB64 | `String`   | --     |
+| IsDetached | 必填，Y为detach，N为attach，attach模式签名值带了原文          | `Y` \| `N` | --     |
+
+### PKCS7验签
+
+PKCS7验签，返回验签结果，`true`为验签成功，验签失败时返回`Promise.reject`
+
+#### 接口名称
+
+pkcs7VerifySignature
+
+#### 函数签名
+
+```ts
+type Pkcs7VerifySignature = (params: {
+  Data?: string;
+  DataB64?: string;
+  SignData: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性     | 说明                                                          | 类型     | 默认值 |
+| -------- | ------------------------------------------------------------- | -------- | ------ |
+| Data     | 与DataB64二选一，待签名原文                                   | `String` | --     |
+| DataB64  | 与Data二选一 ， Base64编码的待签名原文，同时存在时使用DataB64 | `String` | --     |
+| SignData | 必填，签名值                                                  | `String` | --     |
+
+### base64编码
+
+base64编码，返回base64编码内容
+
+#### 接口名称
+
+base64Encode
+
+#### 函数签名
+
+```ts
+type Base64Encode = (params: { Data: string }) => string;
+```
+
+#### 参数说明
+
+| 属性 | 说明                   | 类型     | 默认值 |
+| ---- | ---------------------- | -------- | ------ |
+| Data | 必填，base64待编码内容 | `String` | --     |
+
+### base64解码
+
+base64解码，返回base64解码内容
+
+#### 接口名称
+
+base64Decode
+
+#### 函数签名
+
+```ts
+type Base64Decode = (params: { DataB64: string }) => string;
+```
+
+#### 参数说明
+
+| 属性    | 说明                   | 类型     | 默认值 |
+| ------- | ---------------------- | -------- | ------ |
+| DataB64 | 必填，base64待解码内容 | `String` | --     |
+
+### SM3哈希
+
+SM3哈希，返回SM3哈希值
+
+#### 接口名称
+
+sm3Hash
+
+#### 函数签名
+
+```ts
+type Sm3Hash = (params: { Data: string }) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性 | 说明                     | 类型     | 默认值 |
+| ---- | ------------------------ | -------- | ------ |
+| Data | 必填，待计算杂凑值的原文 | `String` | --     |
+
+### SM3 B64哈希
+
+SM3 B64哈希
+
+#### 接口名称
+
+sm3HexHash
+
+#### 函数签名
+
+```ts
+type Sm3HexHash = (params: { DataB64: string }) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性    | 说明                           | 类型     | 默认值 |
+| ------- | ------------------------------ | -------- | ------ |
+| DataB64 | 必填，待计算杂凑值的原文base64 | `String` | --     |
+
+### SM3 文件哈希
+
+SM3 文件哈希
+
+#### 接口名称
+
+sm3FileHash
+
+#### 函数签名
+
+```ts
+type Sm3FileHash = (params: { SrcFile: string }) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性    | 说明                                                    | 类型     | 默认值 |
+| ------- | ------------------------------------------------------- | -------- | ------ |
+| SrcFile | 必填，待计算杂凑值的本地文件全路径。建议使用正斜杠（/） | `String` | --     |
+
+### SM3哈希加密
+
+SM3哈希加密
+
+#### 接口名称
+
+sm3HashEncryption
+
+#### 函数签名
+
+```ts
+type Sm3HashEncryption = (params: {
+  Data?: string;
+  DataB64?: string;
+  Key?: string;
+  KeyB64?: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性    | 说明                                                          | 类型     | 默认值 |
+| ------- | ------------------------------------------------------------- | -------- | ------ |
+| Data    | 与DataB64二选一，待加密原文                                   | `String` | --     |
+| DataB64 | 与Data二选一 ， Base64编码的待加密原文，同时存在时使用DataB64 | `String` | --     |
+| Key     | 与KeyB64二选一，密钥                                          | `String` | --     |
+| KeyB64  | 与Key二选一 ， base64编码的密钥，同时存在时使用KeyB64         | `String` | --     |
+
+### PKCS7加密
+
+PKCS7加密，返回加密字符串
+
+#### 接口名称
+
+pkcs7Encryption
+
+#### 函数签名
+
+```ts
+type Pkcs7Encryption = (params: {
+  Data?: string;
+  DataB64?: string;
+  Key: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性        | 说明                                                          | 类型     | 默认值 |
+| ----------- | ------------------------------------------------------------- | -------- | ------ |
+| Data        | 与DataB64二选一，待加密原文                                   | `String` | --     |
+| DataB64     | 与Data二选一 ， Base64编码的待加密原文，同时存在时使用DataB64 | `String` | --     |
+| CertB64List | 必填，加密证书base64，多个以\|连接                            | `String` | --     |
+
+### PKCS7解密
+
+PKCS7解密，返回解密字符串
+
+#### 接口名称
+
+pkcs7Decryption
+
+#### 函数签名
+
+```ts
+type Pkcs7Decryption = (params: {
+  DataB64: string;
+  shouldDecodeBase64?: boolean;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性               | 说明                     | 类型      | 默认值 |
+| ------------------ | ------------------------ | --------- | ------ |
+| DataB64            | 必填，待解密原文         | `String`  | --     |
+| shouldDecodeBase64 | 可选，是否需要base64解码 | `Boolean` | --     |
+
+### 非对称加密
+
+非对称加密，返回加密字符串
+
+#### 接口名称
+
+asymmetricDecryption
+
+#### 函数签名
+
+```ts
+type AsymmetricDecryption = (params: { Data: string }) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性    | 说明              | 类型     | 默认值 |
+| ------- | ----------------- | -------- | ------ |
+| Data    | 必填，待解密原文  | `String` | --     |
+| CertB64 | 可选，加密证书B64 | `String` | --     |
+
+### 非对称解密
+
+非对称解密，返回解密字符串
+
+#### 接口名称
+
+asymmetricDecryption
+
+#### 函数签名
+
+```ts
+type AsymmetricDecryption = (params: { Data: string }) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性 | 说明             | 类型     | 默认值 |
+| ---- | ---------------- | -------- | ------ |
+| Data | 必填，待解密原文 | `String` | --     |
+
+### SM4对称加密
+
+SM4对称加密，返回加密字符串，加密密钥
+
+#### 接口名称
+
+sm4Encryption
+
+#### 函数签名
+
+```ts
+type Sm4Encryption = (params: {
+  Data: string;
+}) => Promise<{ Data: string; KeyB64: string }>;
+```
+
+#### 参数说明
+
+| 属性 | 说明             | 类型     | 默认值 |
+| ---- | ---------------- | -------- | ------ |
+| Data | 必填，待加密原文 | `String` | --     |
+
+#### 返回参数说明
+
+| 属性   | 说明           | 类型     |
+| ------ | -------------- | -------- |
+| Data   | 加密密文       | `String` |
+| KeyB64 | Base64对称密钥 | `String` |
+
+### SM4对称解密
+
+SM4对称解密，返回解密字符串
+
+#### 接口名称
+
+sm4Decryption
+
+#### 函数签名
+
+```ts
+type Sm4Decryption = (params: {
+  Data: string;
+  KeyB64: string;
+}) => Promise<string>;
+```
+
+#### 参数说明
+
+| 属性   | 说明                 | 类型     | 默认值 |
+| ------ | -------------------- | -------- | ------ |
+| Data   | 必填，待解密原文     | `String` | --     |
+| KeyB64 | 必填，Base64对称密钥 | `String` | --     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gws-client",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "module": "dist/index.es.js",
   "main": "dist/index.cjs.js",
@@ -16,7 +16,8 @@
   },
   "author": "gzca",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"