sahlberg/libsmb2
GitHub: sahlberg/libsmb2
一个高性能、全异步的跨平台 SMB2/3 用户空间客户端/服务器库，支持从嵌入式设备到游戏主机等多种平台。
Stars: 400 | Forks: 176
Libsmb2 是一个用户空间客户端/服务器库，用于访问或提供网络上的 SMB2/SMB3 共享。
它具有高性能且完全异步的特点。它支持 SMB READ/WRITE 命令的零拷贝以及复合命令。
Libsmb2 采用 LGPLv2.1 许可证分发。
# API
Libsmb2 实现了三种不同的 API 用于访问远程 SMB 共享：
1, 高级同步 posix-like API:
这是一个用于访问共享的简单 API。
此 API 中的函数仿照相应的 POSIX 函数设计。
此 API 在 libsmb2.h 中描述
2, 高级异步 posix-like API:
这是一个高性能、完全非阻塞和异步的 API。
此 API 中的函数仿照相应的 POSIX 函数设计。
这是推荐的 API。
此 API 在 libsmb2.h 中描述
3, 低级异步 RAW API:
这是一个低级 API，提供对 SMB2 PDU 和数据结构的直接访问。
此 API 在 libsmb2-raw.h 中描述
Libsmb2 实现了一个同步 API 用于运行 SMB 服务器。如果您自己实现主循环，也可以运行异步服务器。
# SMB URL 格式
SMB URL 格式目前是 Samba 项目定义/使用的 URL 格式的一个小子集。
目标是最终支持完整的 URL 格式，从而使 URL 在 Samba 实用程序和 Libsmb2 之间可以互换，但我们还没有做到这一点。
smb://[;][@][:]/[/path][?arg=val[&arg=val]*]
可以是主机名、IPv4 或 IPv6 地址。
libsmb2 支持的参数有：
sec= : 用于向服务器认证的机制。默认为任何可用的机制，但可以被以下选项覆盖：
krb5: 使用来自 kinit 的凭据的 Kerberos。
krb5cc: 使用来自凭据缓存的凭据的 Kerberos。
ntlmssp : 仅使用 NTLMSSP
vers= : 协商哪个 SMB 版本：
2: 协商任何版本的 SMB2
3: 协商任何版本的 SMB3
2.02, 2.10, 3.00, 3.02, 3.1.1 : 协商特定版本。
默认为协商任何 SMB2 或 SMB3 版本。
seal : 启用 SMB3 加密。
sign : 要求 SMB2/3 签名。
timeout : 取消命令的超时时间（秒）。
默认为 0: 无超时。
ndr32 : DCERPC: 仅提供 NDR32 传输语法。(默认)
ndr64 : DCERPC: 仅提供 NDR64 传输语法。
ndr3264 : DCERPC: 同时提供 NRD32 和 NDR64 传输语法。
le : DCERPC: 以 Little-Endian 格式发送 PDU
be : DCERPC: 以 Big-Endian 格式发送 PDU
注意：-
当使用 krb5cc 模式时，请在示例和应用程序中使用 smb2_set_domain() 和 smb2_set_password()
# SMB 服务器
在 examples/smb2-server-sync.c 中有一个示例服务器实现。库服务器函数被传递给一个函数指针数组，库将为每个客户端命令调用这些指针。根据您的用途，由您的实现填写并返回每个回复。该示例模拟了一个包含少量文件的磁盘。
您的处理程序也将被调用以作为 ntlmssp 的一部分对用户进行预认证（krb 认证尚未实现）。每次客户端连接时，您的应用程序也会被回调，以允许您在协商之前配置上下文。
# 身份验证
Libsmb2 提供了对 NTLMSSP 用户名/密码认证的内置支持。
它也可以选择通过 (MIT) Kerberos 认证构建。
如果存在这些库，Libsmb2 将尝试使用 Kerberos 构建。
您可以通过使用标志 --without-libkrb5 来配置，强制构建不带 Kerberos 支持的版本。在这种情况下，只有 NTLMSSP 认证可用。
# MIT KERBEROS
认证是使用 MIT Kerberos 实现的，它支持 KRB5 用于针对 Active Directory 的认证以及 NTLMSSP（可选）。
MIT Kerberos 可以配置为也提供 NTLMSSP 认证，作为使用外部 mech 插件的内置 NTLMSSP 实现的替代方案。
要使用此 Kerberos/NTLMSSP 模块，您需要从 [https://github.com/simo5/gss-ntlmssp] 构建并安装 GSS-NTLMSSP
如果您不确定，可以跳过此模块，仅使用 libsmb2 提供的 NTLMSSP 模块。
## NTLM Authentication
NTLM 凭据存储在以下形式的文本文件中：
DOMAIN:USERNAME:PASSWORD
每个用户名一行。
您需要设置环境变量 NTLM_USER_FILE 指向此文件。
您希望每个能够使用 libsmb2 访问远程共享的本地用户账户都需要在此文件中有一个条目。
默认情况下，NTLM 认证将使用当前进程的用户名。
这可以通过在 SMB URL 中指定不同的用户名来覆盖：
smb://guest@server/share?sec=ntlmssp
## KRB5 Authentication
当 Linux 工作站和文件服务器都属于 Active Directory 时，可以使用 Kerberos 认证。
您应该能够通过在 URL 中指定 sec=krb5 使用 krb5 向文件服务器进行认证：
smb://server/share?sec=krb5
应用程序需要分别使用 smb2_set_user()、smb2_set_password() 和 smb2_set_domain() 在上下文中设置用户名、密码和域 fqdn。
# NTLM Credentials
这适用于内置 NTLMSSP 实现以及使用 Kerberos 搭配 NTLMSSP mech 插件的情况。
NTLM 凭据存储在以下形式的文本文件中：
DOMAIN:USERNAME:PASSWORD
每个用户名一行。
您需要设置环境变量 NTLM_USER_FILE 指向此文件。
您希望每个能够使用 libsmb2 访问远程共享的本地用户账户都需要在此文件中有一个条目。
默认情况下，NTLM 认证将使用当前进程的用户名。
这可以通过在 SMB URL 中指定不同的用户名来覆盖：
smb://guest@server/share?sec=ntlmssp
或者，您可以通过调用以下函数从应用程序中提供用户名和密码：
smb2_set_user(smb2, );
smb2_set_password(smb2, );
(对于服务器，您不需要设置用户，因为它是由客户端提供的)
# SMB2/3 SIGNING
KRB5、内置 ntlmssp 支持和 gss-ntlmssp mech 插件均支持签名。
# SMB3 Encryption
仅 KRB5 或内置 ntlmssp 支持加密。
当使用 gss-ntlmssp mech 插件时不支持加密。
可以使用 "seal" URL 参数或调用 smb3_set_seal(smb2, 1); 启用加密。
# BUILDING LIBSMB2
## Windows
您必须安装 CMake (https://cmake.org/) 和 Visual Studio (https://www.visualstudio.com/)
才能为 Windows 构建 libsmb2（包括 Universal Windows Platform）。
请按照以下步骤构建共享库：
```
mkdir build
cd build
cmake -G "Visual Studio 15 2017" ..
cmake --build . --config RelWithDebInfo
```
静态库：
```
mkdir build
cd build
cmake -G "Visual Studio 15 2017" -DBUILD_SHARED_LIBS=0 ..
cmake --build . --config RelWithDebInfo
```
## macOS, iOS, tvOS, watchOS
您可以使用 AMSMB2 (https://github.com/amosavian/AMSMB2) 通用框架，
其中包含为 Apple 设备预编译的 libsmb2。
它是用 Swift 编写的，但可以在 Swift 和 Objective-C 代码中使用。
如果您想在 AMSMB2 中重新构建 libsmb2，请按照以下步骤操作：
```
git clone https://github.com/amosavian/AMSMB2
cd AMSMB2/buildtools
./build.sh
```
预编译的二进制文件默认不包含 Kerberos 支持。
如果您想构建支持 Kerberos 的库，请改用此脚本：
```
./build-with-krb5.sh
```
## ESP32
libsmb2 已为 ESP32 微控制器使用 esp-idf 工具链进行了预配置（不支持 Arduino）。只需将此项目克隆到 ESP32 项目的 'components' 目录中，它就会自动包含在构建过程中。
## Raspberry Pi Pico W (RP2040)
libsmb2 将使用 gcc-arm-none-eabi、pico-sdk 和 FreeRTOS-Kernel 在 RP2040 上编译。在 examples/picow 中有一个 CMakeLists.txt，可以对其进行编辑以指向 pico-sdk 和 FreeRTOS-Kernel，然后将构建 libsmb2 和一个示例 —— 这可以用作起点。在 include/picow 内部有一些用于 lwip、FreeRTOS 和任何使用 libsmb2 构建的应用程序的配置文件。这些也可以用作起点，并根据您的应用程序的需要进行调整。
在 RP2040 上，除了 PICO_BOARD=pico_w 等 RP2040 定义外，libsmb2 唯一需要的定义是 PICO_PLATFORM。
## Playstation 2
EE，Emotion-Engine，是 PS2 的主 CPU。
要为 PS2 EE 编译 libsmb2，首先安装 PS2 工具链和 PS2 SDK 并进行设置。
要构建 libsmb2.a，即 EE tcpip 栈版本的 libsmb2：
$ make -f Makefile.platform clean
$ make -f Makefile.platform ps2_ee_install
EE Using IOP Stack，它与 EE 不同
这是用于 LWIP 栈在 IOP 上运行时的版本（libsmb2_rpc 并链接 -lps2ips）
要构建 libsmb2_rpc.a，即带有 IOP tcpip 栈的 ee 版本的 libsmb2：
$ make -f Makefile.platform clean
$ make -f Makefile.platform ps2_rpc_install
IOP，IO-Processor 是 PS2 的辅助 CPU。
该库已用于构建 smb2man.irx 模块，但它并不随库一起安装。要为 PS2 IOP 安装 libsmb2 和 smb2man.irx，首先安装 PS2 工具链和 PS2SDK 并进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform clean
$ make -f Makefile.platform ps2_iop_install
$ make -f Makefile.platform clean
$ make -f Makefile.platform ps2_irx_install
## PlayStation 3
PPU，PowerPC，是 PS3 的主 CPU。
要为 PS3 PPU 编译 libsmb2，首先安装 PS3 工具链和 PSL1GHT SDK 并进行设置。
然后要构建 libsmb2，运行
$ cd lib
$ make -f Makefile.PS3_PPU install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 PSL1GHT SDK portlibs 文件夹。
## PlayStation Vita
ARM® Cortex™ - A9 core (4 core)，是 PSVITA 的主 CPU。
要为 PSVITA 编译 libsmb2，首先使用 vdpm 安装 VitaSDK
然后要构建 libsmb2，运行
$ make vita_install -f Makefile.platform
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 VitaSDK libs 文件夹。
## PlayStation 4
x86_64 是 PS4 的主 CPU。
要为 PS4 PPU 编译 libsmb2，首先安装 PS4 工具链和 OpenOrbis SDK 并进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform ps4_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 OpenOrbis SDK include 文件夹。
## Nintendo 3DS
Nintendo 3DS CPU 是 ARM11 MPCore 变体。
要为 Nintendo 3DS 编译 libsmb2，首先安装 devkitPro 和 libctru 以进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform 3ds_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 devkitPro 3ds portlibs 文件夹。
## Nintendo Switch
Nintendo Switch CPU 是定制版 Nvidia Tegra X1。
要为 Nintendo Switch 编译 libsmb2，首先安装 devkitPro 和 libnx 以进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform switch_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 devkitPro switch portlibs 文件夹。
## Nintendo Wii
Nintendo Wii CPU 是 Broadway PowerPC 处理器。
要为 Nintendo Wii 编译 libsmb2，首先使用 pacman 安装 devkitPro 和 libogc 以进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform wii_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 devkitPro wii portlibs 文件夹。
## Nintendo Gamecube
Nintendo GameCube CPU 是 IBM "Gekko" PowerPC CPU。
要为 Gamecube 编译 libsmb2，首先使用 pacman 安装 devkitPro 和 libogc 以进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform gc_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 devkitPro gamecube portlibs 文件夹。
## Nintendo DS
Nintendo DS CPU 包含 ARM7TDMI 和 ARM946E-S。
要为 Nintendo DS 编译 libsmb2，首先使用 pacman 安装 devkitPro 和 libnds 以进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform ds
该过程将把生成的 libsmb29.a 和 include/smb2 头文件复制到您的 devkitPro ds portlibs 文件夹的 lib/arm9 目录下。
## Nintendo WII-U
Nintendo Wii-U CPU 是 IBM "Espresso" PowerPC 架构 45 nm，拥有 4 个核心，时钟速度为 1.24 GHz。
要为 Nintendo WII-U 编译 libsmb2，首先使用 pacman 安装 devkitPro 和 libwut 以进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform wiiu_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 devkitPro wiiu portlibs 文件夹。
## Amiga (AmigaOS)
AmigaOS 是主处理器为 PowerPC 微处理器的操作系统。
有 3 个版本：
AmigaOS4(Makefile.AMIGA)
AmigaOS3(Makefile.AMIGA_OS3)
AmigaAROS(Makefile.AMIGA_AROS)
要为 AmigaOS 编译 libsmb2，您需要设置 newlib.library V53.40 或更新版本（或 4.1 FE 中包含的 V53.30）以及 filesysbox.library 54.4 或更新版本以进行设置。
然后要构建 libsmb2，根据您的 AmigaOS 系统选择 makefile 并执行
$ cd lib
$ make -f Makefile.YOUR_AMIGA_OS_USED clean install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到 lib 文件夹内的 bin 文件夹中
注意：Amiga AROS 是 AmigaOS 的开源版本，因此除非您使用的是 AmigaAROS，否则不要构建此版本。
## Dreamcast (KallistiOS)
处于 little-endian 模式的 Hitachi SH4 是 Dreamcast 的主 CPU。
要为 Dreamcast 编译 libsmb2，首先安装 KOS 工具链并进行设置。
然后要构建 libsmb2，运行
$ make -f Makefile.platform clean dc_install
该过程将把生成的 libsmb2.a 和 include/smb2 头文件复制到您的 KallistiOS 工具链安装位置的 addons 文件夹。
注意：目前还没有针对 libsmb2 的 kos-ports 条目，但一旦创建了包含 Dreamcast 支持的版本化发行版，从 kos-ports 安装将成为首选的安装方法。
## Xbox (Xbox XDK)
Xbox CPU 是定制版 Intel Pentium III Coppermine 架构处理器，仅支持 little endian 值。
要为 Xbox 编译 libsmb2，首先从 Team Resurgent 安装 RXDK。
然后要构建 libsmb2，转到 Xbox 文件夹
并打开提供的 .sln 文件，然后点击绿色按钮进行构建：
该过程将生成一个 libsmb2.lib。您可以将 include 文件和 .lib 文件复制到您的 Xbox 项目中。
## Xbox 360 (Xbox 360 SDK)
Xbox 360 CPU 是 PPC(PowerPC) Xenon，仅支持 big endian 值。
要为 Xbox 360 编译 libsmb2，首先安装 Xbox 360 SDK（包含所有功能）、Microsoft Visual C++ 2010 Ultimate 和 Windows XP（推荐）或 Windows 7。
然后要构建 libsmb2，转到 Xbox 360 文件夹
并打开提供的 .sln 文件，然后点击绿色按钮进行构建：
该过程将生成一个 libsmb2.lib。您可以将 include 文件和 .lib 文件复制到您的 Xbox 360 项目中。
注意：这两个移植版本均基于 BDC(Brent De Cartet) 的 XBMC-360 移植，现已更新至 libsmb2 标准以获得最佳性能。
标签：404团队, Bash脚本, CIFS, C语言库, LGPL, NTLMSSP, POSIX API, Samba, SMB2/SMB3, Zero-copy, 协议实现, 子域名枚举工具, 存储, 客户端加密, 客户端加密, 异步IO, 文件共享, 服务端/客户端, 用户空间客户端, 网络安全, 远程访问, 隐私保护