# COMP3301 2024 – Assignment 2
## 1. 课程与作业介绍
– **课程**：COMP3301
– **作业发布时间**：2024年
– **截止时间**：第10周周一下午3点（9月30日）
– **提交方式**：Blackboard（反思文档）和Git。代码提交将在第10周的实践课中进行评分
### 1.1学术诚信
– 所有评估均为个人任务。可以与同学讨论C编程和评估规范的相关方面，但不应在实际编码过程中互相帮助。禁止查看他人代码，也不允许自己的代码以任何形式被他人看到或分享。提交的代码将进行抄袭和串通检查，一旦发现违规，将启动正式的不当行为处理程序。
– **AI工具使用**：所有评估任务均在不借助生成式人工智能（AI）或机器翻译（MT）的情况下评估学生的能力、技能和知识。使用AI技术生成答案（例如代码生成）是严格禁止的，可能构成学生不当行为。
### 1.2作业背景
– 两个进程可以通过文件描述符（如管道、打开的文件）或共享内存（如使用`mmap()`和`MAP_SHARED`映射的内存）进行通信。但文件描述符或共享内存只有在进程存在父子关系时才能被继承。
– UNIX允许通过UNIX域套接字使用套接字控制消息`SCM_RIGHTS`在任意两个进程之间传递文件描述符。而共享内存也可以通过套接字控制消息实现，但在OpenBSD中目前尚未实现。
## 2. 作业任务概述
1. **理解`SCM_RIGHTS`**：找到`SCM_RIGHTS`在内核中的实现位置并理解其工作原理，填写并提交流程图，在反思文档中说明查找相关代码的步骤及使用的工具。
2. **实现`SCM_PAGES`**：实现一个通过套接字控制消息接口共享内存页面的进程间通信机制，类似于`SCM_RIGHTS`。发送的是`memshareblk`结构数组，而不是文件描述符数组，并处理各种边界情况。
3. **识别安全风险**：在反思文档中识别至少一个与任务设计或代码实现相关的潜在安全风险，并详细解释风险以及如何缓解该风险。
## 3. 作业完成步骤
### 3.1准备工作
1. **下载基础代码补丁**
– 命令：`cd ~ ftp https://stluc.manta.uqcloud.net/comp3301/public/2024/comp3301 -2024 -a2.patch`
2. **创建`a2`分支**
– 命令：`cd /usr/src git checkout -b a2 openbsd -7.5`
3. **应用基础代码补丁**
– 命令：`git am < ~/comp3301 -2024 -a2.patch`
4. **安装头文件**
- 命令：`cd /usr/src/include doas make includes`
5. **构建内核**
- `cd /usr/src/sys/arch/amd64/compile/GENERIC.MP`
- `make obj`
- `make config`
- `make -j4`
- `doas make install`
6. **重启系统**
- 命令：`doas reboot`
7. **构建并安装`a2client`**
- `cd /usr/src/usr.sbin/a2client`
- `make obj`
- `make doas make install`
8. **构建并安装`a2server`**
- `cd /usr/src/usr.sbin/a2server`
- `make obj`
- `make doas make install`
9. （可选）构建并安装`fdsend`
- `cd /usr/src/usr.sbin/fdsend`
- `make obj`
- `make doas make install`
10. （可选）构建并安装`fdrecv`
- `cd /usr/src/usr.sbin/fdrecv`
- `make obj`
- `make doas make install`
### 3.2具体任务
1. **理解`SCM_RIGHTS`**
- 阅读并理解`SCM_RIGHTS`在OpenBSD 7.5中的实现方式以及文件描述符在进程间的传递方式。
- 填写并提交Blackboard上提供的流程图模板，在反思文档中说明查找内核源代码中相关代码的步骤以及使用的工具（如`grep/fgrep`，`cscope`等）。
2. **实现`SCM_PAGES`**
- 基础代码补丁定义了`SCM_PAGES`、`struct memshareblk`结构以及一些头文件中的标志。
- 实现`SCM_PAGES`接口，发送`memshareblk`结构数组来替代文件描述符数组。每个`memshareblk`结构代表要共享或已接收的连续内存页面列表，需处理各种边界情况，如地址不指向页面起始位置、页面未映射、页面列表有间隙、发送方在接收方接收之前取消映射页面、发送方在接收方接收之前退出等情况。
3. **识别安全风险**
- 在反思文档中识别至少一个与任务相关的潜在安全风险，如拒绝服务（操作系统崩溃、性能下降）、机密信息泄露、内核数据结构泄露到用户空间等，并详细解释风险以及如何缓解该风险。
## 4. 作业要求
### 4.1代码风格
- 代码需按照OpenBSD的风格指南编写，可使用`https://stluc.manta.uqcloud.net/comp3301/public/2022/cstyle.pl`工具检查风格违规。代码风格分数将根据自己编写或修改的代码中的风格违规数量计算，OpenBSD源代码树或基础代码中的风格违规不影响分数。
### 4.2可靠性、健壮性、可移植性和模块性
- 代码应可靠且健壮，能够正确处理所有错误，不应意外崩溃。同时应具有可移植性和模块性，如页面大小等常量不应硬编码，相似代码不应在多个地方重复。
- 代码必须能够在AMD64架构的`GENERIC.MP`（通用多处理器）配置下编译。有编译时错误的代码将手动评分，并可能导致严重扣分。
## 5. Git提交要求
1. **提交位置**：将更改提交并推送到`source.eait.uq.edu.au`上课程提供的Git仓库。
2. **提交内容**：只应提交源代码和makefile，不应提交`cscope`输出、核心转储文件或基础代码补丁文件。
3. **`a2`分支内容**：应包括OpenBSD 7.5基础提交、A2基础补丁提交以及自己添加所需功能的提交。提交历史和提交消息不影响成绩，但建议频繁提交并使用合适的提交消息。
### 5.1反思文档
1. **内容要求**：
- 完成`SCM_RIGHTS`流程图。
- 识别并描述至少一个安全风险。反思文档应包含引言、流程图（完成A或B模板）、安全风险和结论等部分，可添加其他部分或子部分。
2. **格式要求**：上传为PDF文件，文件名为学生编号`a2.pdf`，页数最多4页。
### 5.2评分方式
1. **演示评分**：提交将在截止周的实践课上由课程工作人员在与学生面对面的演示中进行评分。学生必须亲自参加，否则提交将不被评分。
2. **演示环节**：在演示中，学生将被要求展示作业，包括解释`SCM_RIGHTS`的工作原理、查找相关代码的位置、流程图的标注原因、代码中的某些操作的原因等。演示将在标记VM上进行，不接受在演示过程中对代码的更改。代码必须能够正确编译和运行，否则将影响功能分数。
## 6. 其他建议
- 强烈建议使用Git定期备份作业代码，以防止内核崩溃导致文件系统损坏而丢失代码。同时也建议在尝试作业编程部分之前对虚拟机进行快照。
### 6.2相关手册页
- 以下手册页可能对理解现有功能或作业实现有用：`CMSG_DATA(3)`、`uvm(9)`、`malloc(9)`、`TAILQ_INIT(3)`、`RB_PROTOTYPE(3)`、`file(9)`、`KASSERT(9)`。
1. **公共测试**：提供了公共测试，在运行测试之前建议先运行`sync`命令以减少内核崩溃时文件系统损坏的可能性。公共测试仅测试`SCM_PAGES`的基本功能，通过公共测试并不保证代码完全正确，鼓励学生编写自己的测试用例。
2. **测试程序安装**：可通过在虚拟机中运行一系列命令安装测试程序`a2test`和22个公共测试。
3. **`a2test`程序使用**：`a2test`程序接受命令行参数，第一个参数可选`public`、`private`、`custom`或`all`，第二个参数可选`run`、`info`或`dump`，第三个参数是要运行/查看信息/转储输出的测试列表或`all`。