README

   1 Libsmb2 is a userspace client library for accessing SMB2/SMB3 shares on a
   2 network.
   3 It is high performance and fully async. It supports both zero-copy
   4 for SMB READ/WRITE commands as well as compounded commands.
   5
   6 Libsmb2 is distributed under the LGPLv2.1 licence.
   7
   8
   9 API
  10 ===
  11 Libsmb2 implements three different APIs for accessing remote SMB shares :
  12
  13 1, High level synchronous posix-like API.
  14 This is a simple API for accessing a share.
  15 The functions in this API are modelled to be be similar to the corresponding
  16 POSIX functions.
  17 This API is described in libsmb.h
  18
  19 2, High level async posix-like API.
  20 This is a high performance, fully non-blocking and async API.
  21 The functions in this API are modelled to be be similar to the corresponding
  22 POSIX functions.
  23 This is the recommended API.
  24 This API is described in libsmb.h
  25
  26 3, Low level async RAW API.
  27 This is a low level API that provides direct access to the SMB2 PDUs
  28 and data structures.
  29 This API is described in libsmb-raw.h
  30
  31
  32 SMB URL Format
  33 ==============
  34 The SMB URL format is currently a small subset of the URL format that is
  35 defined/used by the Samba project.
  36 The goal is to eventually support the full URL format, thus making URLs
  37 interchangable between Samba utilities and Libsmb2 but we are not there yet.
  38
  39 smb://[<domain>;][<user>@]<server>[:<port>]/<share>[/path][?arg=val[&arg=val]*]
  40
  41 <server> is either a hostname, an IPv4 or an IPv6 address.
  42
  43 Aruments supported by libsmb2 are :
  44  sec=<mech>    : Mechanism to use to authenticate to the server. Default
  45                  is any available mech, but can be overridden by :
  46                  krb5: Use Kerberos using credentials from kinit.
  47                  krb5cc: Use Kerberos using credentials from credentials
  48                          cache.
  49                  ntlmssp : Only use NTLMSSP
  50  vers=<version> : Which SMB version to negotiate:
  51                   2: Negotiate any version of SMB2
  52                   3: Negotiate any version of SMB3
  53                   2.02, 2.10, 3.00, 3.02 : negotiate a specific version.
  54                   Default is to negotiate any SMB2 or SMB3 version.
  55   seal          : Enable SMB3 encryption.
  56
  57 NOTE:-
  58         When using krb5cc mode use smb2_set_domain() and smb2_set_password() in the examples and applications
  59
  60 Authentication
  61 ==============
  62 Libsmb2 provides has builtin support for NTLMSSP username/password
  63 authentication.
  64 It can also, optionally, be built with (MIT) Kerberos authentication.
  65
  66 Libsmb2 will try to build with Kerberos if these libraries are present.
  67 You can force a build without Kerberos support by using the flag
  68 --without-libkrb5 to configure. In this case only NTLMSSP authentication
  69 will be available.
  70
  71 MIT KERBEROS
  72 ============
  73 Authentication is implemented using MIT Kerberos and it supports both KRB5
  74 for authentication against Active Directory as well as NTLMSSP (optional).
  75
  76 MIT Kerberos can be configured to also provide NTLMSSP authentication,
  77 as an alternative to the builtin NTLMSSP implementation using an
  78 external mech plugin.
  79 To use this Kerberos/NTLMSSP module you will need to build and install
  80 GSS-NTLMSSP from [https://github.com/simo5/gss-ntlmssp]
  81 If you are uncertain you can skip this module and just use the NTLMSSP
  82 module that is provided by libsmb2.
  83
  84 NTLM Authentication
  85 -------------------
  86 NTLM credentials are stored in a text file of the form :
  87 DOMAIN:USERNAME:PASSWORD
  88 with one line per username.
  89 You need to set up the environment variable NTLM_USER_FILE to point to this
  90 file.
  91 You need one entry in this file for each local user account you want to be able
  92 to use libsmb2 for accessing a remote share.
  93
  94 By default, NTLM authentication will use the username for the current process.
  95 This can be overridden by specifying a different username in the SMB URL :
  96   smb://guest@server/share?sec=ntlmssp
  97
  98 KRB5 Authentication
  99 -------------------
 100 Kerberos authentication can be used when the linux workstation as well as
 101 the file server are part of Active Directory.
 102
 103 You should be able to authenticate to the file server using krb5
 104 by specifying sec=krb5 in the URL :
 105   smb://server/share?sec=krb5
 106
 107 The application needs to set the username, password and the domain fqdn in the context using
 108 smb2_set_user(), smb2_set_password() and smb2_set_domain() respectively.
 109
 110
 111 NTLM Credentials
 112 ================
 113 This applies to both the builtin NTLMSSP implementation as well as when
 114 using Kerberos with the NTLMSSP mech plugin.
 115
 116 NTLM credentials are stored in a text file of the form :
 117 DOMAIN:USERNAME:PASSWORD
 118 with one line per username.
 119 You need to set up the environment variable NTLM_USER_FILE to point to this
 120 file.
 121 You need one entry in this file for each local user account you want to be able
 122 to use libsmb2 for accessing a remote share.
 123
 124 By default, NTLM authentication will use the username for the current process.
 125 This can be overridden by specifying a different username in the SMB URL :
 126   smb://guest@server/share?sec=ntlmssp
 127
 128 Alternatively you can provide the username and password from your application
 129 by calling :
 130   smb2_set_user(smb2, <username>);
 131   smb2_set_password(smb2, <password>);
 132
 133
 134 SMB2/3 SIGNING
 135 ==============
 136 Signing is supported with KRB5, with the builtin ntlmssp support and with
 137 gss-ntlmssp mech plugin.
 138
 139 SMB3 Encryption
 140 ===============
 141 Encryption is only supported with KRB5 or with the builtin ntlmssp support.
 142 Encryption is not supported when the gss-ntlmssp mech plugin is used.
 143 Encryption can be enabled either using the "seal" URL argument or by calling
 144   smb3_set_seal(smb2, 1);
 145
 146 BUILDING LIBSMB2
 147 ===============
 148
 149  Windows
 150 ---------------------------
 151
 152 You have to install CMake (https://cmake.org/) and Visual Studio (https://www.visualstudio.com/)
 153 to build libsmb2 for Windows (including Universal Windows Platform).
 154
 155 Please follow the next steps to build shared library:
 156
 157         mkdir build
 158         cd build
 159         cmake -G "Visual Studio 15 2017" ..
 160         cmake --build . --config RelWithDebInfo
 161
 162 Static library:
 163
 164         mkdir build
 165         cd build
 166         cmake -G "Visual Studio 15 2017" -DBUILD_SHARED_LIBS=0 ..
 167         cmake --build . --config RelWithDebInfo
 168
 169  macOS, iOS, tvOS, watchOS
 170 ---------------------------
 171
 172 You can use AMSMB2 (https://github.com/amosavian/AMSMB2) universal framework
 173 which incorporates precompiled libsmb2 for Apple devices.
 174
 175 It is written in Swift but can be used in both Swift and Objective-C codes.
 176
 177 If you want to rebuild libsmb2 in AMSMB2, please follow these steps:
 178
 179         git clone https://github.com/amosavian/AMSMB2
 180         cd AMSMB2/buildtools
 181         ./build.sh
 182
 183 Precompiled binaries don't include Kerberos support by default.
 184 If you want build libraries with Kerberos support, execute this script instead:
 185
 186         ./build-with-krb5.sh
 187
 188
 189 ESP32
 190 -----
 191
 192 libsmb2 is pre-configured for the ESP32 micro-controller. Simply
 193 clone this project in the 'components' directory of the ESP32 project
 194 and it will automatically be included in the build process.