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

Last change on this file was 478, checked in by Silvan Scherrer, 15 years ago

Samba 3.5: vendor update to 3.5.4
File size: 14.5 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.5</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>Curently implemented parameters from the
160 external program to the helper are:</para>
161 <variablelist>
162 <varlistentry>
163 <term>Username</term>
164
165 <listitem><para>The username, expected to be in
166 Samba's <smbconfoption name="unix charset"/>.
167 </para>
168
169 <para><example>Username: bob</example></para>
170 <para><example>Username:: Ym9i</example></para>
171 </listitem></varlistentry>
172
173 <varlistentry>
174 <term>NT-Domain</term>
175 <listitem><para>The user's domain, expected to be in
176 Samba's <smbconfoption name="unix charset"/>.
177 </para>
178
179 <para><example>NT-Domain: WORKGROUP</example></para>
180 <para><example>NT-Domain:: V09SS0dST1VQ</example></para>
181 </listitem></varlistentry>
182
183 <varlistentry>
184 <term>Full-Username</term>
185 <listitem><para>The fully qualified username, expected to be in
186 Samba's <smbconfoption name="unix charset"/> and qualified with the
187 <smbconfoption name="winbind separator"/>.
188 </para>
189
190 <para><example>Full-Username: WORKGROUP\bob</example></para>
191 <para><example>Full-Username:: V09SS0dST1VQYm9i</example></para>
192 </listitem></varlistentry>
193
194 <varlistentry>
195 <term>LANMAN-Challenge</term>
196
197 <listitem><para>The 8 byte <command>LANMAN Challenge</command> value,
198 generated randomly by the server, or (in cases such as
199 MSCHAPv2) generated in some way by both the server and
200 the client.
201 </para>
202 <para><example>LANMAN-Challege: 0102030405060708</example></para>
203 </listitem></varlistentry>
204
205 <varlistentry>
206 <term>LANMAN-Response</term>
207
208 <listitem><para>The 24 byte <command>LANMAN Response</command> value,
209 calculated from the user's password and the supplied
210 <command>LANMAN Challenge</command>. Typically, this
211 is provided over the network by a client wishing to authenticate.
212 </para>
213 <para><example>LANMAN-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</example></para>
214
215 </listitem></varlistentry>
216
217 <varlistentry>
218 <term>NT-Response</term>
219 <listitem><para>The >= 24 byte <command>NT Response</command>
220 calculated from the user's password and the supplied
221 <command>LANMAN Challenge</command>. Typically, this is
222 provided over the network by a client wishing to authenticate.
223 </para>
224 <para><example>NT-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</example></para>
225
226 </listitem></varlistentry>
227
228 <varlistentry>
229 <term>Password</term>
230 <listitem><para>The user's password. This would be
231 provided by a network client, if the helper is being
232 used in a legacy situation that exposes plaintext
233 passwords in this way.
234 </para>
235 <para><example>Password: samba2</example></para>
236 <para><example>Password:: c2FtYmEy</example></para>
237
238 </listitem></varlistentry>
239
240 <varlistentry>
241 <term>Request-User-Session-Key</term>
242 <listitem><para>Apon sucessful authenticaiton, return
243 the user session key associated with the login.
244 </para>
245 <para><example>Request-User-Session-Key: Yes</example></para>
246
247 </listitem></varlistentry>
248
249 <varlistentry>
250 <term>Request-LanMan-Session-Key</term>
251 <listitem><para>Apon sucessful authenticaiton, return
252 the LANMAN session key associated with the login.
253 </para>
254 <para><example>Request-LanMan-Session-Key: Yes</example></para>
255
256 </listitem></varlistentry>
257
258 <para><warning>Implementors should take care to base64 encode
259 any data (such as usernames/passwords) that may contain malicous user data, such as
260 a newline. They may also need to decode strings from
261 the helper, which likewise may have been base64 encoded.</warning></para>
262 </variablelist>
263
264 </listitem>
265 </varlistentry>
266 </variablelist>
267 </listitem>
268 </varlistentry>
269
270 <varlistentry>
271 <term>--username=USERNAME</term>
272 <listitem><para>
273 Specify username of user to authenticate
274 </para></listitem>
275
276 </varlistentry>
277
278 <varlistentry>
279 <term>--domain=DOMAIN</term>
280 <listitem><para>
281 Specify domain of user to authenticate
282 </para></listitem>
283 </varlistentry>
284
285 <varlistentry>
286 <term>--workstation=WORKSTATION</term>
287 <listitem><para>
288 Specify the workstation the user authenticated from
289 </para></listitem>
290 </varlistentry>
291
292 <varlistentry>
293 <term>--challenge=STRING</term>
294 <listitem><para>NTLM challenge (in HEXADECIMAL)</para>
295 </listitem>
296 </varlistentry>
297
298 <varlistentry>
299 <term>--lm-response=RESPONSE</term>
300 <listitem><para>LM Response to the challenge (in HEXADECIMAL)</para></listitem>
301 </varlistentry>
302
303 <varlistentry>
304 <term>--nt-response=RESPONSE</term>
305 <listitem><para>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</para></listitem>
306 </varlistentry>
307
308 <varlistentry>
309 <term>--password=PASSWORD</term>
310 <listitem><para>User's plaintext password</para><para>If
311 not specified on the command line, this is prompted for when
312 required. </para>
313
314 <para>For the NTLMSSP based server roles, this parameter
315 specifies the expected password, allowing testing without
316 winbindd operational.</para>
317 </listitem>
318 </varlistentry>
319
320 <varlistentry>
321 <term>--request-lm-key</term>
322 <listitem><para>Retreive LM session key</para></listitem>
323 </varlistentry>
324
325 <varlistentry>
326 <term>--request-nt-key</term>
327 <listitem><para>Request NT key</para></listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term>--diagnostics</term>
332 <listitem><para>Perform Diagnostics on the authentication
333 chain. Uses the password from <command>--password</command>
334 or prompts for one.</para>
335 </listitem>
336 </varlistentry>
337
338 <varlistentry>
339 <term>--require-membership-of={SID|Name}</term>
340 <listitem><para>Require that a user be a member of specified
341 group (either name or SID) for authentication to succeed.</para>
342 </listitem>
343 </varlistentry>
344
345 &stdarg.server.debug;
346 &popt.common.samba;
347 &stdarg.help;
348
349 </variablelist>
350</refsect1>
351
352<refsect1>
353 <title>EXAMPLE SETUP</title>
354
355 <para>To setup ntlm_auth for use by squid 2.5, with both basic and
356 NTLMSSP authentication, the following
357 should be placed in the <filename>squid.conf</filename> file.
358<programlisting>
359auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
360auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
361auth_param basic children 5
362auth_param basic realm Squid proxy-caching web server
363auth_param basic credentialsttl 2 hours
364</programlisting></para>
365
366<note><para>This example assumes that ntlm_auth has been installed into your
367 path, and that the group permissions on
368 <filename>winbindd_privileged</filename> are as described above.</para></note>
369
370 <para>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above
371 example, the following should be added to the <filename>squid.conf</filename> file.
372<programlisting>
373auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
374auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
375</programlisting></para>
376
377</refsect1>
378
379<refsect1>
380 <title>TROUBLESHOOTING</title>
381
382 <para>If you're experiencing problems with authenticating Internet Explorer running
383 under MS Windows 9X or Millenium Edition against ntlm_auth's NTLMSSP authentication
384 helper (--helper-protocol=squid-2.5-ntlmssp), then please read
385 <ulink url="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP">
386 the Microsoft Knowledge Base article #239869 and follow instructions described there</ulink>.
387 </para>
388</refsect1>
389
390<refsect1>
391 <title>VERSION</title>
392
393 <para>This man page is correct for version 3 of the Samba
394 suite.</para>
395</refsect1>
396
397<refsect1>
398 <title>AUTHOR</title>
399
400 <para>The original Samba software and related utilities
401 were created by Andrew Tridgell. Samba is now developed
402 by the Samba Team as an Open Source project similar
403 to the way the Linux kernel is developed.</para>
404
405 <para>The ntlm_auth manpage was written by Jelmer Vernooij and
406 Andrew Bartlett.</para>
407</refsect1>
408
409</refentry>
Note: See TracBrowser for help on using the repository browser.