teec_protocol/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright (C) 2025-2026 KylinSoft Co., Ltd. <https://www.kylinos.cn/>
3// See LICENSES for license details.
4
5//! TEE Client-Application 通信协议定义
6//!
7//! 提供 CA（Client Application）与 TA（Trusted Application）之间通信的协议类型。
8//! 这些类型用于序列化/反序列化请求和响应数据，通过机密通信通道（TLS + VSOCK）传输。
9
10#![allow(dead_code)]
11#![allow(non_camel_case_types)]
12
13use bytemuck::{Pod, Zeroable};
14use serde::{Deserialize, Serialize};
15
16/// 数据包分块大小：32KiB
17pub const CHUNK_SIZE: u64 = 32 * 1024;
18
19/// 最大消息大小限制（10MB），防止 OOM 攻击
20pub const MAX_MESSAGE_SIZE: usize = 10 * 1024 * 1024;
21
22/// 数据包类型枚举，定义协议支持的不同操作类型
23#[derive(Debug, PartialEq, Eq, Default)]
24pub enum PacketType {
25    #[default]
26    Unknown = 0,
27    OpenSession = 1,
28    CloseSession = 2,
29    InvokeCommand = 3,
30    RequestCancellation = 4,
31}
32
33impl From<u64> for PacketType {
34    fn from(value: u64) -> Self {
35        match value {
36            0 => PacketType::Unknown,
37            1 => PacketType::OpenSession,
38            2 => PacketType::CloseSession,
39            3 => PacketType::InvokeCommand,
40            4 => PacketType::RequestCancellation,
41            _ => PacketType::Unknown,
42        }
43    }
44}
45
46impl From<PacketType> for u64 {
47    fn from(value: PacketType) -> Self {
48        match value {
49            PacketType::Unknown => 0,
50            PacketType::OpenSession => 1,
51            PacketType::CloseSession => 2,
52            PacketType::InvokeCommand => 3,
53            PacketType::RequestCancellation => 4,
54        }
55    }
56}
57
58/// 协议头结构，使用 #[repr(C)] 确保内存布局与 C 兼容
59/// 满足 bytemuck::Pod 要求：所有字段必须为基本类型
60#[repr(C)]
61#[derive(Debug, Copy, Clone, Pod, Zeroable)]
62pub struct PacketHeader {
63    /// 数据包类型标识，对应 PacketType 枚举的数值表示
64    pub data_type: u64,
65    /// 数据包负载大小
66    pub data_size: u64,
67}
68
69impl PacketHeader {
70    /// 协议头结构体的大小
71    pub const SIZE: usize = size_of::<PacketHeader>();
72
73    /// 将协议头序列化为字节切片
74    pub fn as_bytes(&self) -> &[u8] {
75        bytemuck::bytes_of(self)
76    }
77
78    /// 从字节切片反序列化协议头
79    pub fn from_bytes(buf: &[u8]) -> Self {
80        *bytemuck::from_bytes(buf)
81    }
82}
83
84/// TA 注册请求。
85///
86/// TA 启动后通过此消息向 TEE OS 注册自身，声明其 UUID。
87#[derive(Serialize, Deserialize, Debug)]
88pub enum TARequest {
89    Register { uuid: String },
90}
91
92/// TEE 请求枚举，定义 CA 发送给 TA 的所有请求类型
93///
94/// 这些请求会被序列化并通过机密通信通道（TLS + VSOCK）发送给 TA。
95#[derive(Serialize, Deserialize)]
96pub enum TEE_Request {
97    OpenSession {
98        uuid: String,
99        connection_method: u32,
100        params: TEE_Parameters,
101        #[serde(default)]
102        ca_auth_info: Option<CaAuthInfo>,
103    },
104    CloseSession {
105        session_id: u32,
106    },
107    InvokeCommand {
108        session_id: u32,
109        cmd_id: u32,
110        params: TEE_Parameters,
111    },
112    RequestCancellation {
113        session_id: u32,
114    },
115}
116
117/// CA 认证信息（用于 TA 的 ACL 访问控制）
118#[derive(Serialize, Deserialize, Debug, Clone)]
119pub struct CaAuthInfo {
120    /// CA 的唯一标识（UUID v5，基于调用者路径生成）
121    pub ca_uuid: String,
122    /// 验签是否通过（包含签名验证和证书链验证）
123    pub verified: bool,
124}
125
126/// TEE 响应枚举，定义 TA 返回给 CA 的所有响应类型
127///
128/// 这些响应会被序列化并通过机密通信通道（TLS + VSOCK）发送给 CA。
129#[derive(Serialize, Deserialize)]
130pub enum TEE_Response {
131    OpenSession { session_id: u32, result: u32 },
132    CloseSession { result: u32 },
133    InvokeCommand { params: TEE_Parameters, result: u32 },
134    RequestCancellation { result: u32 },
135}
136
137/// TEE 参数容器，包含最多 4 个参数
138///
139/// 这些参数会被序列化到请求/响应数据包中，通过网络传输。
140#[derive(Serialize, Deserialize, Default)]
141pub struct TEE_Parameters(
142    pub TEE_Parameter,
143    pub TEE_Parameter,
144    pub TEE_Parameter,
145    pub TEE_Parameter,
146);
147
148/// 单个 TEE 参数，包含参数值/数据和参数类型标识。
149///
150/// `param` 携带实际数据（VALUE (a,b) 或 MEMREF buffer），
151/// `param_type` 指示该参数的读写方向（输入/输出/双向）。
152#[derive(Serialize, Deserialize, Default)]
153pub struct TEE_Parameter {
154    pub param: TEE_Param,
155    pub param_type: TEE_ParamType,
156}
157
158/// TEE 参数的联合数据载体。
159///
160/// - `data`：用于 MEMREF 类型参数的缓冲区数据
161/// - `values`：用于 VALUE 类型参数的 (a, b) 对
162#[derive(Serialize, Deserialize, Default)]
163pub struct TEE_Param {
164    pub data: Vec<u8>,
165    pub values: TEE_Value,
166}
167
168/// TEE VALUE 类型参数的值对。
169///
170/// 对应 GP TEE Client API 中的 `TEEC_Value`，
171/// 包含两个 32 位无符号整数 `a` 和 `b`。
172#[derive(Serialize, Deserialize, Clone, Copy, Default)]
173pub struct TEE_Value {
174    pub a: u32,
175    pub b: u32,
176}
177
178/// TEE 参数类型枚举，指示参数的读写方向。
179#[derive(Serialize, Deserialize, Default, Debug, PartialEq, Eq, Clone, Copy)]
180pub enum TEE_ParamType {
181    #[default]
182    None = 0,
183    ValueInput = 1,
184    ValueOutput = 2,
185    ValueInout = 3,
186    MemrefInput = 5,
187    MemrefOutput = 6,
188    MemrefInout = 7,
189}
190
191impl From<u32> for TEE_ParamType {
192    fn from(value: u32) -> Self {
193        match value {
194            0 => TEE_ParamType::None,
195            1 => TEE_ParamType::ValueInput,
196            2 => TEE_ParamType::ValueOutput,
197            3 => TEE_ParamType::ValueInout,
198            5 => TEE_ParamType::MemrefInput,
199            6 => TEE_ParamType::MemrefOutput,
200            7 => TEE_ParamType::MemrefInout,
201            _ => TEE_ParamType::None,
202        }
203    }
204}
205
206impl From<TEE_ParamType> for u32 {
207    fn from(value: TEE_ParamType) -> Self {
208        match value {
209            TEE_ParamType::None => 0,
210            TEE_ParamType::ValueInput => 1,
211            TEE_ParamType::ValueOutput => 2,
212            TEE_ParamType::ValueInout => 3,
213            TEE_ParamType::MemrefInput => 5,
214            TEE_ParamType::MemrefOutput => 6,
215            TEE_ParamType::MemrefInout => 7,
216        }
217    }
218}
219
220/// 将路径转换为 UUID v5（用于生成 CA 唯一标识符）
221///
222/// 使用 NIL UUID 作为命名空间，路径字符串作为名称，
223/// 生成的 UUID 可用于 TEE_Request::OpenSession 的 ca_auth_info.ca_uuid 字段。
224pub fn path_to_uuid(path: &str) -> String {
225    use uuid::Uuid;
226    let namespace = Uuid::nil();
227    Uuid::new_v5(&namespace, path.as_bytes()).to_string()
228}
229
230/// 协议中使用的类型别名，为兼容 Teaclave TrustZone SDK。
231pub use TEE_ParamType as ParamType;
232/// 协议中使用的类型别名，为兼容 Teaclave TrustZone SDK。
233pub use TEE_Parameter as Parameter;
234/// 协议中使用的类型别名，为兼容 Teaclave TrustZone SDK。
235pub use TEE_Parameters as Parameters;
236/// 协议中使用的类型别名，为兼容 Teaclave TrustZone SDK。
237pub use TEE_Value as Value;
238
239#[cfg(test)]
240mod protocol_tests {
241    use super::*;
242
243    #[test]
244    fn test_tee_param_type_from_u32() {
245        // 测试 TEE_ParamType 的 From<u32> 实现 - 覆盖所有分支
246        assert_eq!(TEE_ParamType::from(0), TEE_ParamType::None);
247        assert_eq!(TEE_ParamType::from(1), TEE_ParamType::ValueInput);
248        assert_eq!(TEE_ParamType::from(2), TEE_ParamType::ValueOutput);
249        assert_eq!(TEE_ParamType::from(3), TEE_ParamType::ValueInout);
250        assert_eq!(TEE_ParamType::from(4), TEE_ParamType::None); // 未知值 -> None
251        assert_eq!(TEE_ParamType::from(5), TEE_ParamType::MemrefInput);
252        assert_eq!(TEE_ParamType::from(6), TEE_ParamType::MemrefOutput);
253        assert_eq!(TEE_ParamType::from(7), TEE_ParamType::MemrefInout);
254        assert_eq!(TEE_ParamType::from(8), TEE_ParamType::None); // 未知值 -> None
255        assert_eq!(TEE_ParamType::from(99), TEE_ParamType::None); // 未知值 -> None
256        assert_eq!(TEE_ParamType::from(255), TEE_ParamType::None); // 边界值
257    }
258
259    #[test]
260    fn test_tee_param_type_into_u32() {
261        // 测试 TEE_ParamType 的 Into<u32> 实现 - 覆盖所有变体
262        assert_eq!(u32::from(TEE_ParamType::None), 0);
263        assert_eq!(u32::from(TEE_ParamType::ValueInput), 1);
264        assert_eq!(u32::from(TEE_ParamType::ValueOutput), 2);
265        assert_eq!(u32::from(TEE_ParamType::ValueInout), 3);
266        assert_eq!(u32::from(TEE_ParamType::MemrefInput), 5);
267        assert_eq!(u32::from(TEE_ParamType::MemrefOutput), 6);
268        assert_eq!(u32::from(TEE_ParamType::MemrefInout), 7);
269    }
270
271    #[test]
272    fn test_tee_param_type_roundtrip() {
273        // 测试双向转换的往返一致性
274        let values = vec![0, 1, 2, 3, 5, 6, 7];
275        for value in values {
276            let param_type = TEE_ParamType::from(value);
277            let back_to_u32: u32 = param_type.into();
278            assert_eq!(value, back_to_u32);
279        }
280    }
281
282    #[test]
283    fn test_tee_value_default() {
284        // 测试 TEE_Value 的 Default trait
285        let default_val = TEE_Value::default();
286        assert_eq!(default_val.a, 0);
287        assert_eq!(default_val.b, 0);
288    }
289
290    #[test]
291    fn test_tee_parameter_default() {
292        // 测试 TEE_Parameter 的 Default trait
293        let default_param = TEE_Parameter::default();
294        assert_eq!(default_param.param_type, TEE_ParamType::None);
295        assert_eq!(default_param.param.values.a, 0);
296        assert_eq!(default_param.param.values.b, 0);
297        assert!(default_param.param.data.is_empty());
298    }
299
300    #[test]
301    fn test_packet_header_serialization_roundtrip() {
302        // 测试 PacketHeader 序列化/反序列化的往返一致性
303        let original = PacketHeader {
304            data_type: 0x1234_5678_9ABC_DEF0,
305            data_size: 0xFEDC_BA98_7654_3210,
306        };
307
308        let bytes = original.as_bytes();
309        let restored = PacketHeader::from_bytes(bytes);
310
311        assert_eq!(original.data_type, restored.data_type);
312        assert_eq!(original.data_size, restored.data_size);
313    }
314
315    #[test]
316    fn test_packet_type_conversion() {
317        // 测试协议类型转换 - 覆盖所有分支
318        assert_eq!(PacketType::from(0), PacketType::Unknown);
319        assert_eq!(PacketType::from(1), PacketType::OpenSession);
320        assert_eq!(PacketType::from(2), PacketType::CloseSession);
321        assert_eq!(PacketType::from(3), PacketType::InvokeCommand);
322        assert_eq!(PacketType::from(4), PacketType::RequestCancellation);
323        assert_eq!(PacketType::from(5), PacketType::Unknown); // 未知值 -> Unknown
324        assert_eq!(PacketType::from(0xFFFFFFFF), PacketType::Unknown); // 边界值
325
326        assert_eq!(u64::from(PacketType::Unknown), 0);
327        assert_eq!(u64::from(PacketType::OpenSession), 1);
328        assert_eq!(u64::from(PacketType::CloseSession), 2);
329        assert_eq!(u64::from(PacketType::InvokeCommand), 3);
330        assert_eq!(u64::from(PacketType::RequestCancellation), 4);
331    }
332
333    #[test]
334    fn test_packet_header_size() {
335        use core::mem;
336
337        // 测试协议头数据大小
338        let packet0 = PacketHeader {
339            data_type: u64::from(PacketType::OpenSession),
340            data_size: CHUNK_SIZE,
341        };
342
343        let packet1 = PacketHeader {
344            data_type: u64::from(PacketType::CloseSession),
345            data_size: 44,
346        };
347
348        assert_eq!(mem::size_of_val(&packet0), PacketHeader::SIZE);
349        assert_eq!(mem::size_of_val(&packet1), PacketHeader::SIZE);
350        assert_eq!(PacketHeader::SIZE, mem::size_of::<PacketHeader>());
351    }
352
353    #[test]
354    fn test_path_to_uuid_consistency() {
355        // 相同路径应该生成相同的 UUID
356        let uuid1 = path_to_uuid("/usr/bin/test");
357        let uuid2 = path_to_uuid("/usr/bin/test");
358        assert_eq!(uuid1, uuid2);
359    }
360
361    #[test]
362    fn test_path_to_uuid_uniqueness() {
363        // 不同路径应该生成不同的 UUID
364        let uuid1 = path_to_uuid("/usr/bin/test1");
365        let uuid2 = path_to_uuid("/usr/bin/test2");
366        assert_ne!(uuid1, uuid2);
367    }
368
369    #[test]
370    fn test_path_to_uuid_deterministic() {
371        // 测试 UUID v5 的确定性：相同路径总是生成相同的 UUID
372        // 这是 UUID v5 的核心特性，用于 CA 身份标识的稳定性
373
374        // 已知路径的已知 UUID（回归测试，确保算法稳定）
375        assert_eq!(
376            path_to_uuid("/usr/bin/test"),
377            "f2d62525-c975-5075-8bfd-ea1a7c98adc3"
378        );
379
380        // 不同路径生成不同 UUID
381        assert_ne!(path_to_uuid("/usr/bin/test"), path_to_uuid("/usr/bin/ls"));
382    }
383}
teec_protocol/lib.rs

teec_protocol/
lib.rs
