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