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   sign          : Require SMB2/3 signing.
  57   timeout       : Timeout in seconds when to cancel a command.
  58                   Default it 0: No timeout.
  59
  60 NOTE:-
  61         When using krb5cc mode use smb2_set_domain() and smb2_set_password() in the examples and applications
  62
  63 Authentication
  64 ==============
  65 Libsmb2 provides has builtin support for NTLMSSP username/password
  66 authentication.
  67 It can also, optionally, be built with (MIT) Kerberos authentication.
  68
  69 Libsmb2 will try to build with Kerberos if these libraries are present.
  70 You can force a build without Kerberos support by using the flag
  71 --without-libkrb5 to configure. In this case only NTLMSSP authentication
  72 will be available.
  73
  74 MIT KERBEROS
  75 ============
  76 Authentication is implemented using MIT Kerberos and it supports both KRB5
  77 for authentication against Active Directory as well as NTLMSSP (optional).
  78
  79 MIT Kerberos can be configured to also provide NTLMSSP authentication,
  80 as an alternative to the builtin NTLMSSP implementation using an
  81 external mech plugin.
  82 To use this Kerberos/NTLMSSP module you will need to build and install
  83 GSS-NTLMSSP from [https://github.com/simo5/gss-ntlmssp]
  84 If you are uncertain you can skip this module and just use the NTLMSSP
  85 module that is provided by libsmb2.
  86
  87 NTLM Authentication
  88 -------------------
  89 NTLM credentials are stored in a text file of the form :
  90 DOMAIN:USERNAME:PASSWORD
  91 with one line per username.
  92 You need to set up the environment variable NTLM_USER_FILE to point to this
  93 file.
  94 You need one entry in this file for each local user account you want to be able
  95 to use libsmb2 for accessing a remote share.
  96
  97 By default, NTLM authentication will use the username for the current process.
  98 This can be overridden by specifying a different username in the SMB URL :
  99   smb://guest@server/share?sec=ntlmssp
 100
 101 KRB5 Authentication
 102 -------------------
 103 Kerberos authentication can be used when the linux workstation as well as
 104 the file server are part of Active Directory.
 105
 106 You should be able to authenticate to the file server using krb5
 107 by specifying sec=krb5 in the URL :
 108   smb://server/share?sec=krb5
 109
 110 The application needs to set the username, password and the domain fqdn in the context using
 111 smb2_set_user(), smb2_set_password() and smb2_set_domain() respectively.
 112
 113
 114 NTLM Credentials
 115 ================
 116 This applies to both the builtin NTLMSSP implementation as well as when
 117 using Kerberos with the NTLMSSP mech plugin.
 118
 119 NTLM credentials are stored in a text file of the form :
 120 DOMAIN:USERNAME:PASSWORD
 121 with one line per username.
 122 You need to set up the environment variable NTLM_USER_FILE to point to this
 123 file.
 124 You need one entry in this file for each local user account you want to be able
 125 to use libsmb2 for accessing a remote share.
 126
 127 By default, NTLM authentication will use the username for the current process.
 128 This can be overridden by specifying a different username in the SMB URL :
 129   smb://guest@server/share?sec=ntlmssp
 130
 131 Alternatively you can provide the username and password from your application
 132 by calling :
 133   smb2_set_user(smb2, <username>);
 134   smb2_set_password(smb2, <password>);
 135
 136
 137 SMB2/3 SIGNING
 138 ==============
 139 Signing is supported with KRB5, with the builtin ntlmssp support and with
 140 gss-ntlmssp mech plugin.
 141
 142 SMB3 Encryption
 143 ===============
 144 Encryption is only supported with KRB5 or with the builtin ntlmssp support.
 145 Encryption is not supported when the gss-ntlmssp mech plugin is used.
 146 Encryption can be enabled either using the "seal" URL argument or by calling
 147   smb3_set_seal(smb2, 1);
 148
 149 BUILDING LIBSMB2
 150 ===============
 151
 152  Windows
 153 ---------------------------
 154
 155 You have to install CMake (https://cmake.org/) and Visual Studio (https://www.visualstudio.com/)
 156 to build libsmb2 for Windows (including Universal Windows Platform).
 157
 158 Please follow the next steps to build shared library:
 159
 160         mkdir build
 161         cd build
 162         cmake -G "Visual Studio 15 2017" ..
 163         cmake --build . --config RelWithDebInfo
 164
 165 Static library:
 166
 167         mkdir build
 168         cd build
 169         cmake -G "Visual Studio 15 2017" -DBUILD_SHARED_LIBS=0 ..
 170         cmake --build . --config RelWithDebInfo
 171
 172  macOS, iOS, tvOS, watchOS
 173 ---------------------------
 174
 175 You can use AMSMB2 (https://github.com/amosavian/AMSMB2) universal framework
 176 which incorporates precompiled libsmb2 for Apple devices.
 177
 178 It is written in Swift but can be used in both Swift and Objective-C codes.
 179
 180 If you want to rebuild libsmb2 in AMSMB2, please follow these steps:
 181
 182         git clone https://github.com/amosavian/AMSMB2
 183         cd AMSMB2/buildtools
 184         ./build.sh
 185
 186 Precompiled binaries don't include Kerberos support by default.
 187 If you want build libraries with Kerberos support, execute this script instead:
 188
 189         ./build-with-krb5.sh
 190
 191
 192 ESP32
 193 -----
 194
 195 libsmb2 is pre-configured for the ESP32 micro-controller. Simply
 196 clone this project in the 'components' directory of the ESP32 project
 197 and it will automatically be included in the build process.