diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index 6f21174e..e2406b01 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -16,6 +16,14 @@ export const sidebarZh: SidebarConfig = { '/rules/entire/kitx-encryption-ring.md', ] }, + { + text: '网络', + collapsible: true, + children: [ + '/rules/network/README.md', + '/rules/network/kitx-web-command.md', + ] + }, '/rules/installer.md', { text: '加载器', diff --git a/docs/client/guide/getting-started.md b/docs/client/guide/getting-started.md index 11ac5a01..e1df303e 100644 --- a/docs/client/guide/getting-started.md +++ b/docs/client/guide/getting-started.md @@ -52,7 +52,7 @@ git submodule init 其中 `` 为开发类型, 可选值为: -`list` | `dashboard` | `mobile` | `loader` | `plugin` | `installer` | `reference` +`list` | `dashboard` | `mobile` | `loader` | `plugin` | `installer` | `reference` | `all` 若您想要开发 KitX PC 端客户端, 请 start `dashboard` 和 `reference` @@ -66,16 +66,16 @@ git submodule init 您也可以随时 start `list` 来列出可供选择的开发类型 +或者 start `all` 来更新所有子模块 + --- ## 构建项目 ### 编译前准备 -1. 您需要安装 dotnet 6 SDK, 请前往 [dotnet 官网](https://dotnet.microsoft.com/download/dotnet/6.0) 下载并安装 - 安装成功的标志是: 成功运行命令 `dotnet --list-sdks` 并且列出了 dotnet 6 SDK 的版本号 -2. 您需要安装 dotnet 7 SDK, 请前往 [dotnet 官网](https://dotnet.microsoft.com/download/dotnet/7.0) 下载并安装 - 安装是否成功的检测方法同上, 部分项目已经升级至 dotnet 7, 其余项目仍然使用 dotnet 6 +1. 您需要安装 dotnet 7 SDK, 请前往 [dotnet 官网](https://dotnet.microsoft.com/download/dotnet/7.0) 下载并安装 + 安装成功的标志是: 成功运行命令 `dotnet --list-sdks` 并且列出了 dotnet 7 SDK 的版本号 --- diff --git a/docs/guide/README.md b/docs/guide/README.md index 04b3b265..a1f5f222 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -10,7 +10,7 @@ KitX Project 旨在打造一个跨平台万物互联可扩展的工具箱, 使 # 项目组成 -面向最终用户 +## 面向最终用户 - KitX 仪表盘 ([KitX Dashboard](https://github.com/Crequency/KitX-Dashboard)) 是 KitX Project 的核心, 也是 KitX Project 在桌面端的具体实现. @@ -26,15 +26,15 @@ KitX Project 旨在打造一个跨平台万物互联可扩展的工具箱, 使 移动端项目基于 `Flutter` 实现跨平台图形界面, 使用 `Dart` 作为主要开发语言. -- KitX 安装包 ([KitX Installer](https://github.com/Crequency/KitX-Installer)) 包含多个项目, 主要实现 KitX 仪表盘 不同平台的安装包 +- KitX 安装包 ([KitX Installer](https://github.com/Crequency/KitX-Installer)) 主要包含 KitX 仪表盘 针对不同平台的安装包实现 -面向开发者 + 安装包项目使用 `Rust` 语言编写, 使用 `Egui` 作为图形界面库. -- KitX SDK 是 KitX 插件开发者会用到的一系列开发工具 +## 面向开发者 - 包含插件打包工具, 插件解包工具, 插件调试工具, 插件模板生成器, 插件通讯诊断器等 +- [KitX SDK](https://github.com/Crequency/KitX-SDK) 是 KitX 插件开发者会用到的一系列开发工具 - KitX SDK 并不是具体的项目, 它由多个项目组成, 主要部分是 [KitX Tools](https://github.com/Crequency/KitX-Tools). + 包含插件打包工具, 插件解包工具, 插件调试工具, 插件模板生成器, 插件通讯诊断器等 - [KitX Script](https://github.com/Crequency/KitX-Script) 是专用于 `KitX 任务计划` 流程控制的脚本语言. diff --git a/docs/rules/entire/kitx-encryption-ring.md b/docs/rules/entire/kitx-encryption-ring.md index 7e7eacf4..784f3b05 100644 --- a/docs/rules/entire/kitx-encryption-ring.md +++ b/docs/rules/entire/kitx-encryption-ring.md @@ -6,4 +6,47 @@ description: 本页有关 KitX 加密环的运作原理 # KitX 加密环运作原理 +1. 每个客户端在启用 "加密环" 时生成一对 RSA 密钥对存储在本地 +2. 用户启用 "加密环" 后, 可手动添加要加密通信的目标设备 (目标设备也需启用 "加密环") +3. 若目标设备启用了 "加密环", 则开始密钥交换过程 +4. 若目标设备未启用 "加密环", 则弹窗提示用户目标设备未启用 "加密环" + +## 密钥交换过程 + +```mermaid +--- +title: 密钥交换过程 +--- +flowchart TB + subgraph Client.A + K(收到 Client.B 的密钥) --> |AES| L(用临时密码解密密钥) + L --> M(将 Client.B 的密钥存储在本地) + end + + subgraph Client.B + D(收到密钥交换请求) --> E(询问用户临时密码) + E --> F(验证解密是否成功) + F --> |否| G(提示用户密码错误) + G --> E + F --> |是| H(存储 Client.A 的密钥及相关信息) + H --> |AES| I(用相同的临时密码加密 Client.B 的密钥) + I --> J(加密后的密钥发回 Client.A) + J --> |KWC| K + end + + subgraph Client.A + A(生成临时六位密码) --> |AES| B(用临时密码加密密钥) + B --> |KWC| D + B --> C(将临时密码显示在屏幕中
提示用户在目标设备上输入这串密码) + end +``` + +## 加密通信 + +对于已交换密钥的设备, 在 KWC 报文中设置 `IsEncrypted` 字段为 `True` 即可标记该报文启用了加密通信 +并需随报文附带 `EncryptionKeyId` 字段以便目标设备能使用正确的密钥解密报文 + +`EncryptionKeyId` 由密钥提供方提供, 且在密钥交换过程中已经交换, 其值为密钥的 SHA256 哈希值 + + diff --git a/docs/rules/network/README.md b/docs/rules/network/README.md new file mode 100644 index 00000000..bddd5a7f --- /dev/null +++ b/docs/rules/network/README.md @@ -0,0 +1,8 @@ +--- +lang: zh-CN +title: 网络部分 +description: 这篇文章是 KitX Project 网络部分的总览 +--- + +building ... + diff --git a/docs/rules/network/kitx-web-command.md b/docs/rules/network/kitx-web-command.md new file mode 100644 index 00000000..5567004b --- /dev/null +++ b/docs/rules/network/kitx-web-command.md @@ -0,0 +1,36 @@ +--- +lang: zh-CN +title: KWC 网络通讯协议 +description: 这篇文章是有关 KWC 网络通讯协议 +--- + +# 什么是 KWC + +KWC 是 KitX Web Command 的缩写, 即 `KitX 网络命令系统`, 是一种通讯协议, 适用于 KitX 网络中的通讯. + +# KWC 协议 + +KWC 是一种通讯规范, 规范了 KitX 网络中的通讯格式, 使得不同的设备可以通过 KWC 协议进行通讯. +本质是 LBPT 序列化/反序列化文本, 但使用 KitX 网络特定属性. + +## KWC 格式 (属性列表) + +KWC 语法完全符合 LBPT 格式, 但使用特定的属性来传递仅适用于 KitX 网络的信息. +以下列出 KWC 协议中的属性: + +| 属性名 | 类型 | 描述 | 默认值 | +|------------------|-----------------|-----------------------------------|-----------| +| Type | String | 消息类型 | "Command" | +| Version | String | 协议版本 | | +| Target | `DeviceLocator` | 目标设备定位器 | | +| EncryptionMethod | String | 加密方法 | "AES" | +| EncryptionKeyId | String | 加密密钥 ID | | +| IsEncrypted | Boolean | `Content` 属性是否加密 | False | +| IsCompressed | Boolean | `Content` 属性是否压缩 | False | +| Content | String | 内容 (一定为 LBPT 中的末尾多行属性) | | + +- [`DeviceLocator`](https://github.com/Crequency/KitX-Rules/blob/main/KitX.Web.Rules/DeviceLocator.cs) 设备定位器, 用于定位设备, 具体成员列表参见外部链接. + + + +