source: vendor/3.6.23/docs-xml/manpages-3/ntlm_auth.1.xml

Last change on this file was 860, checked in by Silvan Scherrer, 11 years ago

Samba 3.6: updated vendor to latest version

File size: 14.1 KB
Line 
1<?xml version="1.0" encoding="iso-8859-1"?>
2<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3<refentry id="ntlm-auth.1">
4
5<refmeta>
6 <refentrytitle>ntlm_auth</refentrytitle>
7 <manvolnum>1</manvolnum>
8 <refmiscinfo class="source">Samba</refmiscinfo>
9 <refmiscinfo class="manual">User Commands</refmiscinfo>
10 <refmiscinfo class="version">3.6</refmiscinfo>
11</refmeta>
12
13
14<refnamediv>
15 <refname>ntlm_auth</refname>
16 <refpurpose>tool to allow external access to Winbind's NTLM authentication function</refpurpose>
17</refnamediv>
18
19<refsynopsisdiv>
20 <cmdsynopsis>
21 <command>ntlm_auth</command>
22 <arg choice="opt">-d debuglevel</arg>
23 <arg choice="opt">-l logdir</arg>
24 <arg choice="opt">-s &lt;smb config file&gt;</arg>
25 </cmdsynopsis>
26</refsynopsisdiv>
27
28<refsect1>
29 <title>DESCRIPTION</title>
30
31 <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
32 <manvolnum>7</manvolnum></citerefentry> suite.</para>
33
34 <para><command>ntlm_auth</command> is a helper utility that authenticates
35 users using NT/LM authentication. It returns 0 if the users is authenticated
36 successfully and 1 if access was denied. ntlm_auth uses winbind to access
37 the user and authentication data for a domain. This utility
38 is only intended to be used by other programs (currently
39 <ulink url="http://www.squid-cache.org/">Squid</ulink>
40 and <ulink url="http://download.samba.org/ftp/unpacked/lorikeet/trunk/mod_ntlm_winbind/">mod_ntlm_winbind</ulink>)
41 </para>
42</refsect1>
43
44<refsect1>
45 <title>OPERATIONAL REQUIREMENTS</title>
46
47 <para>
48 The <citerefentry><refentrytitle>winbindd</refentrytitle>
49 <manvolnum>8</manvolnum></citerefentry> daemon must be operational
50 for many of these commands to function.</para>
51
52 <para>Some of these commands also require access to the directory
53 <filename>winbindd_privileged</filename> in
54 <filename>$LOCKDIR</filename>. This should be done either by running
55 this command as root or providing group access
56 to the <filename>winbindd_privileged</filename> directory. For
57 security reasons, this directory should not be world-accessable. </para>
58
59</refsect1>
60
61
62<refsect1>
63 <title>OPTIONS</title>
64
65 <variablelist>
66 <varlistentry>
67 <term>--helper-protocol=PROTO</term>
68 <listitem><para>
69 Operate as a stdio-based helper. Valid helper protocols are:
70 </para>
71 <variablelist>
72 <varlistentry>
73 <term>squid-2.4-basic</term>
74 <listitem><para>
75 Server-side helper for use with Squid 2.4's basic (plaintext)
76 authentication. </para>
77 </listitem>
78 </varlistentry>
79 <varlistentry>
80 <term>squid-2.5-basic</term>
81 <listitem><para>
82 Server-side helper for use with Squid 2.5's basic (plaintext)
83 authentication. </para>
84 </listitem>
85 </varlistentry>
86 <varlistentry>
87 <term>squid-2.5-ntlmssp</term>
88 <listitem><para>
89 Server-side helper for use with Squid 2.5's NTLMSSP
90 authentication. </para>
91 <para>Requires access to the directory
92 <filename>winbindd_privileged</filename> in
93 <filename>$LOCKDIR</filename>. The protocol used is
94 described here: <ulink
95 url="http://devel.squid-cache.org/ntlm/squid_helper_protocol.html">http://devel.squid-cache.org/ntlm/squid_helper_protocol.html</ulink>.
96 This protocol has been extended to allow the
97 NTLMSSP Negotiate packet to be included as an argument
98 to the <command>YR</command> command. (Thus avoiding
99 loss of information in the protocol exchange).
100 </para>
101 </listitem>
102 </varlistentry>
103 <varlistentry>
104 <term>ntlmssp-client-1</term>
105 <listitem><para>
106 Client-side helper for use with arbitrary external
107 programs that may wish to use Samba's NTLMSSP
108 authentication knowledge. </para>
109 <para>This helper is a client, and as such may be run by any
110 user. The protocol used is
111 effectively the reverse of the previous protocol. A
112 <command>YR</command> command (without any arguments)
113 starts the authentication exchange.
114 </para>
115 </listitem>
116 </varlistentry>
117
118 <varlistentry>
119 <term>gss-spnego</term>
120 <listitem><para>
121 Server-side helper that implements GSS-SPNEGO. This
122 uses a protocol that is almost the same as
123 <command>squid-2.5-ntlmssp</command>, but has some
124 subtle differences that are undocumented outside the
125 source at this stage.
126 </para>
127 <para>Requires access to the directory
128 <filename>winbindd_privileged</filename> in
129 <filename>$LOCKDIR</filename>.
130 </para>
131 </listitem>
132 </varlistentry>
133
134 <varlistentry>
135 <term>gss-spnego-client</term>
136 <listitem><para>
137 Client-side helper that implements GSS-SPNEGO. This
138 also uses a protocol similar to the above helpers, but
139 is currently undocumented.
140 </para>
141 </listitem>
142 </varlistentry>
143
144 <varlistentry>
145 <term>ntlm-server-1</term>
146 <listitem><para>
147 Server-side helper protocol, intended for use by a
148 RADIUS server or the 'winbind' plugin for pppd, for
149 the provision of MSCHAP and MSCHAPv2 authentication.
150 </para>
151 <para>This protocol consists of lines in the form:
152 <command>Parameter: value</command> and <command>Parameter::
153 Base64-encode value</command>. The presence of a single
154 period <command>.</command> indicates that one side has
155 finished supplying data to the other. (Which in turn
156 could cause the helper to authenticate the
157 user). </para>
158
159 <para>Currently implemented parameters from the
160 external program to the helper are:</para>
161 <variablelist>
162 <varlistentry>
163 <term>Username</term>
164 <listitem><para>The username, expected to be in
165 Samba's <smbconfoption name="unix charset"/>.
166 </para>
167 <varlistentry>
168 <term>Examples:</term>
169 <para>Username: bob</para>
170 <para>Username:: Ym9i</para>
171 </varlistentry>
172 </listitem>
173 </varlistentry>
174
175 <varlistentry>
176 <term>NT-Domain</term>
177 <listitem><para>The user's domain, expected to be in
178 Samba's <smbconfoption name="unix charset"/>.
179 </para>
180
181 <varlistentry>
182 <term>Examples:</term>
183 <para>NT-Domain: WORKGROUP</para>
184 <para>NT-Domain:: V09SS0dST1VQ</para>
185 </varlistentry>
186 </listitem>
187 </varlistentry>
188
189 <varlistentry>
190 <term>Full-Username</term>
191 <listitem><para>The fully qualified username, expected to be
192 in Samba's <smbconfoption name="unix charset"/> and qualified
193 with the <smbconfoption name="winbind separator"/>.</para>
194 <varlistentry>
195 <term>Examples:</term>
196 <para>Full-Username: WORKGROUP\bob</para>
197 <para>Full-Username:: V09SS0dST1VQYm9i</para>
198 </varlistentry>
199 </listitem>
200 </varlistentry>
201
202 <varlistentry>
203 <term>LANMAN-Challenge</term>
204 <listitem><para>The 8 byte <command>LANMAN Challenge</command>
205 value, generated randomly by the server, or (in cases such
206 as MSCHAPv2) generated in some way by both the server and
207 the client.</para>
208 <varlistentry>
209 <term>Examples:</term>
210 <para>LANMAN-Challenge: 0102030405060708</para>
211 </varlistentry>
212 </listitem>
213 </varlistentry>
214
215 <varlistentry>
216 <term>LANMAN-Response</term>
217 <listitem><para>The 24 byte <command>LANMAN Response</command> value,
218 calculated from the user's password and the supplied
219 <command>LANMAN Challenge</command>. Typically, this
220 is provided over the network by a client wishing to authenticate.
221 </para>
222 <varlistentry>
223 <term>Examples:</term>
224 <para>LANMAN-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</para>
225 </varlistentry>
226 </listitem>
227 </varlistentry>
228
229 <varlistentry>
230 <term>NT-Response</term>
231 <listitem><para>The >= 24 byte <command>NT Response</command>
232 calculated from the user's password and the supplied
233 <command>LANMAN Challenge</command>. Typically, this is
234 provided over the network by a client wishing to authenticate.
235 </para>
236 <varlistentry>
237 <term>Examples:</term>
238 <para>NT-Response: 0102030405060708090A0B0C0D0E0F10111213141516171</para>
239 </varlistentry>
240 </listitem>
241 </varlistentry>
242
243 <varlistentry>
244 <term>Password</term>
245 <listitem><para>The user's password. This would be
246 provided by a network client, if the helper is being
247 used in a legacy situation that exposes plaintext
248 passwords in this way.</para>
249 <varlistentry>
250 <term>Examples:</term>
251 <para>Password: samba2</para>
252 <para>Password:: c2FtYmEy</para>
253 </varlistentry>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term>Request-User-Session-Key</term>
259 <listitem><para>Upon successful authenticaiton, return
260 the user session key associated with the login.</para>
261 <varlistentry>
262 <term>Examples:</term>
263 <para>Request-User-Session-Key: Yes</para>
264 </varlistentry>
265 </listitem>
266 </varlistentry>
267
268 <varlistentry>
269 <term>Request-LanMan-Session-Key</term>
270 <listitem><para>Upon successful authenticaiton, return
271 the LANMAN session key associated with the login.
272 </para>
273 <varlistentry>
274 <term>Examples:</term>
275 <para>Request-LanMan-Session-Key: Yes</para>
276 </varlistentry>
277 </listitem>
278 </varlistentry>
279
280 </variablelist>
281 </listitem>
282 </varlistentry>
283 </variablelist>
284 <warning><para>Implementers should take care to base64 encode
285 any data (such as usernames/passwords) that may contain malicous user data, such as
286 a newline. They may also need to decode strings from
287 the helper, which likewise may have been base64 encoded.</para></warning>
288 </listitem>
289 </varlistentry>
290
291 <varlistentry>
292 <term>--username=USERNAME</term>
293 <listitem><para>
294 Specify username of user to authenticate
295 </para></listitem>
296
297 </varlistentry>
298
299 <varlistentry>
300 <term>--domain=DOMAIN</term>
301 <listitem><para>
302 Specify domain of user to authenticate
303 </para></listitem>
304 </varlistentry>
305
306 <varlistentry>
307 <term>--workstation=WORKSTATION</term>
308 <listitem><para>
309 Specify the workstation the user authenticated from
310 </para></listitem>
311 </varlistentry>
312
313 <varlistentry>
314 <term>--challenge=STRING</term>
315 <listitem><para>NTLM challenge (in HEXADECIMAL)</para>
316 </listitem>
317 </varlistentry>
318
319 <varlistentry>
320 <term>--lm-response=RESPONSE</term>
321 <listitem><para>LM Response to the challenge (in HEXADECIMAL)</para></listitem>
322 </varlistentry>
323
324 <varlistentry>
325 <term>--nt-response=RESPONSE</term>
326 <listitem><para>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</para></listitem>
327 </varlistentry>
328
329 <varlistentry>
330 <term>--password=PASSWORD</term>
331 <listitem><para>User's plaintext password</para><para>If
332 not specified on the command line, this is prompted for when
333 required. </para>
334
335 <para>For the NTLMSSP based server roles, this parameter
336 specifies the expected password, allowing testing without
337 winbindd operational.</para>
338 </listitem>
339 </varlistentry>
340
341 <varlistentry>
342 <term>--request-lm-key</term>
343 <listitem><para>Retrieve LM session key</para></listitem>
344 </varlistentry>
345
346 <varlistentry>
347 <term>--request-nt-key</term>
348 <listitem><para>Request NT key</para></listitem>
349 </varlistentry>
350
351 <varlistentry>
352 <term>--diagnostics</term>
353 <listitem><para>Perform Diagnostics on the authentication
354 chain. Uses the password from <command>--password</command>
355 or prompts for one.</para>
356 </listitem>
357 </varlistentry>
358
359 <varlistentry>
360 <term>--require-membership-of={SID|Name}</term>
361 <listitem><para>Require that a user be a member of specified
362 group (either name or SID) for authentication to succeed.</para>
363 </listitem>
364 </varlistentry>
365
366 &stdarg.server.debug;
367 &popt.common.samba;
368 &stdarg.help;
369
370 </variablelist>
371</refsect1>
372
373<refsect1>
374 <title>EXAMPLE SETUP</title>
375
376 <para>To setup ntlm_auth for use by squid 2.5, with both basic and
377 NTLMSSP authentication, the following
378 should be placed in the <filename>squid.conf</filename> file.
379<programlisting>
380auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
381auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
382auth_param basic children 5
383auth_param basic realm Squid proxy-caching web server
384auth_param basic credentialsttl 2 hours
385</programlisting></para>
386
387<note><para>This example assumes that ntlm_auth has been installed into your
388 path, and that the group permissions on
389 <filename>winbindd_privileged</filename> are as described above.</para></note>
390
391 <para>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above
392 example, the following should be added to the <filename>squid.conf</filename> file.
393<programlisting>
394auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
395auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
396</programlisting></para>
397
398</refsect1>
399
400<refsect1>
401 <title>TROUBLESHOOTING</title>
402
403 <para>If you're experiencing problems with authenticating Internet Explorer running
404 under MS Windows 9X or Millennium Edition against ntlm_auth's NTLMSSP authentication
405 helper (--helper-protocol=squid-2.5-ntlmssp), then please read
406 <ulink url="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP">
407 the Microsoft Knowledge Base article #239869 and follow instructions described there</ulink>.
408 </para>
409</refsect1>
410
411<refsect1>
412 <title>VERSION</title>
413
414 <para>This man page is correct for version 3 of the Samba
415 suite.</para>
416</refsect1>
417
418<refsect1>
419 <title>AUTHOR</title>
420
421 <para>The original Samba software and related utilities
422 were created by Andrew Tridgell. Samba is now developed
423 by the Samba Team as an Open Source project similar
424 to the way the Linux kernel is developed.</para>
425
426 <para>The ntlm_auth manpage was written by Jelmer Vernooij and
427 Andrew Bartlett.</para>
428</refsect1>
429
430</refentry>
Note: See TracBrowser for help on using the repository browser.