diff --git a/docs/zh/server/security/secdetector/_toc.yaml b/docs/zh/server/security/secdetector/_toc.yaml index 2f9e2b381ce9e9f650a4954173b798b6f3145c83..64e43c12951ab8b1395a4d36bae90819ef64985d 100644 --- a/docs/zh/server/security/secdetector/_toc.yaml +++ b/docs/zh/server/security/secdetector/_toc.yaml @@ -2,11 +2,6 @@ label: secDetector使用指南 isManual: true description: secDetector是OS内构入侵检测系统，为关键信息基础设施提供入侵检测及响应能力 sections: - - label: 认识secDetector - href: ./introduction_to_secdetector.md - - label: 安装与部署 - href: ./install_secdetector.md - - label: 接口参考 - href: ./api_reference.md - - label: 使用secDetector - href: ./using_secdetector.md + - href: + upstream: https://gitee.com/openeuler/secDetector/blob/master/docs/zh/2403_LTS_SP2/_toc.yaml + path: ./secdetector diff --git a/docs/zh/server/security/secdetector/api_reference.md b/docs/zh/server/security/secdetector/api_reference.md deleted file mode 100644 index 1235f7bf151a0db3b6cbb62f8495185df34c9a58..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secdetector/api_reference.md +++ /dev/null @@ -1,83 +0,0 @@ -# 接口说明 - -secDetector操作系统内构入侵检测系统对外提供SDK，这里给出用户开发应用程序所需的接口。SDK的接口设计非常简单，一共只有三个接口，两个头文件。 - -头文件： - -- secDetector/secDetector_sdk.h：包含接口定义 - -- secDetector/secDetector_topic.h：包含一些调用接口所需使用的预定义宏，如可选择性订阅的功能主题编号 - - -## secSub - -订阅 topic 接口 - -**功能**： - -订阅接口，应用程序通过输入不同 topic id，可以选择订阅不同的功能主题，比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题，多个探针的 topic id 可以以位图的形式进行组合。 - ->![](./public_sys-resources/icon-note.gif) **说明：** ->由于一次订阅产生一个reader即信息读取器，所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容，可以退订之后再重新订阅。 - -**函数声明：** - -```c -void *secSub(const int topic); -``` - -**参数：** - -- topic：入参，需要订阅的主题集合 - -**返回值：** - -- NULL：订阅失败 -- NOT NULL：读取订阅主题相关信息的GRPC reader读取器 - -## secUnsub - -退订 topic 接口 - -**功能**： - -退订接口，应用程序通过输入订阅成功后获得的reader，完成主题的退订。退订后应用程序便不会收到相应主题的信息。系统中某主题如果没有任何应用程序订阅，则不会被执行。 - -**函数声明：** - -```c -void secUnsub(void *reader); -``` - -**参数：** - -- reader：入参，需要退订的信息读取器 - -**返回值：** - -- 无 - - -## secReadFrom - -已订阅主题的消息读取接口 - -**功能**： - -使用订阅接口对某些主题的订阅成功后，执行退订操作之前，可使用本接口接受 secDetector 发送的已订阅主题的消息。本接口是阻塞式的。应用程序建议使用独立的线程循环调用。当已订阅主题有消息时候，本函数才会被恢复执行。 - -**函数声明：** - -```c -void secReadFrom(void *reader, char *data, int data_len); -``` - -**参数：** - -- reader：入参，主题订阅成功后得到的消息读取器 -- data：出参，消息缓冲区，由应用程序提供的一段内存 -- data_len：入参，消息缓冲区的尺寸 - -**返回值：** - -- 无 diff --git a/docs/zh/server/security/secdetector/install_secdetector.md b/docs/zh/server/security/secdetector/install_secdetector.md deleted file mode 100644 index e4acb8312d5e67bf1b795b22b9a9aa05343769b3..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secdetector/install_secdetector.md +++ /dev/null @@ -1,104 +0,0 @@ -# 安装 secDetector - -## 软硬件要求 - -### 硬件要求 - -* 当前仅支持 x86_64、aarch64 架构处理器。 -* secDetector磁盘使用需求：配额1GB及以上。 -* secDetector内存使用需求：配额100MB及以上。 - -### 环境准备 - -安装 openEuler 系统，安装方法参考《[安装指南](../../installation_upgrade/installation/installation-on-servers.md)》。 - -## 安装secDetector - -1. 配置openEuler yum源：openEuler 发布版本上已默认配置完成yum源，无需额外操作。特殊情况下请参考openEuler官方文档配置在线yum源或通过ISO挂载配置本地yum源。 - -2. 安装secDetector。 - - ```shell - #安装secDetector - sudo yum install secDetector - ``` - -> ![](./public_sys-resources/icon-note.gif)说明： -> -> 安装secDetector后在指定目录下可获得部署secDetector所需的相关文件： - -```shell -#secDetector的kerneldriver的核心框架 -/lib/modules/%{kernel_version}/extra/secDetector/secDetector_core.ko - -#secDetector的kerneldriver的功能组件 -/lib/modules/%{kernel_version}/extra/secDetector/secDetector_xxx.ko - -#secDetector的守护者进程文件 -/usr/bin/secDetectord - -#secDetector的SDK库文件 -/usr/lib64/secDetector/libsecDetectorsdk.so -/usr/include/secDetector/secDetector_sdk.h -/usr/include/secDetector/secDetector_topic.h -``` - -## 部署 secDetector - -secDetector的主体secDetectord是以系统服务的形式部署在系统中的，前台业务系统可以通过集成SDK来与之通信。由于secDetector的部分能力必须构建在内核之中，因此secDetectord的功能全集还依赖于其后台驱动的部署。 - -### 部署 kernel driver - -1. 插入 kernel driver 的基础框架：secDetector_core.ko 是 kernel driver 的基础框架，要优先于其他内核模块进行部署。找到安装后的 secDetector_core.ko 目录，将其插入内核。参考命令如下： - - ```shell - sudo insmod secDetector_core.ko - ``` - - secDetector_core 支持一个命令行参数ringbuf_size。用户可以通过指定该参数的值来控制 kernel driver 与 用户态secDetectord之间数据通道的缓存空间尺寸。该参数可以被指定为4~1024中的一个整数，单位是MB。默认值是4，必须为2的幂。参考命令如下： - - ``` - sudo insmod secDetector_core.ko ringbuf_size=128 - ``` - - -2. 插入 kernel driver 的功能模块：secDetector的 kernel driver 采用模块化部署方式。用户可以选择基于框架部署满足需要的功能模块，也可以选择部署全部模块。参考命令如下： - - ```shell - sudo insmod secDetector_kmodule_baseline.ko - - sudo insmod secDetector_memory_corruption.ko - - sudo insmod secDetector_program_action.ko - - sudo insmod secDetector_xxx.ko - ``` - - - secDetector_kmodule_baseline.ko 提供了内核模块列表检测的能力，属于内存修改类探针； - - secDetector_memory_corruption.ko 提供了内存修改检测的能力，属于内存修改类探针； - - secDetector_program_action.ko 提供了程序行为检测的能力，属于程序行为类探针。 - -### 部署 usr driver 和 observer_agent - -当前用户态驱动 usr driver 和服务 observer_agent 已经都被集成到secDetectord中，参考命令如下： - -```shell -sudo ./secDetectord & -``` - -usr driver当前包含了文件操作类探针和进程管理类探针的能力。 - -secDetectord支持如下一些配置选项： - -``` -用法：secDetectord [选项] -secDetectord 默认会在后台运行，从探针中取得数据并转发给订阅者。 -选项： - -d 进入调试模式，进入前台运行，并且在控制台打印探针数据。 - -s 配置eBPF缓冲区大小，单位为Mb，默认为4； size可选范围为4~1024，且必须为2的幂次方。当前拥有2个独立的缓冲区。 - -t 支持配置订阅的事件，默认为所有事件。topic 是位图格式。例如 -t 0x60 同时订阅进程创建和进程退出事件。详细请查阅 include/secDetector_topic.h。 -``` - -### 部署SDK - -SDK的库文件默认已经被部署到系统库目录中，用户需要在自己的程序中引用SDK的头文件即可使用。 \ No newline at end of file diff --git a/docs/zh/server/security/secdetector/introduction_to_secdetector.md b/docs/zh/server/security/secdetector/introduction_to_secdetector.md deleted file mode 100644 index d9af9b9ecd03612f3f2024727cea62940a8fefa3..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secdetector/introduction_to_secdetector.md +++ /dev/null @@ -1,98 +0,0 @@ -# 认识secDetector - -## 简介 - -secDetector 是专为OS设计的内构入侵检测系统，旨在为关键信息基础设施提供入侵检测及响应能力，为第三方安全工具减少开发成本同时增强检测和响应能力。secDetector 基于ATT&CK攻击模式库建模提供更为丰富的安全事件原语，并且可以提供实时阻断和灵活调整的响应能力。 - -secDetector 作为一套灵活的OS内构入侵检测系统，有三种使用模式： - -1. 直接被系统用户开启用作一些基础异常事件的告警和处置。 -2. 被安全态势感知服务集成，补齐系统信息采集缺陷，用于APT等复杂的安全威胁分析和重点事件布控实时阻断。 -3. 由安全从业人员或安全感知服务提供商二次开发，基于可拓展框架构建精确、高效、及时的入侵检测与响应能力。 - -## 软件架构 - -``` -||==APP===================================================================|| -|| || -|| ---------------------------- || -|| | SDK | || -|| ---------------------------- || -|| /^\ || -||==================================|=====================================|| - | - | - | -||==OBSERVER========================|=====================================|| -|| | || -|| ---------------------------- || -|| | service | || -|| ---------------------------- || -|| /^\ || -||==================================|=====================================|| - | -||==DRIVER================================================================|| -|| || -|| ---------------------------- || -|| | 8 types of cases | || -|| ---------------------------- || -|| || -||------------------------------------------------------------------------|| -|| core || -|| ------------- ---------------- ---------------- ----------------- || -|| | hook unit | | collect unit | | analyze unit | | response unit | || -|| ------------- ---------------- ---------------- ----------------- || -|| || -||========================================================================|| -``` - -secDetector在架构上分为四个部分：SDK、service、检测特性集合cases、检测框架core。 - -- SDK - - SDK是以一个用户态动态链接库lib的形态承载，被部署到需要使用secDetector入侵检测系统的安全感知业务中。SDK用于和secDetector入侵检测系统的service通讯，完成所需的工作（例如订阅，去订阅，读取现有消息等功能）。secDetector提供的异常信息被定义成不同的case，安全感知业务可以根据自身需求订阅。 - -- service - - service是以一个用户态服务应用的形态承载，向上管理、维护安全感知业务的case订阅信息，向下维护case的运行情况。框架core和检测特性集合case采集到的信息由service统一收集，按需转发给不同的安全感知业务。安全感知业务对于底层检测特性集合case和框架core的配置、管理的需求也由service进行统一的管理和转发。不同的安全感知业务可能会需求同样的case，service会统计出所有安全感知业务需求case的并集，向下层注册。 - -- 特性集合cases - - 检测特性集合cases是一系列异常检测探针，根据异常信息的不同会有不同的形态，比如内核异常信息检测的每个探针会以内核模块ko的形态承载。一个case代表一个探针，一个探针往往是一类异常信息或者一类异常事件的信息。比如进程类探针会关注所有进程的创建、退出、属性修改等事件信息，内存修改类探针会收集内核模块列表和安全开关等信息。因此一个探针可能会包含对多个事件的监控，而这些对不同事件的监控逻辑可能无法部署在同一个执行流当中。我们使用工作流（workflow）的概念表示一个探针在同一个执行流中的工作，一个探针可以包含一个或者多个工作流。比如对于进程探针而言，进程创建检测和进程属性修改检测就是不同的工作流。 - -- 框架core - - 检测框架core是每一个case依赖的基础框架，提供case的管理和workflow所需的通用的基础功能单元。内核异常信息检测框架会以内核模块ko的形态承载。一个检测特性case可以将自己注册到框架中，或者从框架中去注册。框架还可以提供特定的交互接口以满足外部的动态请求。一个workflow被定义为有四类功能单元组成：事件发生器、信息采集器、事件分析器、响应单元。 - -特性集合cases和框架core合起来被称为driver。driver驱动提供了secDetector功能的最底层的系统级实现。 - -driver分为两类，kerneldriver 和 usrdriver。顾名思义，kerneldriver是部署在内核态中的，以内核模块的形式承载。usrdriver是部署在用户态中的，直接被部署为service中的一个模块。从逻辑上usrdriver是在service之下的，但是在运行中，为了降低通信成本，usrdriver被直接集成在service程序中。 - -## 能力特性 - -### 检测能力 - -| 特性 | 状态 | 发布版本 | -| ------------------------------ | ------ | ------------------------------------------------------------ | -| 检测框架 | 已实现 | 统一灵活可拓展高效的检测框架，支持不同类型的触发、收集、分析、响应单元 | -| 进程管理类探针 | 已实现 | 监控进程创建、退出、元数据修改等事件 | -| 文件操作类探针 | 已实现 | 监控文件创建、删除、读写、属性修改等事件 | -| 程序行为类探针（API调用） | 已实现 | 监控匿名管道创建、命令执行、ptrace系统调用等关键程序行为 | -| 内存修改类探针（内核关键数据） | 已实现 | 监控内核模块列表，硬件安全功能开关等内核关键数据 | - -### 响应能力 - -| 特性 | 状态 | 说明 | -| -------- | ------ | -------------------------------------------------- | -| 响应框架 | 已实现 | 统一的灵活可拓展的响应框架，支持不同类型的响应单元 | -| 告警上报 | 已实现 | 提供异常信息上报能力的响应单元 | - -### 服务能力 - -| 特性 | 状态 | 说明 | -| -------- | ------ | ------------------------------------------------------------ | -| 通信框架 | 已实现 | 应用程序使用gRPC和service进行通信。功能被封装在SDK的动态库中。 | -| 订阅管理 | 已实现 | 应用程序可以一次订阅，长期使用secDetector获取信息。secDetector会对订阅的应用程序进行管理，分发对应的被订阅主题的信息。 | -| 配置下发 | 已实现 | 服务可以通过参数对于特定的检测、阻断特性进行配置，从而实现过滤、调整等功能。目前未对应用程序开放。 | -| 即时检测 | 已实现 | secDetector提供的信息是实时的，准确的，一手的。 | - diff --git a/docs/zh/server/security/secdetector/public_sys-resources/icon-note.gif b/docs/zh/server/security/secdetector/public_sys-resources/icon-note.gif deleted file mode 100644 index 6314297e45c1de184204098efd4814d6dc8b1cda..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secdetector/public_sys-resources/icon-note.gif and /dev/null differ diff --git a/docs/zh/server/security/secdetector/secdetector.md b/docs/zh/server/security/secdetector/secdetector.md deleted file mode 100644 index e20d3fc09effae2c13b7125bad2a0ba932716600..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secdetector/secdetector.md +++ /dev/null @@ -1,5 +0,0 @@ -# secDetector 使用指南 - -本文档介绍 openEuler 操作系统内构入侵检测系统 secDetector 的架构、特性、安装、开发指导、落地应用场景等，帮助用户快速了解并使用 secDetector。 - -本文档适用于使用 openEuler 系统并希望了解和使用 secDetector 的社区开发者、开源爱好者以及相关合作伙伴。使用人员需要具备基本的Linux操作系统知识。 diff --git a/docs/zh/server/security/secdetector/using_secdetector.md b/docs/zh/server/security/secdetector/using_secdetector.md deleted file mode 100644 index e9e19cf22add983ed8fedd86fe9d0ff4089bda8a..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secdetector/using_secdetector.md +++ /dev/null @@ -1,46 +0,0 @@ -# 使用 secDetector - -secDetector 提供了SDK，一个so库，用户可以在自己的应用程序中集成该动态链接库从而通过简单的接口使用secDetector。本章介绍其使用方法。 - -## 基本用法 - -用户按照指南《[安装secDetector](./install_secdetector.md)》安装完secDetector之后，libsecDetectorsdk.so、secDetector_sdk.h、secDetector_topic.h就已经被部署到系统用户库默认路径中。 - -1. 使用 C 或 C++ 开发的应用程序确保include路径包含后，可以首先在程序中引用这两个头文件。 - - ``` - #include - #include - ``` - -2. 参考指南《[接口参考](./api_reference.md)》调用SDK提供的接口访问secDetector。 - - 1. 首先调用订阅接口secSub，订阅所需的主题。 - 2. 然后在独立线程中调用消息读取接口secReadFrom阻塞式的读取被订阅主题产生的信息。 - 3. 最后当不需要使用secDetector时，调用退订接口secUnsub。退订时请严格使用订阅时的返回值。 - -## 代码示例 - -可以参考secDetector代码仓上的示例代码，由python语言编写。 - -1. 可以在如下链接中查看示例代码 - - [examples/python · openEuler/secDetector (gitee.com)](https://gitee.com/openeuler/secDetector/tree/master/examples/python) - -2. 也可以下载后参考 - -```shell -git clone https://gitee.com/openeuler/secDetector.git -``` - -## 规格与约束 - -1. 部分功能（如内存修改探针-安全开关）依赖硬件体系结构，因此在不同指令集架构上的表现并不相同。 -2. 从内核到用户态传输数据缓存空间为探针共享，缓冲区满会丢弃新采集的事件信息。缓存空间可配置范围为4~1024 MB, 必须为2的幂。 -3. 服务进程secDetectord支持root用户运行，不支持多实例，非第一个运行的程序会退出。 -4. 用户订阅连接数限制为5个。 -5. 用户订阅后，读取消息时需要为消息读取接口提供一块缓冲区，超过缓冲区长度的消息将被截断。建议缓冲区长度不低于4096。 -6. 对于文件名、节点名之类的描述字符串都有一定的长度限制，过长可能会被截断。 -7. 应用程序单进程内不支持并行多连接 secDetectord 接收消息。只能一次订阅，单连接接受消息。去订阅后才能重新订阅。 -8. secDetectord 进程应当等待所有应用程序的连接中断即完全退订所有主题后，才可以关闭退出。 -9. 部分功能（如内存修改探针-安全开关）基于当前CPU状态。因此检测的基本功能是可以检测到当前CPU上的状态变化，其他CPU上的状态变化如果未能及时同步到当前CPU，则不会被检测到。 \ No newline at end of file diff --git a/docs/zh/server/security/secgear/_toc.yaml b/docs/zh/server/security/secgear/_toc.yaml index 93f1de5044884ef84dcabda2b4eb8b92f520c344..e0781a30dc8b88002aad4b52c291ae0add100715 100644 --- a/docs/zh/server/security/secgear/_toc.yaml +++ b/docs/zh/server/security/secgear/_toc.yaml @@ -2,15 +2,7 @@ label: secGear开发指南 isManual: true description: 使用 secGear 统一机密计算编程框架开发应用程序，保障云端数据运行时的安全性 sections: - - label: 认识secGear - href: ./introduction-to-secGear.md - - label: 安装与部署 - href: ./secgear-installation.md - - label: 接口说明 - href: ./api-reference.md - - label: 开发secGear应用程序 - href: ./developer-guide.md - - label: 使用secGear工具 - href: ./using-secgear-tools.md - - label: 应用场景 - href: ./application-scenarios.md + - href: + upstream: https://gitee.com/openeuler/secGear/blob/master/docs/zh/2403_LTS_SP2/_toc.yaml + path: ./secgear + diff --git a/docs/zh/server/security/secgear/api-reference.md b/docs/zh/server/security/secgear/api-reference.md deleted file mode 100644 index c774731a8cd56575f75df6e156d1aea90cfeba9c..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/api-reference.md +++ /dev/null @@ -1,331 +0,0 @@ -# 接口说明 - -secGear 机密计算统一编程框架分为安全侧和非安全侧，这里给出用户开发应用程序所需的接口。除这些接口外，安全侧还继承了 ARM TrustZone 和 Intel SGX 的开源 POSIC 接口。 - -## cc_enclave_create - -创建 enclave 接口 - -**功能**： - -初始化接口，函数根据不同 type，调用不同的 TEE 创建函数，完成不同 TEE 方案关于 enclave 上下文初始化，由非安全侧调用 - ->![](./public_sys-resources/icon-note.gif) **说明：** ->由于 Intel SGX 限制，多线程并发调用 cc_enclave_create 时存在内存映射的竞争关系，会导致创建 enclave 概率性失败。所以编码时要避免线程并发调用 cc_enclave_create。 - -**函数声明：** - -cc_enclave_result_t cc_enclave_create(const char* path, enclave_type_t type, uint32_t version,uint32_t flags,const enclave_features_t* features,uint32_t features_count, - cc_enclave_t ** enclave); - -**参数：** - -- Path：入参，要加载的 enclave 路径 -- Type：入参，用来指定 TEE 解决方案， 如 SGX_ENCLAVE_TYPE、GP_ENCLAVE_TYPE、AUTO_ENCLAVE_TYPE -- version：入参，指定的 enclave engine 的版本，目前只有一个版本，取值为 0。 -- Flags：入参，标志位，说明这个 enclave 运行状态，例如调试状态 SECGEAR_DEBUG_FLAG、模拟状态 SECGEAR_SIMULATE_FLAG（目前不支持） -- features：入参，用于设置一些关于 enclave 支持的特性，例如 SGX 的 PCL、 switchless 等。目前不支持，请设置为 NULL -- features_count：入参，入参 features 特性结构体的数量。目前不支持，请设置为 0 -- enclave：出参，创建的 enclave 上下文 - -**返回值：** - -- CE_SUCCESS：认证信息验证成功 -- CE_ERROR_INVALID_PARAMETER：输入参数有误 -- CE_ERROR_OUT_OF_MEMORY：无可用内存 -- CC_FAIL：通用错误 -- CC_ERROR_UNEXPECTED：不可预期错误 -- CC_ERROR_ENCLAVE_MAXIMUM：单个 app 创建的 enclave 数量达到最 -- CC_ERROR_INVALID_PATH：安全二进制路径无效 -- CC_ERROR_NO_FIND_REGFUNC：enclave 引擎搜索失败 - -## cc_enclave_destroy - -销毁 enclave 接口 - -**功能**： - -调用不同 TEE 的退出函数，释放已经创建的 enclave 实体，由非安全侧调用 - -**函数声明：** - -cc_enclave_result_t cc_enclave_destroy (cc_enclave_t ** enclave)； - -**参数：** - -- enclave：入参，已经创建 enclave 的上下文 - -**返回值：** - -- CE_SUCCESS：认证信息验证成功 -- CE_ERROR_INVALID_PARAMETER：输入参数有误 -- CE_ERROR_OUT_OF_MEMORY：无可用内存 -- CC_ERROR_NO_FIND_UNREGFUNC：enclave引擎搜索失败 -- CC_FAIL：通用错误 -- CC_ERROR_UNEXPECTED：不可预期错误 - -## cc_malloc_shared_memory - -创建共享内存 - -**功能**： - -开启switchless特性后，创建安全环境与非安全环境可同时访问的共享内存，由非安全侧调用 - -**函数声明：** - -void *cc_malloc_shared_memory(cc_enclave_t *enclave, size_t size); - -**参数：** - -- enclave：入参，安全环境上下文句柄。因不同平台共享内存模型不同，同时为了保持接口跨平台一致性，该参数仅在ARM平台被使用，SGX平台该入参会被忽略 -- size：入参，共享内存大小 - -**返回值：** - -- NULL：共享内存申请失败 -- 其他：为创建的共享内存的首地址 - -## cc_free_shared_memory - -释放共享内存 - -**功能**： - -开启switchless特性后，释放共享内存，由非安全侧调用 - -**函数声明：** - -cc_enclave_result_t cc_free_shared_memory(cc_enclave_t *enclave, void *ptr); - -**参数：** - -- enclave：入参，安全环境上下文句柄。因不同平台共享内存模型不同，同时为了保持接口跨平台一致性，该参数仅在ARM平台被使用（该参数必须与调用cc_malloc_shared_memory接口时传入的enclave保持一致），SGX平台该入参会被忽略 -- ptr：入参，cc_malloc_shared_memory接口返回的共享内存地址 - -**返回值：** - -- CC_ERROR_BAD_PARAMETERS：入参非法 -- CC_ERROR_INVALID_HANDLE：无效enclave或者传入的enclave与ptr所对应的enclave不匹配（仅在ARM平台生效，SGX平台会忽略enclave，故不会对enclave进行检查） -- CC_ERROR_NOT_IMPLEMENTED：该接口未实现 -- CC_ERROR_SHARED_MEMORY_START_ADDR_INVALID：ptr不是cc_malloc_shared_memory接口返回的共享内存地址（仅在ARM平台生效） -- CC_ERROR_OUT_OF_MEMORY：内存不足（仅在ARM平台生效） -- CC_FAIL：一般性错误 -- CC_SUCCESS：成功 - -## cc_enclave_generate_random - -随机数生成 - -**功能**： - -用于在安全侧生成密码安全的随机数 - -**函数声明：** - -cc_enclave_result_t cc_enclave_generate_random(void *buffer, size_t size); - -**参数：** - -- *buffer：入参，生成随机数的缓冲区 -- size：入参，缓冲区的长度 - -**返回值：** - -- CE_OK：认证信息验证成功 -- CE_ERROR_INVALID_PARAMETER：输入参数有误 -- CE_ERROR_OUT_OF_MEMORY：无可用内存 - -## cc_enclave_seal_data - -数据持久化 - -**功能**： - -用于加密 enclave 内部数据，使数据可以在 enclave 外部持久化存储，由安全侧调用 - -**函数声明：** - -cc_enclave_result_t cc_enclave_seal_data(uint8_t *seal_data, uint32_t seal_data_len, - -​ cc_enclave_sealed_data_t *sealed_data, uint32_t sealed_data_len, - -​ uint8_t *additional_text, uint32_t additional_text_len); - -**参数：** - -- seal_data：入参，需要加密的数据 -- seal_data_len：入参，需要加密数据的长度 -- sealed_data：出参，加密后的数据处理句柄 -- sealed_data_len：出参，加密后的密文长度 -- additional_text：入参，加密所需的附加消息 -- additional_text_len：入参，附加消息长度 - -**返回值：** - -- CE_SUCCESS：数据加密成功 -- CE_ERROR_INVALID_PARAMETER：输入参数有误 -- CE_ERROR_OUT_OF_MEMORY：无可用内存 -- CC_ERROR_SHORT_BUFFER：传入的buffer过小 -- CC_ERROR_GENERIC：底层硬件通用错误 - -## cc_enclave_unseal_data - -数据解密 - -**功能**： - -用于解密 enclave 密封过的数据，用于将外部持久化数据重新导回 enclave 环境中，由安全侧调用 - -**函数声明：** - -cc_enclave_result_t cc_enclave_unseal_data(cc_enclave_sealed_data_t *sealed_data, - - uint8_t *decrypted_data, uint32_t *decrypted_data_len, - - uint8_t *additional_text, uint32_t *additional_text_len); - -**参数：** - -- sealed_data：入参，已加密数据的句柄 -- decrypted_data：出参，解密之后的密文数据buffer -- decrypted_data_len：出参，解密后密文长度 -- additional_text：出参，解密后附加消息 -- additional_text_len：出参，解密后附加消息长度 - -**返回值：** - -- CE_SUCCESS：数据解密成功 -- CE_ERROR_INVALID_PARAMETER：输入参数有误 -- CE_ERROR_OUT_OF_MEMORY：无可用内存 -- CC_ERROR_SHORT_BUFFER：传入的buffer过小 -- CC_ERROR_GENERIC：底层硬件通用错误 - -## cc_enclave_get_sealed_data_size - -获取加密数据的大小 - -**功能**： - -用于 sealed_data 数据的大小，主要用于分配解密后的数据空间，由安全侧与非安全侧皆可调用 - -**函数声明：** - -uint32_t cc_enclave_get_sealed_data_size(const uint32_t add_len, const uint32_t seal_data_len); - -**参数：** - -- add_len：入参，附加消息长度 -- sealed_data_len：入参，加密信息的长度 - -**返回值：** - -- UINT32_MAX：参数错误或函数执行错误 -- others：函数执行成功，返回值为当前 sealed_data 结构的大小 - -## cc_enclave_get_encrypted_text_size - -获取加密消息的长度 - -**功能**： - -获取加密数数据中加密消息的长度，由安全侧调用 - -**函数声明：** - -uint32_t cc_enclave_get_encrypted_text_size(const cc_enclave_sealed_data_t *sealed_data); - -**参数：** - -- sealed_data：入参，加密数据的句柄 - -**返回值：** - -- UINT32_MAX：参数错误或函数执行错误 -- others：函数执行成功，返回值为当前 sealed_data 中加密消息的长度 - -## cc_enclave_get_add_text_size - -获取附加消息的长度 - -**功能**： - -获取加密数数据中附加消息的长度，由安全侧调用 - -**函数声明：** - -uint32_t cc_enclave_get_add_text_size(const cc_enclave_sealed_data_t *sealed_data); - -**参数：** - -- sealed_data：入参，加密数据的句柄 - -**返回值：** - -- UINT32_MAX：参数错误或函数执行错误 -- others：函数执行成功，返回值为当前sealed_data中附加消息的长度 - -## cc_enclave_memory_in_enclave - -安全内存检查 - -**功能**： - -用于校验指定长度的内存地址是否都属于安全侧内存，由安全侧调用 - -**函数声明：** - -bool cc_enclave_memory_in_enclave(const void *addr, size_t size); - -**参数：** - -- *addr：入参，指定需要校验的内存地址 -- size：入参，自内存地址起需要校验的长度 - -**返回值：** - -- true：指定区域内存都在安全区范围内 -- false：指定区域的内存有部分或者全部不在安全范围内 - -## cc_enclave_memory_out_enclave - -安全内存检查 - -**功能**： - -用于校验指定长度的内存地址是否都属于非安全侧内存，由安全侧调用 - -**函数声明：** - -bool cc_enclave_memory_out_enclave(const void *addr, size_t size); - -**参数：** - -- *addr：入参，指定需要校验的内存地址 -- size：入参，自内存地址起需要校验的长度 - -**返回值：** - -- true：指定区域内存都在非安全区 -- false：指定区域的内存有部分或者全部在安全区 - -## PrintInfo - -消息打印 - -**功能**： - -用于安全侧日志的打印，本接口输出安全侧用户想打印的信息，输入日志保存在非安全侧/var/log/secgear/secgear.log中 - -**函数声明：** - -void PrintInfo(int level, const char *fmt, ...); - -**参数：** - -- level：入参，日志打印等级，可选项为PRINT_ERROR, PRINT_WARNING, PRINT_STRACE, PRINT_DEBUG -- fmt: 入参，需要输出的字符串 - -**返回值：** - -- 无 diff --git a/docs/zh/server/security/secgear/application-scenarios.md b/docs/zh/server/security/secgear/application-scenarios.md deleted file mode 100644 index bb5cd15caff6c837d29f2ab40a1bade1bdc3aae9..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/application-scenarios.md +++ /dev/null @@ -1,96 +0,0 @@ -# 应用场景 - -本文通过举例介绍典型场景机密计算解决方案，帮助读者理解secGear的使用场景，进而结合自己的业务构建对应的机密计算解决方案。 - -## BJCA基于TEE的密码模块 - -在政策和业务的双驱动下，密码应用保障基础设施一直在向虚拟化演进，随着业务上云，密码服务支撑也需要构建全新的密码交付模式，实现密码、云服务与业务应用的融合，因此数字认证（BJCA）推出基于TEE的密码模块。数字认证既可以利用鲲鹏TEE环境构建合规的密码计算模块，支撑密码云服务平台，同时也可以基于鲲鹏主机构建“机密计算平台”，为云计算、隐私计算、边缘计算等各类场景提供“高速泛在、弹性部署、灵活调度”的密码服务支撑。基于鲲鹏处理器的内生式密码模块已经成为密码行业变革型的创新方案，并作为内生可信密码计算新起点。 - -### 现状 - -传统密码模块中算法协议以及处理的数据是隐私数据，密码模块上云存在安全风险。 - -### 解决方案 - -![](./figures/BJCA_Crypto_Module.png) - -基于TEE的密码模块方案如图所示，其中密码模块基于secGear机密计算开发框架拆分成两部分：管理服务、算法协议。 - -- 管理服务：运行在REE侧，负责对外提供密码服务，转发请求到TEE中处理。 -- 算法协议：运行在TEE侧，负责用户数据加/解密等处理。 - -由于密码服务可能存在高并发、大数据请求，此时REE与TEE存在频繁交互以及大数据拷贝，会导致性能直线下降，针对类似场景可使用secGear零切换特性优化，减少调用切换及数据拷贝次数，实现性能倍增。 - -## GaussDB基于TEE的全密态数据库 - -云数据库俨然已成为数据库业务未来重要的增长点，绝大多数的传统数据库服务厂商正在加速提供更优质的云数据库服务。然而云数据库所面临的风险相较于传统数据库更复杂多样，无论是应用程序漏洞、系统配置错误，还是恶意管理员都可能对数据安全与隐私保护造成巨大风险。 - -### 现状 - -云数据库的部署网络由“私有环境”向“开放环境”转变，系统运维管理角色被拆分为业务管理员和运维管理员。业务管理员拥有业务管理的权限，属于企业业务方，而运维管理员属于云服务提供商。数据库运维管理员虽然被定义成系统运维管理，其实际依旧享有对数据的完全使用权限，通过运维管理权限或提权来访问数据甚至篡改数据；再者，由于开放式的环境和网络边界的模糊化，用户数据在整个业务流程中被更充分的暴露给攻击者，无论是传输、存储、运维还是运行态，都有可能遭受来自攻击者的攻击。因此对于云数据库场景，如何解决第三方可信问题，如何更加可靠的保护数据安全相比传统数据库面临着更大挑战，其中数据安全、隐私不泄露是整个云数据库面临的首要安全挑战。 - -### 解决方案 - -面对上述挑战，基于TEE的GaussDB(openGauss)全密态数据库的设计思路是：用户自己持有数据加解密密钥，数据以密文形态存在于数据库服务侧的整个生命周期过程中，并在数据库服务端TEE内完成查询运算。 - -![](./figures/secret_gaussdb.png) - -基于TEE的全密态数据库解决方案如图所示，全密态数据库的特点如下： - -1. 数据文件以密文形式存储，不存储密钥明文信息。 -2. DB数据密钥保存在客户端。 -3. 客户端发起查询请求时，在服务端REE侧执行密态SQL语法得到相关密文记录，送入TEE中。 -4. 客户端通过secGear安全通道将DB数据密钥加密传输到服务端TEE中，在TEE中解密得到DB数据密钥，用DB数据密钥将密文记录解密得到明文记录，执行SQL语句，得到查询结果，再将DB数据密钥加密后的查询结果发送给客户端。 - -其中步骤3在数据库高并发请求场景下，会频繁触发REE-TEE之间调用以及大量的数据传输，导致性能直线下降，通过secGear零切换特性优化，减少调用切换及数据拷贝次数，实现性能倍增。 - -## openLooKeng基于TEE的联邦SQL - -openLooKeng联邦SQL是跨数据中心查询的一种，典型场景如下，有三个数据中心：中心数据中心A，边缘数据中心B和边缘数据中心C。openLooKeng集群部署在三个数据中心中，当数据中心A收到一次跨域查询请求时，会下发执行计划到各数据中心，在边缘数据中心B和C的openLookeng集群完成计算后，通过网络将结果传递给数据中心A中的openLookeng集群完成聚合计算。 - -### 现状 - -在以上方案中，计算结果在不同数据中心的openLookeng集群之间传递，避免了网络带宽不足，一定程度上解决了跨域查询问题。但是计算结果是从原始数据计算得到的，可能带有敏感信息，导致数据出域存在一定安全和合规风险。怎么保护聚合计算过程中边缘数据中心的计算结果，在中心数据中心实现 “可用而不可见”呢？ - -### 解决方案 - -其基本思路是：数据中心A中，openLookeng集群将聚合计算逻辑及算子拆分出独立的模块，部署到鲲鹏TEE环境上中；其他边缘数据中心的计算结果通过安全通道传输到数据中心A的TEE中；所有数据最终在TEE中完成聚合计算，从而保护聚合计算过程中边缘数据中心的计算结果不会被数据中心A上REE侧特权程序或恶意程序获取、篡改。 - -![](./figures/openLooKeng.png) - -基于TEE的联邦SQL解决方案如图所示，具体查询流程如下： - -1. 用户在数据中心A下发跨域查询请求，openLooKeng的Coordinator根据查询SQL及数据源分布，拆解下发执行计划到本地工作节点以及边缘数据中心的coordinator，边缘数据中心的coordinator再下发到本地工作节点。 -2. 各工作节点执行计划，得到本地计算结果。 -3. 边缘数据中心通过secGear安全通道将本地计算结果加密后经网络传到数据中心A的REE侧，并中转到TEE中，在TEE中解密计算结果。 -4. 数据中心A在TEE中对数据中心A、B、C的计算结果执行聚合计算，得到最终执行结果，并返回给用户。 - -其中步骤4，在存在大量查询请求时，会频繁触发REE-TEE调用，并且有大量数据的拷贝，导致性能直线下降。通过secGear零切换特性优化，减少调用切换及数据拷贝次数，实现性能倍增。 - -## MindSpore基于TEE的纵向联邦特征保护 - -纵向联邦学习是联邦学习的一个重要分支，当不同的参与方拥有来自相同一批用户但属性不同的数据时，可以利用纵向联邦学习进行协同训练。 - -![](./figures/Mindspore_original.png) - -### 现状 - -传统方案如图所示，具体数据处理流程如下。 - -1. 拥有属性的参与方（Follower方）都会持有一个底层网络，参与方属性输入底层网络得到中间结果，再将中间结果发送给拥有标签的参与方（Leader方）。 -2. Leader方使用各参与方的中间结果和标签来训练顶层网络，再将计算得到的梯度回传给各参与方来训练底层网络。 - -此方案避免了Follower方直接上传自己的原始数据，保护原始数据不出域，一定程度上保护了隐私安全。然而，攻击者还是有可能从上传的中间结果反推出用户信息，导致存在隐私泄露风险。因此我们需要对训练时出域的中间结果和梯度提供更强的隐私保护方案，来满足安全合规要求。 - -### 解决方案 - -借鉴之前三个场景的安全风险及解决方案可以发现，想要达到中间结果出域后的“可用不可见”，正是机密计算的“拿手好戏”。 - -![](./figures/Mindspore.png) - -基于TEE的纵向联邦特征保护方案如图所示，具体数据处理流程如下。 - -1. Follower方的中间结果通过secGear的安全通道加密后传输到Leader方，Leader方非安全世界接收到加密的中间结果后中转到安全世界，在安全世界通过安全通道接口解密。 -2. 在安全世界中将中间结果输入到联邦拆分层计算模块，完成结果计算。 - -以上过程中Follower方的中间结果明文只存在于安全世界内存中，对Leader方来说就是黑盒子，无法访问。 diff --git a/docs/zh/server/security/secgear/developer-guide.md b/docs/zh/server/security/secgear/developer-guide.md deleted file mode 100644 index c41e8ea0e24d8bfe2bececc8370419ceef13d65e..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/developer-guide.md +++ /dev/null @@ -1,93 +0,0 @@ -# secGear 开发指南 - -这里给出使用 secGear 开发一个 C 语言程序 helloworld 的例子，方便用户理解使用 secGear 开发应用程序。 - -## 下载样例 - -```shell -git clone https://gitee.com/openeuler/secGear.git -``` - -## 目录结构说明 - -```shell -cd examples/helloworld - -#目录结构如下 -├── helloworld -│ ├── CMakeLists.txt -│ ├── enclave -│ │ ├── CMakeLists.txt -│ │ ├── Enclave.config.xml -│ │ ├── Enclave.lds -│ │ ├── hello.c -│ │ ├── manifest.txt -│ │ └── config_cloud.ini -│ ├── helloworld.edl -│ └── host -│ ├── CMakeLists.txt -│ └── main.c -``` - -代码主体分为三块： - -- 非安全侧程序（main.c） -- 非安全侧与安全侧调用接口头文件（helloworld.edl） -- 安全侧程序（hello.c） - -## 准备工作 - -除以上三部分主体代码外，还有编译工程文件（CMakeLists.txt）、开发者证书（SGX的Enclave.config.xml/Enclave.lds，鲲鹏的manifest.txt/config_cloud.ini）。 - -> ![](./public_sys-resources/icon-note.gif)说明: -> -> - 鲲鹏开发者证书需要向华为业务负责人[申请开发者证书](https://gitee.com/link?target=https%3A%2F%2Fwww.hikunpeng.com%2Fdocument%2Fdetail%2Fzh%2Fkunpengcctrustzone%2Ffg-tz%2Fkunpengtrustzone_04_0009.html)。 -> - SGX以Debug模式调试，暂时不用申请。如需正式商用并且用intel的远程证明服务，需要向Intel[申请License](https://gitee.com/link?target=https%3A%2F%2Fwww.intel.com%2Fcontent%2Fwww%2Fus%2Fen%2Fdeveloper%2Ftools%2Fsoftware-guard-extensions%2Frequest-license.html)。 - -申请成功后会得到开发者证书相关文件，需要放置到代码目录相应位置。 - -## 开发步骤 - -基于secGear做机密计算应用拆分改造，类似于独立功能模块提取，识别敏感数据处理逻辑，提取成独立的lib库，部署在可信执行环境中，对非安全侧提供的接口定义在EDL文件中。 - -开发步骤如下图所示： - -1. 开发非安全侧main函数及接口，管理enclave并调用安全侧函数。 -2. 开发EDL文件（类似C语言头文件定义非安全侧与安全侧交互接口） -3. 开发安全侧接口实现 -4. 调用代码生成工具，根据EDL自动生成非安全侧与安全侧交互源码，并分别编译到非安全侧与安全侧二进制文件中，非安全侧逻辑直接调用安全侧对应的接口即可，无需关心自动的生成的交互代码，降低开发成本。 -5. 调用签名工具对安全侧二进制签名，实现安全侧程序可信启动。 - -![](./figures/develop_step.png) - -## 编译运行 - -### ARM环境 - -```shell -// clone secGear repository -git clone https://gitee.com/openeuler/secGear.git - -// build secGear and examples -cd secGear -source environment -mkdir debug && cd debug && cmake -DENCLAVE=GP .. && make && sudo make install - -// run helloworld -/vendor/bin/secgear_helloworld -``` - -### x86环境 - -```shell -// clone secGear repository -git clone https://gitee.com/openeuler/secGear.git - -// build secGear and examples -cd secGear -source /opt/intel/sgxsdk/environment && source environment -mkdir debug && cd debug && cmake .. && make && sudo make install - -// run helloworld -./examples/helloworld/host/secgear_helloworld -``` diff --git a/docs/zh/server/security/secgear/figures/BJCA_Crypto_Module.png b/docs/zh/server/security/secgear/figures/BJCA_Crypto_Module.png deleted file mode 100644 index 68850639553841299d65c3a666a0b57cfa5500dc..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/BJCA_Crypto_Module.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/figures/Mindspore.png b/docs/zh/server/security/secgear/figures/Mindspore.png deleted file mode 100644 index b4e415062b7474fb4a5a1d4d02af2f16796da8b7..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/Mindspore.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/figures/Mindspore_original.png b/docs/zh/server/security/secgear/figures/Mindspore_original.png deleted file mode 100644 index 7812fd1803ceccb4b7a0e9b4debe6833f1a77280..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/Mindspore_original.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/figures/develop_step.png b/docs/zh/server/security/secgear/figures/develop_step.png deleted file mode 100644 index 4241739df0bcd015dc1589f023d5d1d44f839438..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/develop_step.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/figures/openLooKeng.png b/docs/zh/server/security/secgear/figures/openLooKeng.png deleted file mode 100644 index 2f810818c55f7913a95abfa0a7a4a7136b0d7a93..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/openLooKeng.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/figures/secGear_arch.png b/docs/zh/server/security/secgear/figures/secGear_arch.png deleted file mode 100644 index d7639d138ddbcd154860fce45460e4d256b376a2..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/secGear_arch.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/figures/secret_gaussdb.png b/docs/zh/server/security/secgear/figures/secret_gaussdb.png deleted file mode 100644 index 05ab4c1b649751a76cdd0db9d47eefe57c44f180..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/figures/secret_gaussdb.png and /dev/null differ diff --git a/docs/zh/server/security/secgear/introduction-to-secGear.md b/docs/zh/server/security/secgear/introduction-to-secGear.md deleted file mode 100644 index c7bbd241a1c0184e8933891555f2c4719bd47f3a..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/introduction-to-secGear.md +++ /dev/null @@ -1,160 +0,0 @@ -# 认识secGear - -## 概述 - -随着云计算的快速发展，越来越多的企业把计算业务部署到云上，面对第三方云基础设施，云上用户数据安全面临着巨大的挑战。机密计算是一种基于硬件可信执行环境的隐私保护技术，旨在依赖最底层硬件，构建最小信任依赖，将操作系统、Hypervisor、基础设施、系统管理员、服务提供商等都从信任实体列表中删除，视为未经授权的实体，从而减少潜在的风险，保护可信执行环境中数据的机密性、完整性。然而随着机密计算技术的兴起，业界机密计算技术种类繁多（如主流的Intel SGX、ARM Trustzone、RSIC-V keystone等），各技术SDK也千差万别，给开发者带来较大的开发维护成本，长远考虑，还造成了机密计算应用生态隔离。为方便开发者快速构建保护云上数据安全的机密计算解决方案，openEuler推出机密计算统一开发框架secGear。 - -## 架构介绍 - -![](./figures/secGear_arch.png) - -secGear机密计算统一开发框架技术架构如图所示，主要包括三层，共同组成openEuler机密计算软件生态底座。 - -- Base Layer：机密计算SDK统一层，屏蔽TEE及SDK差异，实现不同架构共源码。 -- Middleware Layer：通用组件层，机密计算软件货架，无需从头造轮子，帮助用户快速构建机密计算解决方案。 -- Server Layer：机密计算服务层，提供典型场景机密计算解决方案。 - - - -## 关键特性 - -### 零切换 - -#### 客户痛点 -传统应用做机密计算拆分改造后，REE侧逻辑存在频繁调用TEE侧逻辑时或REE与TEE存在频繁大块数据交互时。由于REE与TEE之间的每次调用，都需要经过REE用户态 、REE内核态、驱动、TEE内核态、TEE用户态之间的上下文切换，调用传递的大块数据也要经过多次拷贝，并且驱动底层数据块大小限制等因素，频繁的REE与TEE交互性能直线下降，严重影响机密计算应用的落地。 - -#### 解决方案 -[零切换](https://gitee.com/openeuler/secGear#switchless%E7%89%B9%E6%80%A7)是一种通过共享内存减少REE与TEE上下文切换及数据拷贝次数，优化REE与TEE交互性能的技术。 - -#### 使用方法 - -1. 创建enclave时启用零切换 - - 零切换配置项及说明如下。 - - ```c - typedef struct { - uint32_t num_uworkers; - uint32_t num_tworkers; - uint32_t switchless_calls_pool_size; - uint32_t retries_before_fallback; - uint32_t retries_before_sleep; - uint32_t parameter_num; - uint32_t workers_policy; - uint32_t rollback_to_common; - cpu_set_t num_cores; - } cc_sl_config_t; - ``` - - | 配置项 | 说明 | - | -------------------------- | ------------------------------------------------------------ | - | num_uworkers | 非安全侧代理工作线程数，用于执行switchless OCALL，当前该字段仅在SGX平台生效，ARM平台可以配置，但是因ARM平台暂不支持OCALL，所以配置后不会生效。
规格：
ARM：最大值：512；最小值：1；缺省值：8（配置为0时）
SGX：最大值：4294967295；最小值：1 | - | num_tworkers | 安全侧代理工作线程数，用于执行switchless ECALL。
规格：
ARM：最大值：512；最小值：1；缺省值：8（配置为0时）
SGX：最大值：4294967295；最小值：1 | - | switchless_calls_pool_size | switchless调用任务池的大小，实际可容纳switchless_calls_pool_size * 64个switchless调用任务（例：switchless_calls_pool_size=1，可容纳64个switchless调用任务）。
规格：
ARM：最大值：8；最小值：1；缺省值：1（配置为0时）
SGX：最大值：8；最小值：1；缺省值：1（配置为0时） | - | retries_before_fallback | 执行retries_before_fallback次汇编pause指令后，若switchless调用仍没有被另一侧的代理工作线程执行，就回退到switch调用模式，该字段仅在SGX平台生效。
规格：SGX：最大值：4294967295；最小值：1；缺省值：20000（配置为0时） | - | retries_before_sleep | 执行retries_before_sleep次汇编pause指令后，若代理工作线程一直没有等到有任务来，则进入休眠状态，该字段仅在SGX平台生效。
规格： SGX：最大值：4294967295；最小值：1；缺省值：20000（配置为0时） | - | parameter_num | switchless函数支持的最大参数个数，该字段仅在ARM平台生效。
规格： ARM：最大值：16；最小值：0 | - | workers_policy | switchless代理线程运行模式，该字段仅在ARM平台生效。
规格： ARM： WORKERS_POLICY_BUSY：代理线程一直占用CPU资源，无论是否有任务需要处理，适用于对性能要求极高且系统软硬件资源丰富的场景； WORKERS_POLICY_WAKEUP：代理线程仅在有任务时被唤醒，处理完任务后进入休眠，等待再次被新任务唤醒 | - | rollback_to_common | 异步switchless调用失败时是否回退到普通调用，该字段仅在ARM平台生效。
规格： ARM：0：否，失败时仅返回相应错误码；其他：是，失败时回退到普通调用，此时返回普通调用的返回值 | - | num_cores | 用于设置安全侧线程绑核
规格： 最大值为当前环境CPU核数 | - -2. 定义EDL文件中接口时添加零切换标识transition_using_threads - - ```ocaml - enclave { - include "secgear_urts.h" - from "secgear_tstdc.edl" import *; - from "secgear_tswitchless.edl" import *; - trusted { - public int get_string([out, size=32]char *buf); - public int get_string_switchless([out, size=32]char *buf) transition_using_threads; - }; - }; - ``` - - - -### 安全通道 -#### 客户痛点 -数据拥有者在请求云上机密计算服务时，需要把待处理数据上传到云上TEE环境中处理，由于TEE没有网络，用户数据需要经过网络先传输到REE，REE接收到数据的明文后，再传入TEE中。用户数据的明文暴露在REE内存中，存在安全风险。 - -#### 解决方案 -安全通道是一种结合机密计算远程证明，实现数据拥有者与云上TEE之间安全的密钥协商技术，协商出仅数据拥有者与云上TEE拥有的sessionkey，再通过sessionkey加密用户数据，网络传输的是sessionkey加密后的数据，REE接收到密文数据，再传入TEE中解密，处理。 - -#### 使用方法 -安全通道以lib库方式提供，分为客户端、服务端host、服务端enclave三部分，分别由业务程序的客户端、服务端CA、服务端TA调用。 -| 模块 | 头文件 | 库文件 | 依赖 | -|------------|--------------------------|-----------------------|---------| -| 客户端 | secure_channel_client.h | libcsecure_channel.so | openssl | -| 服务端host | secure_channel_host.h | libusecure_channel.so | openssl | -| 服务端enclave | secure_channel_enclave.h | libtsecure_channel.so | TEE及TEE软件栈 | - -##### 接口列表 -| 接口名 | 所属头文件、库 | 功能 | 备注 | -|----------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|--------------|----| -| cc_sec_chl_client_init | secure_channel_client.h libcsecure_channel.so | 安全通道客户端初始化 | 调用前需初始化参数ctx中网络连接和消息发送钩子函数 | -| cc_sec_chl_client_fini | secure_channel_client.h libcsecure_channel.so | 安全通道客户端销毁 | 通知服务端销毁本客户端的信息，销毁本地安全通道信息 | -| cc_sec_chl_client_callback | secure_channel_client.h libcsecure_channel.so | 安全通道协商消息处理函数 | 处理安全通道协商过程中，服务端发送给客户端的消息。在客户端消息接收处调用 | -| cc_sec_chl_client_encrypt | secure_channel_client.h libcsecure_channel.so | 安全通道客户端的加密接口 | 无 | -| cc_sec_chl_client_decrypt | secure_channel_client.h libcsecure_channel.so | 安全通道客户端的解密接口 | 无 | -| int (*cc_conn_opt_funcptr_t)(void *conn, void *buf, size_t count); | secure_channel.h | 消息发送钩子函数原型 | 由用户客户端和服务端实现，实现中指定安全通道协商消息类型，负责发送安全通道协商消息到对端 | -| cc_sec_chl_svr_init | secure_channel_host.h libusecure_channel.so | 安全通道服务端初始化 | 调用前需初始化ctx中enclave_ctx | -| cc_sec_chl_svr_fini | secure_channel_host.h libusecure_channel.so | 安全通道服务端销毁 | 销毁安全通道服务端以及所有客户端信息 | -| cc_sec_chl_svr_callback | secure_channel_host.h libusecure_channel.so | 安全通道协商消息处理函数 | 处理安全通道协商过程中，客户端发送给服务端的消息。在服务端消息接收处调用，调用前需初始化与客户端的网络连接和发送消息函数，详见[样例](https://gitee.com/openeuler/secGear/blob/master/examples/secure_channel/host/server.c#:~:text=conn_ctx.conn_kit.send)。 | -| cc_sec_chl_enclave_encrypt | secure_channel_enclave.h libtsecure_channel.so | 安全通道enclave中的加密接口 | 无 | -| cc_sec_chl_enclave_decrypt | secure_channel_enclave.h libtsecure_channel.so | 安全通道enclave中的解密接口 | 无 | -##### 注意事项 -安全通道仅封装密钥协商过程、加解密接口，不建立网络连接，协商过程复用业务的网络连接。其中客户端和服务端的网络连接由业务建立和维护，在安全通道客户端和服务端初始化时传入消息发送钩子函数和网络连接指针。 -详见[安全通道样例](https://gitee.com/openeuler/secGear/tree/master/examples/secure_channel)。 - -### 远程证明 - -#### 客户痛点 -随着机密计算技术的发展，逐渐形成几大主流技术（如Arm Trustzone/CCA、Intel SGX/TDX、擎天Enclave、海光CSV等），产品解决方案中可能存在多种机密计算硬件，甚至不同TEE之间的协同，其中远程证明是任何一种机密计算技术信任链的重要一环，每种技术的远程证明报告格式及验证流程各有差异，用户对接不同的TEE，需要集成不同TEE证明报告的验证流程，增加了用户的集成负担，并且不利于扩展新的TEE类型。 - -#### 解决方案 -secGear远程证明统一框架是机密计算远程证明相关的关键组件，屏蔽不同TEE远程证明差异，提供Attestation Agent和Attestation Service两个组件，Agent供用户集成获取证明报告，对接证明服务；Service可独立部署，支持iTrustee、virtCCA远程证明报告的验证。 - -#### 功能描述 -远程证明统一框架聚焦机密计算相关功能，部署服务时需要的服务运维等相关能力由服务部署第三方提供。远程证明统一框架的关键技术如下： -- 报告校验插件框架：支持运行时兼容iTrustee、vritCCA、CCA等不同TEE平台证明报告检验，支持扩展新的TEE报告检验插件。 -- 证书基线管理：支持对不同TEE类型的TCB/TA基线值管理及公钥证书管理，集中部署到服务端，对用户透明。 -- 策略管理：提供默认策略（易用）、用户定制策略（灵活）。 -- 身份令牌：支持对不同TEE签发身份令牌，由第三方信任背书，实现不同TEE类型相互认证。 -- 证明代理：支持对接证明服务/点对点互证，兼容TEE报告获取，身份令牌验证等，易集成，使用户聚焦业务。 - -根据使用场景，支持点对点验证和证明服务验证两种模式。 - -证明服务验证流程如下： - -1.用户（普通节点或TEE）对TEE平台发起挑战。 - -2.TEE平台通过证明代理获取TEE证明报告，并返回给用户。 - -3.用户端证明代理将报告转发到远程证明服务。 - -4.远程证明服务完成报告校验，返回由第三方信任背书的统一格式身份令牌。 - -5.证明代理验证身份令牌，并解析得到证明报告校验结果。 - -6.得到通过的校验结果后，建立安全连接。 - -点对点验证流程(无证明服务)如下： - -1.用户向TEE平台发起挑战，TEE平台返回证明报告给用户。 - -2.用户使用本地点对点TEE校验插件完成报告验证。 - -> ![](./public_sys-resources/icon-note.gif) **说明：** -> -> 点对点验证和远程证明服务验证时的证明代理不同，在编译时可通过编译选项，决定编译有证明服务和点对点模式的证明代理。 -#### 应用场景 -在金融、AI等场景下，基于机密计算保护运行中的隐私数据安全时，远程证明是校验机密计算环境及应用合法性的技术手段，远程证明统一框架提供了易集成、易部署的组件，帮助用户快速使能机密计算远程证明能力。 - -## 缩略语 - -| 缩略语 | 英文全名 | 中文解释 | -| ------ | ----------------------------- | ---------------- | -| REE | Rich Execution Environment | 富执行环境 | -| TEE | Trusted Execution Environment | 可信执行环境 | -| EDL | Enclave Description Language | 安全应用描述语言 | diff --git a/docs/zh/server/security/secgear/public_sys-resources/icon-note.gif b/docs/zh/server/security/secgear/public_sys-resources/icon-note.gif deleted file mode 100644 index 6314297e45c1de184204098efd4814d6dc8b1cda..0000000000000000000000000000000000000000 Binary files a/docs/zh/server/security/secgear/public_sys-resources/icon-note.gif and /dev/null differ diff --git a/docs/zh/server/security/secgear/secgear-installation.md b/docs/zh/server/security/secgear/secgear-installation.md deleted file mode 100644 index 67950e202d940cb63def628d34eef436a461208c..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/secgear-installation.md +++ /dev/null @@ -1,113 +0,0 @@ -# 安装 secGear - -## ARM环境 - -### 环境要求 - -#### 硬件环境 - -| 项目 | 版本 | -| ------ | --------------------------------------------------- | -| 服务器 | TaiShan 200服务器（型号2280） | -| 主板 | 鲲鹏主板 | -| BMC | 1711单板（型号BC82SMMAB），固件版本不低于3.01.12.49 | -| CPU | 鲲鹏920处理器（型号7260、5250、5220） | -| 机箱 | 不限，建议8盘或12盘 | - -> ![img](./public_sys-resources/icon-note.gif)说明 -> -> - 要求服务器已经预置TrustZone特性套件，即预装TEE OS、TEE OS启动密钥、BMC、BIOS和License许可证。 -> - 普通服务器无法仅通过升级BMC、BIOS、TEE OS固件实现TrustZone特性使能。 -> - 带TrustZone特性的服务器出厂默认特性关闭，请参考BIOS设置使能服务器TrustZone特性。 - -### 环境准备 - - 参考鲲鹏官网[环境要求](https://www.hikunpeng.com/document/detail/zh/kunpengcctrustzone/fg-tz/kunpengtrustzone_20_0018.html)和[搭建步骤](https://www.hikunpeng.com/document/detail/zh/kunpengcctrustzone/fg-tz/kunpengtrustzone_20_0019.html)。 - -### 安装操作 - -1. 配置openEuler yum源，在线yum源或通过ISO挂载配置本地yum源，配置在线源如下。 - - ```shell - vi /etc/yum.repo/openEuler.repo - [osrepo] - name=osrepo - baseurl=http://repo.openeuler.org/openEuler-{version}/everything/aarch64/ - enabled=1 - gpgcheck=1 - gpgkey=http://repo.openeuler.org/openEuler-{version}/everything/aarch64/RPM-GPG-KEY-openEuler - ``` - -2. 安装secGear - - ```shell - #安装编译工具 - yum install cmake ocaml-dune - - #安装secGear - yum install secGear-devel - - #检查是否安装成功。命令和回显如下表示安装成功。 - rpm -qa | grep -E 'secGear|itrustee|ocaml-dune' - itrustee_sdk-xxx - itrustee_sdk-devel-xxx - secGear-xxx - secGear-devel-xxx - ocaml-dune-xxx - ``` - -## X86环境 - -### 环境要求 - -#### 硬件环境 - -支持Intel SGX（Intel Software Guard Extensions） 特性的处理器。 - -### 环境准备 - -购买支持Intel SGX特性设备，参考对应设备BIOS配置手册，开启SGX特性。 - -### 安装操作 - -1. 配置openEuler yum源，在线yum源或通过ISO挂载配置本地yum源，配置在线源如下。 - - ```shell - vi openEuler.repo - [osrepo] - name=osrepo - baseurl=http://repo.openeuler.org/openEuler{version}/everything/x86_64/ - enabled=1 - gpgcheck=1 - gpgkey=http://repo.openeuler.org/openEuler-{version}/everything/x86_64/RPM-GPG-KEY-openEuler - ``` - -2. 安装secGear - - ```shell - #安装编译工具 - yum install cmake ocaml-dune - - #安装secGear - yum install secGear-devel - - #检查是否安装成功。命令和回显如下表示安装成功。 - rpm -qa | grep -E 'secGear|ocaml-dune|sgx' - secGear-xxx - secGear-devel-xxx - ocaml-dune-xxx - libsgx-epid-xxx - libsgx-enclave-common-xxx - libsgx-quote-ex-xxx - libsgx-aesm-launch-plugin-xxx - libsgx-uae-service-xxx - libsgx-ae-le-xxx - libsgx-urts-xxx - sgxsdk-xxx - sgx-aesm-service-xxx - linux-sgx-driver-xxx - libsgx-launch-xxx - ``` - - - diff --git a/docs/zh/server/security/secgear/secgear.md b/docs/zh/server/security/secgear/secgear.md deleted file mode 100644 index 2717afebe51fd5ea7e82a3f0b8245ffa634c85bd..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/secgear.md +++ /dev/null @@ -1,5 +0,0 @@ -# secGear 开发指南 - -本文档介绍openEuler机密计算统一开发框架secGear的架构、特性、安装、开发指导、落地应用场景等，帮助用户快速了解并使用secGear。 - -本文档适用于使用openEuler系统并希望了解和使用secGear的社区开发者、开源爱好者以及相关合作伙伴。使用人员需要具备基本的Linux操作系统知识。 \ No newline at end of file diff --git a/docs/zh/server/security/secgear/using-secgear-tools.md b/docs/zh/server/security/secgear/using-secgear-tools.md deleted file mode 100644 index 8d1b14d82d1d411842d751dc82e003ebddfccaa4..0000000000000000000000000000000000000000 --- a/docs/zh/server/security/secgear/using-secgear-tools.md +++ /dev/null @@ -1,149 +0,0 @@ -# 使用 secGear 工具 - -secGear 提供了一套工具集，方便用户开发应用程序。本章介绍相关工具及其使用方法。 - -## 代码生成工具 codegener - -### 简介 - -secGear codegener 是基于 intel SGX SDK edger8r 开发的工具，用于解析 EDL 文件生成中间 C 代码，即辅助生成安全测与非安全侧文件互相调用的代码。 - -secGear codegener 定义的 EDL 文件格式与 intel SGX SDK edger8r 相同，但是不支持 Intel 的完整语法定义： - -- 只能在方法中使用 public，不加 public 的函数声明默认为 private -- 不支持从非安全侧到安全侧，以及安全侧到非安全侧的 Switchless Calls -- OCALL（Outside call） 不支持部分调用模式（如 cdecl，stdcall，fastcall） - -EDL 文件语法为类 C 语言语法，这里主要描述与 C 语言的差异部分： - -| 成员 | 含义 | -| ----------------------- | ------------------------------------------------------------ | -| include "my_type.h" | 使用外部包含文件中定义的类型 | -| trusted | 声明 TA（Trusted Application）侧可用安全函数 | -| untrusted | 声明 TA 侧可用不安全函数 | -| return_type | 定义返回值类型 | -| parameter_type | 定义参数类型 | -| [in , size = len] | 对ecall而言，表示该参数需要将数据从非安全侧传入安全侧，ocall反之（指针类型需要使用此参数，其中 size 表示实际使用的 buffer） | -| [out, size = len] | 对ecall而言，表示该参数需要将数据从安全侧传出到非安全侧，ocall反之（指针类型需要使用此参数，其中 size 表示实际使用的 buffer） | - -### 使用说明 - -#### **命令格式** - -codegen 的命令格式如下： - -- x86_64 架构： - -**codegen_x86_64** \< --trustzone | --sgx > [--trusted-dir \ | **--untrusted-dir** \| --trusted | --untrusted ] edlfile - -ARM 架构： - -**codegen_arm64** \< --trustzone | --sgx > [--trusted-dir \ | **--untrusted-dir** \| --trusted | --untrusted ] edlfile - -#### **参数说明** - -各参数含义如下： - -| **参数** | 是否可选 | 参数含义 | -| ---------------------- | -------- | ------------------------------------------------------------ | -| --trustzone \| --sgx | 必选 | 只在当前运行命令目录下生成机密计算架构对应接口函数，不加参数默认生成 SGX 接口函数 | -| --search-path \ | 可选 | 用于指定被转译的edl文件所依赖文件的搜索路径 | -| --use-prefix | 可选 | 用于给代理函数名称加上前缀，前缀名为edl的文件名 | -| --header-only | 可选 | 指定代码生成工具只生成头文件 | -| --trusted-dir \ | 可选 | 指定生成安全侧辅助代码所在目录，不指定该参数默认为当前路径 | -| --untrusted-dir \ | 可选 | 指定生成非安全侧函数辅助代码所在目录 | -| --trusted | 可选 | 生成安全侧辅助代码 | -| --untrusted | 可选 | 生成非安全侧辅助代码 | -| edlfile | 必选 | 需要转译的 EDL 文件，例如 hello.edl | - -#### 示例 - -- 转译 *helloworld.edl* ，在 *enclave-directory* 下生成安全侧辅助代码，*host-directory* 下生成非安全辅助代码的命令示例如下： - -```shell -$ codegen_x86_64 --sgx --trusted-dir enclave-directory --untrusted-dir host-directory helloworld.edl -``` - -- 转译 *helloworld.edl* ，在当前目录生成安全侧辅助代码，不生成非安全辅助代码的命令示例如下： - -```shell -$ codegen_x86_64 --sgx --trusted helloworld.edl -``` - -- 转译 *helloworld.edl* ，在当前目录生成非安全侧辅助代码，不生成安全辅助代码的命令示例如下： - -```shell -$ codegen_x86_64 --sgx --untrusted helloworld.edl -``` - -- 转译 *helloworld.edl* ，在当前目录生成安全侧和非安全侧辅助代码的命令示例如下： - -```shell -$ codegen_x86_64 --sgx helloworld.edl -``` - -## 签名工具 sign_tool - -### 简介 - -secGear sign_tool 是一款命令行工具，包含编译工具链和签名工具，用于 enclave 签名。sign_tool 有两种签名形式： - -- 单步签名：仅适用于 debug 调试模式 -- 两步签名：商用场景。需要从第三方平台或者独立的安全设备获取签名私钥，对 envlave 进行签名 - -### 使用指导 - -#### **命令格式** - -sign_tool 包含 sign 指令（对 enclave 进行签名）和 digest 指令（生成摘要值）。命令格式为： - -**sign_tool.sh -d** [sign | digest] **-x** \ **-i** \ **-p** \ **-s** \ [OPTIONS] **–o** \ - -#### **参数说明** - -| sign 指令参数 | 参数含义 | 是否必选 | -| -------------- | -------------------------------------------------------------| -------------------------------------------- | -| -a \ | api_level，标识 iTrustee TA 的 GP API version，默认为 1 | 可选 | -| -c \ | 配置文件 | 可选 | -| -d \ | 指定签名工具要进行的操作（ sign 或者 digest ） | 单步仅执行sign，两步需要先执行digest，再执行sign | -| -e \ | 设备的公钥证书，用于保护加密 rawdata 的 AES key （iTrustee必需） | 仅 iTrustee 类型必选 | -| -f \ | OTRP_FLAG，是否支持 OTRP 标准协议，默认为 0 | 可选 | -| -i \ | 待签名的库文件 | 必选 | -| -k \ | 单步签名所需私钥（pem文件） | 仅 SGX 类型必选 | -| -m \ | 安全配置文件 mainfest.txt，由用户自行配置 | 仅 iTrustee 类型必选 | -| -o \ | 输出文件 | 必选 | -| -p \ | 两步签名所需的签名服务器公钥证书（pem文件） | 必选 | -| -s \ | 两步签名所需的已签名摘要值 | 必选 | -| -t \ | TA_TYPA，标识 iTrustee 的 TA 二进制格式，默认为 1 | 可选 | -| -x \ | encalve type（sgx 或 trustzone） | 必选 | -| -h | 打印帮助信息 | 可选 | - -#### **单步签名** - -enclave 类型为 SGX，给 test.enclave 签名，输出签名文件 signed.enclave 的示例如下： - -```shell -$ sign_tool.sh –d sign –x sgx –i test.enclave -k private_test.pem –o signed.enclave -``` - -#### **两步签名** - -以 SGX 为例，两步签名的操作步骤如下： - -1. 生成摘要值 - - 使用 sign_tool 签名，生成摘要值 digest.data 和临时中间文件 signdata（该文件在生成签名文件时使用，并在签名后自动删除）。参考命令如下： - - ```shell - $ sign_tool.sh –d digest –x sgx –i input –o digest.data - ``` - -2. 将 digest.data 发送至签名机构或平台，并获取对应签名。 - -3. 使用获取的签名生成签名后的动态库 signed.enclave。 - - ```shell - $ sign_tool.sh –d sign –x sgx–i input –p pub.pem –s signature –o signed.enclave - ``` - -说明：为发布 Intel SGX 支持的正式版本应用，需要申请 Intel 白名单。流程请参考 Intel 文档：