1# fdsan使用指导 2 3## 1. 功能介绍 4 5fdsan针对的操作对象是文件描述符，主要用于检测不同使用者对相同文件描述符的错误操作，包括多次关闭（double-close）和关闭后使用（use-after-close)。这些文件描述符可以是操作系统中的文件、目录、网络套接字和其他I/O设备等，在程序中，打开文件或套接字会生成一个文件描述符，如果此文件描述符在使用后出现反复关闭、或者关闭后使用等场景，就会造成内存泄露、文件句柄泄露等安全隐患问题。该类问题非常隐蔽，且难以排查，为了更好地检测此类问题，因此引入了此种针对文件描述符错误操作的检测工具fdsan。 6 7## 2. 实现原理 8 9设计思路：当打开已有文件或创建一个新文件的时候，在得到返回fd后，设置一个关联的tag，来标记fd的属主信息；关闭文件前，检测fd关联的tag，判断是否符合预期(属主信息一致)，符合就继续走正常文件关闭流程；如果不符合就是检测到异常，根据设置，调用对应的异常处理。 10 11tag由两部分组成，最高位的8-bit构成type，后面的56-bit构成value。 12 13type，标识fd通过何种封装形式进行管理，例如 `FDSAN_OWNER_TYPE_FILE`就表示fd通过普通文件进行管理，type类型在 `fdsan_owner_type`进行定义。 14 15value，则用于标识实际的owner tag。 16 17 tag构成图示 18 19 20 21 22 23## 3. 接口说明 24 25### fdsan_set_error_level 26 27``` 28enum fdsan_error_level fdsan_set_error_level(enum fdsan_error_level new_level); 29``` 30 31**描述：** 可以通过`fdsan_set_error_level`设定error_level，error_level用于控制检测到异常后的处理行为。默认error_level为FDSAN_ERROR_LEVEL_WARN_ALWAYS。 32 33**参数：** fdsan_error_level 34 35| 名称 | 说明 | 36| -------------------------- | ------------------------------------------------------------ | 37| `FDSAN_ERROR_LEVEL_DISABLED` | disabled，此level代表什么都不处理。 | 38| `FDSAN_ERROR_LEVEL_WARN_ONCE` | warn-once，第一次出现错误时在hilog中发出警告，然后将级别降低为disabled(FDSAN_ERROR_LEVEL_DISABLED)。 | 39| `FDSAN_ERROR_LEVEL_WARN_ALWAYS` | warn-always，每次出现错误时都在hilog中发出警告。 | 40| `FDSAN_ERROR_LEVEL_FATAL` | fatal，出现错误时调用abort异常退出。 | 41 42**返回值：** 返回旧的error_level。 43 44### fdsan_get_error_level 45 46``` 47enum fdsan_error_level fdsan_get_error_level(); 48``` 49 50**描述：** 可以通过`fdsan_get_error_level`获取error level。 51 52**返回值：** 当前的error_level。 53 54### fdsan_create_owner_tag 55``` 56uint64_t fdsan_create_owner_tag(enum fdsan_owner_type type, uint64_t tag); 57``` 58**描述：** 通过传入的type和tag字段，拼接成一个有效的文件描述符的关闭tag。 59 60**参数：** fdsan_owner_type 61 62| 名称 | 说明 | 63| -------------------------- | ------------------------------------------------------------ | 64| `FDSAN_OWNER_TYPE_GENERIC_00` | 默认未使用fd对应的type值 | 65| `FDSAN_OWNER_TYPE_GENERIC_FF` | 默认非法fd对应的type值 | 66| `FDSAN_OWNER_TYPE_FILE` | 默认普通文件对应的type值，使用fopen或fdopen打开的文件具有该类型 | 67| `FDSAN_OWNER_TYPE_DIRECTORY` | 默认文件夹对应的type值，使用opendir或fdopendir打开的文件具有该类型 | 68| `FDSAN_OWNER_TYPE_UNIQUE_FD` | 默认unique_fd对应的type值，保留暂未使用 | 69| `FDSAN_OWNER_TYPE_ZIPARCHIVE` | 默认zip压缩文件对应的type值，保留暂未使用 | 70 71**返回值：** 返回创建的tag，可以用于fdsan_exchange_owner_tag函数的输入。 72 73### fdsan_exchange_owner_tag 74 75``` 76void fdsan_exchange_owner_tag(int fd, uint64_t expected_tag, uint64_t new_tag); 77``` 78**描述：** 修改文件描述符的关闭tag。 79 80通过fd所以找到对应的FdEntry，判断close_tag值与expected_tag是否一致，一致说明符合预期，可以用new_tag值重新设定对应的FdEntry。 81 82如果不符合，则说明检测到了异常，后续则进行对应的异常处理。 83 84**参数：** 85 86| 名称 | 类型 | 说明 | 87| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 88| `fd` | int | fd句柄，作为FdEntry的索引 | 89| `expected_tag` | uint64_t | 期望的ownership tag值 | 90| `new_tag` | uint64_t | 设置新的ownership tag值 | 91 92 93 94### fdsan_close_with_tag 95 96``` 97int fdsan_close_with_tag(int fd, uint64_t tag); 98``` 99**描述：** 根据tag描述符关闭文件描述符。 100 101通过fd找到匹配的FdEntry。如果close_tag与tag相同，则符合预期，可以继续执行文件描述符关闭流程，否则意味着检测到异常。 102 103**参数：** 104 105| 名称 | 类型 | 说明 | 106| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 107| `fd` | int | 待关闭的fd句柄 | 108| `tag` | uint64_t | 期望的ownership tag | 109 110**返回值：** 0或者-1，0表示close成功，-1表示close失败。 111 112### fdsan_get_owner_tag 113``` 114uint64_t fdsan_get_owner_tag(int fd); 115``` 116**描述：** 根据文件描述符获取tag信息。 117 118通过fd找到匹配的FdEntry，并获取其对应的close_tag。 119 120**参数：** 121 122| 名称 | 类型 | 说明 | 123| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 124| `tag` | uint64_t | ownership tag | 125 126**返回值：** 返回对应fd的tag。 127 128### fdsan_get_tag_type 129``` 130const char* fdsan_get_tag_type(uint64_t tag); 131``` 132**描述：** 根据tag计算出对应的type类型。 133 134通过获取到的tag信息，通过计算获取对应tag中的type信息。 135 136**参数：** 137 138| 名称 | 类型 | 说明 | 139| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 140| `tag` | uint64_t | ownership tag | 141 142**返回值：** 返回对应tag的type。 143 144### fdsan_get_tag_value 145``` 146uint64_t fdsan_get_tag_value(uint64_t tag); 147``` 148**描述：** 根据tag计算出对应的owner value。 149 150通过获取到的tag信息，通过偏移计算获取对应tag中的value信息。 151 152**参数：** 153 154| 名称 | 类型 | 说明 | 155| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 156| `tag` | uint64_t | ownership tag | 157 158**返回值：** 返回对应tag的value。 159 160## 4. 使用示例 161 162如何使用fdsan？这是一个简单的double-close问题： 163 164``` 165void good_write() 166{ 167 sleep(1); 168 int fd = open(DEV_NULL_FILE, O_RDONLY); 169 sleep(3); 170 ssize_t ret = write(fd, "fdsan test\n", 11); 171 if (ret == -1) { 172 OH_LOG_ERROR(LOG_APP, "good write but failed?!"); 173 } 174 close(fd); 175} 176 177void bad_close() 178{ 179 int fd = open(DEV_NULL_FILE, O_RDONLY); 180 close(fd); 181 sleep(2); 182 // This close expected to be detect by fdsan 183 close(fd); 184} 185 186void functional_test() 187{ 188 std::vector<std::thread> threads; 189 for (auto function : { good_write, bad_close }) { 190 threads.emplace_back(function); 191 } 192 for (auto& thread : threads) { 193 thread.join(); 194 } 195} 196 197int main() 198{ 199 functional_test(); 200 return 0; 201} 202``` 203上述代码中的`good_write`函数会打开一个文件并写入一些字符串而`bad_close`函数中也会打开一个文件同时包含double-close问题，这两个线程同时运行那么程序的执行情况会是这样的。 204 205 206 207由于每次open返回的fd是顺序分配的，在进入主函数后第一个可用的fd是43，`bad_close`函数中第一次open返回的fd是43，在关闭之后，43就变成了可用的fd，在`good_write`函数中open返回了第一个可用的fd，即43，但是由于`bad_close`函数中存在double-close问题，因此错误的关闭了另一个线程中打开的文件，导致写入失败。 208 209在fdsan引入之后，有两种方法可以检测这类问题：使用标准库接口或实现具有fdsan的函数接口。 210 211### 使用标准库接口 212 213标准库接口中fopen，fdopen，opendir，fdopendir都已经集成了fdsan，使用前述接口而非直接使用open可以帮助检测问题。在前述案例中可以使用fopen替代open： 214 215```cpp 216void good_write() 217{ 218 sleep(1); 219 // fopen is protected by fdsan, replace open with fopen 220 // int fd = open(DEV_NULL_FILE, O_RDONLY); 221 FILE *f = fopen(DEV_NULL_FILE, O_RDONLY); 222 sleep(3); 223 ssize_t ret = write(fileno(f), "fdsan test\n", 11); 224 if (ret == -1) { 225 OH_LOG_ERROR(LOG_APP, "good write but failed?!"); 226 } 227 close(fileno(f)); 228} 229``` 230 231使用fopen打开的每个文件描述符都需要有一个与之对应的 `tag` 。`fdsan` 在 `close` 时会检查关闭的 `fd` 是否与 `tag` 匹配，不匹配就会默认提示相关日志信息。下面是上述代码的日志信息： 232 233``` 234# hilog | grep MUSL-FDSAN 23504-30 15:03:41.760 10933 1624 E C03f00/MUSL-FDSAN: attempted to close file descriptor 43, expected to be unowned, actually owned by FILE* 0x00000000f7b90aa2 236``` 237 238从这里的错误信息中可以看出FILE接口体的文件被其他人错误的关闭了，FILE接口体的地址可以协助进一步定位。 239 240此外，可以在代码中使用`fdsan_set_error_level`设置错误等级error_level，设置为Fatal之后如果fdsan检测到错误会提示日志信息同时crash生成堆栈信息用于定位。下面是error_level设置为Fatal之后生成的crash堆栈信息： 241 242``` 243Reason:Signal:SIGABRT(SI_TKILL)@0x0000076e from:1902:20010043 244Fault thread info: 245Tid:15312, Name:e.myapplication 246#00 pc 000e65bc /system/lib/ld-musl-arm.so.1(raise+176)(3de40c79448a2bbced06997e583ef614) 247#01 pc 0009c3bc /system/lib/ld-musl-arm.so.1(abort+16)(3de40c79448a2bbced06997e583ef614) 248#02 pc 0009de4c /system/lib/ld-musl-arm.so.1(fdsan_error+116)(3de40c79448a2bbced06997e583ef614) 249#03 pc 0009e2e8 /system/lib/ld-musl-arm.so.1(fdsan_close_with_tag+836)(3de40c79448a2bbced06997e583ef614) 250#04 pc 0009e56c /system/lib/ld-musl-arm.so.1(close+20)(3de40c79448a2bbced06997e583ef614) 251#05 pc 000055d8 /data/storage/el1/bundle/libs/arm/libentry.so(bad_close()+96)(f3339aac824c099f449153e92718e1b56f80b2ba) 252#06 pc 00006cf4 /data/storage/el1/bundle/libs/arm/libentry.so(decltype(std::declval<void (*)()>()()) std::__n1::__invoke[abi:v15004]<void (*)()>(void (*&&)())+24)(f3339aac824c099f449153e92718e1b56f80b2ba) 253#07 pc 00006c94 /data/storage/el1/bundle/libs/arm/libentry.so(f3339aac824c099f449153e92718e1b56f80b2ba) 254#08 pc 000067b8 /data/storage/el1/bundle/libs/arm/libentry.so(void* std::__n1::__thread_proxy[abi:v15004]<std::__n1::tuple<std::__n1::unique_ptr<std::__n1::__thread_struct, std::__n1::default_delete<std::__n1::__thread_struct>>, void (*)()>>(void*)+100)(f3339aac824c099f449153e92718e1b56f80b2ba) 255#09 pc 00105a6c /system/lib/ld-musl-arm.so.1(start+248)(3de40c79448a2bbced06997e583ef614) 256#10 pc 000700b0 /system/lib/ld-musl-arm.so.1(3de40c79448a2bbced06997e583ef614) 257``` 258 259此时，从crash信息中可以看到是bad_close中存在问题，同时crash中也包含了所有打开的文件，协助进行定位，提升效率。 260 261``` 262OpenFiles: 2630->/dev/null native object of unknown type 0 2641->/dev/null native object of unknown type 0 2652->/dev/null native object of unknown type 0 2663->socket:[28102] native object of unknown type 0 2674->socket:[28103] native object of unknown type 0 2685->anon_inode:[eventpoll] native object of unknown type 0 2696->/sys/kernel/debug/tracing/trace_marker native object of unknown type 0 2707->anon_inode:[eventpoll] native object of unknown type 0 2718->anon_inode:[eventpoll] native object of unknown type 0 2729->/dev/console native object of unknown type 0 27310->pipe:[95598] native object of unknown type 0 27411->pipe:[95598] native object of unknown type 0 27512->socket:[18542] native object of unknown type 0 27613->pipe:[96594] native object of unknown type 0 27714->socket:[18545] native object of unknown type 0 27815->pipe:[96594] native object of unknown type 0 27916->anon_inode:[eventfd] native object of unknown type 0 28017->/dev/binder native object of unknown type 0 28118->/data/storage/el1/bundle/entry.hap native object of unknown type 0 28219->anon_inode:[eventpoll] native object of unknown type 0 28320->anon_inode:[signalfd] native object of unknown type 0 28421->socket:[29603] native object of unknown type 0 28522->anon_inode:[eventfd] native object of unknown type 0 28623->anon_inode:[eventpoll] native object of unknown type 0 28724->anon_inode:[eventfd] native object of unknown type 0 28825->anon_inode:[eventpoll] native object of unknown type 0 28926->anon_inode:[eventfd] native object of unknown type 0 29027->anon_inode:[eventpoll] native object of unknown type 0 29128->anon_inode:[eventfd] native object of unknown type 0 29229->anon_inode:[eventpoll] native object of unknown type 0 29330->anon_inode:[eventfd] native object of unknown type 0 29431->anon_inode:[eventpoll] native object of unknown type 0 29532->anon_inode:[eventfd] native object of unknown type 0 29633->anon_inode:[eventpoll] native object of unknown type 0 29734->anon_inode:[eventfd] native object of unknown type 0 29835->socket:[97409] native object of unknown type 0 29936->socket:[94716] native object of unknown type 0 30038->socket:[94720] native object of unknown type 0 30140->/data/storage/el1/bundle/entry_test.hap native object of unknown type 0 30241->socket:[95617] native object of unknown type 0 30342->/sys/kernel/debug/tracing/trace_marker native object of unknown type 0 30443->/dev/null FILE* 4155724704 30544->socket:[94737] native object of unknown type 0 30645->pipe:[95634] native object of unknown type 0 30746->pipe:[95634] native object of unknown type 0 30847->pipe:[95635] native object of unknown type 0 30949->pipe:[95636] native object of unknown type 0 31050->pipe:[95636] native object of unknown type 0 311``` 312 313 314### 实现具有fdsan的函数接口 315 316除了直接使用具有fdsan功能的标准库函数之外，还可以实现具有fdsan的函数接口。fdsan机制主要通过两个接口实现：`fdsan_exchange_owner_tag`和`fdsan_close_with_tag`，fdsan_exchange_owner_tag可以设置对应fd的tag，而fdsan_close_with_tag可以在关闭文件时检查对应的tag是否正确。 317 318下面是一个具有fdsan的函数接口实现实例： 319 320```cpp 321struct fdsan_fd { 322 fdsan_fd() = default; 323 324 explicit fdsan_fd(int fd) 325 { 326 reset(fd); 327 } 328 329 fdsan_fd(const fdsan_fd& copy) = delete; 330 fdsan_fd(fdsan_fd&& move) 331 { 332 *this = std::move(move); 333 } 334 335 ~fdsan_fd() 336 { 337 reset(); 338 } 339 340 fdsan_fd& operator=(const fdsan_fd& copy) = delete; 341 fdsan_fd& operator=(fdsan_fd&& move) 342 { 343 if (this == &move) { 344 return *this; 345 } 346 reset(); 347 if (move.fd_ != -1) { 348 fd_ = move.fd_; 349 move.fd_ = -1; 350 // Acquire ownership from the moved-from object. 351 exchange_tag(fd_, move.tag(), tag()); 352 } 353 return *this; 354 } 355 356 int get() 357 { 358 return fd_; 359 } 360 361 void reset(int new_fd = -1) 362 { 363 if (fd_ != -1) { 364 close(fd_, tag()); 365 fd_ = -1; 366 } 367 if (new_fd != -1) { 368 fd_ = new_fd; 369 // Acquire ownership of the presumably unowned fd. 370 exchange_tag(fd_, 0, tag()); 371 } 372 } 373 374 private: 375 int fd_ = -1; 376 377 // Use the address of object as the file tag 378 uint64_t tag() 379 { 380 return reinterpret_cast<uint64_t>(this); 381 } 382 383 static void exchange_tag(int fd, uint64_t old_tag, uint64_t new_tag) 384 { 385 if (&fdsan_exchange_owner_tag) { 386 fdsan_exchange_owner_tag(fd, old_tag, new_tag); 387 } 388 } 389 390 static int close(int fd, uint64_t tag) 391 { 392 if (&fdsan_close_with_tag) { 393 return fdsan_close_with_tag(fd, tag); 394 } 395 } 396}; 397``` 398 399这里的实现中使用`fdsan_exchange_owner_tag`在开始时将fd与结构体对象地址绑定，然后在关闭文件时使用`fdsan_close_with_tag`进行检测，预期tag是结构体对象地址。 400 401在实现了具有fdsan的函数接口之后，可以使用该接口包装fd： 402 403```cpp 404void good_write() 405{ 406 sleep(1); 407 // int fd = open(DEV_NULL_FILE, O_RDONLY); 408 fdsan_fd fd(open(DEV_NULL_FILE, O_RDONLY)); 409 sleep(3); 410 ssize_t ret = write(fd.get(), "fdsan test\n", 11); 411 if (ret == -1) { 412 OH_LOG_ERROR(LOG_APP, "good write but failed?!"); 413 } 414 close(fd.get()); 415} 416``` 417 418此时运行该程序可以检测到另一个线程的double-close问题，详细信息可以参考3.2节。同样也可以设置error_level为fatal，这样可以使fdsan在检测到crash之后主动crash以获取更多信息。 419 420
