1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % globalentities SYSTEM '../entities/global.entities'> %globalentities;
6 <refentry id="ntlm-auth.1">
9 <refentrytitle>ntlm_auth</refentrytitle>
10 <manvolnum>1</manvolnum>
15 <refname>ntlm_auth</refname>
16 <refpurpose>tool to allow external access to Winbind's NTLM authentication function</refpurpose>
21 <command>ntlm_auth</command>
22 <arg choice="opt">-d debuglevel</arg>
23 <arg choice="opt">-l logdir</arg>
24 <arg choice="opt">-s <smb config file></arg>
29 <title>DESCRIPTION</title>
31 <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
32 <manvolnum>7</manvolnum></citerefentry> suite.</para>
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 indended to be used by other programs (currently
44 <title>OPERATIONAL REQUIREMENTS</title>
47 The <citerefentry><refentrytitle>winbindd</refentrytitle>
48 <manvolnum>8</manvolnum></citerefentry> daemon must be operational
49 for many of these commands to function.</para>
51 <para>Some of these commands also require access to the directory
52 <filename>winbindd_privileged</filename> in
53 <filename>$LOCKDIR</filename>. This should be done either by running
54 this command as root or providing group access
55 to the <filename>winbindd_privileged</filename> directory. For
56 security reasons, this directory should not be world-accessable. </para>
62 <title>OPTIONS</title>
66 <term>--helper-protocol=PROTO</term>
68 Operate as a stdio-based helper. Valid helper protocols are:
72 <term>squid-2.4-basic</term>
74 Server-side helper for use with Squid 2.4's basic (plaintext)
75 authentication. </para>
79 <term>squid-2.5-basic</term>
81 Server-side helper for use with Squid 2.5's basic (plaintext)
82 authentication. </para>
86 <term>squid-2.5-ntlmssp</term>
88 Server-side helper for use with Squid 2.5's NTLMSSP
89 authentication. </para>
90 <para>Requires access to the directory
91 <filename>winbindd_privileged</filename> in
92 <filename>$LOCKDIR</filename>. The protocol used is
93 described here: <ulink
94 url="http://devel.squid-cache.org/ntlm/squid_helper_protocol.html">http://devel.squid-cache.org/ntlm/squid_helper_protocol.html</ulink>.
95 This protocol has been extended to allow the
96 NTLMSSP Negotiate packet to be included as an argument
97 to the <command>YR</command> command. (Thus avoiding
98 loss of information in the protocol exchange).
103 <term>ntlmssp-client-1</term>
105 Cleint-side helper for use with arbitary external
106 programs that may wish to use Samba's NTLMSSP
107 authentication knowlege. </para>
108 <para>This helper is a client, and as such may be run by any
109 user. The protocol used is
110 effectivly the reverse of the previous protocol.
116 <term>gss-spnego</term>
118 Server-side helper that implements GSS-SPNEGO. This
119 uses a protocol that is almost the same as
120 <command>squid-2.5-ntlmssp</command>, but has some
121 subtle differences that are undocumented outside the
122 source at this stage.
124 <para>Requires access to the directory
125 <filename>winbindd_privileged</filename> in
126 <filename>$LOCKDIR</filename>.
132 <term>gss-spnego-client</term>
134 Client-side helper that implements GSS-SPNEGO. This
135 also uses a protocol similar to the above helpers, but
136 is currently undocumented.
142 <term>ntlm-server-1</term>
144 Server-side helper protocol, intended for use by a
145 RADIUS server or the 'winbind' plugin for pppd, for
146 the provision of MSCHAP and MSCHAPv2 authentication.
148 <para>This protocol consists of lines in for form:
149 <command>Parameter: value</command> and <command>Paramter::
150 Base64-encode value</command>. The presence of a single
151 period <command>.</command> indicates that one side has
152 finished supplying data to the other. (Which in turn
153 could cause the helper to authenticate the
156 <para>Curently implemented parameters from the
157 external program to the helper are:</para>
160 <term>Username</term>
162 <listitem><para>The username, expected to be in
163 Samba's <smbconfoption><name>unix charset</name></smbconfoption>.
166 <para><example>Username: bob</example></para>
167 <para><example>Username:: Ym9i</example></para>
168 </listitem></varlistentry>
171 <term>Username</term>
172 <listitem><para>The user's domain, expected to be in
173 Samba's <smbconfoption><name>unix charset</name></smbconfoption>.
176 <para><example>Domain: WORKGROUP</example></para>
177 <para><example>Domain:: V09SS0dST1VQ</example></para>
178 </listitem></varlistentry>
181 <term>Full-Username</term>
182 <listitem><para>The fully qualified username, expected to be in
183 Samba's <smbconfoption><name>unix
184 charset</name></smbconfoption> and qualified with the
185 <smbconfoption><name>winbind separator</name></smbconfoption>.
188 <para><example>Full-Username: WORKGROUP\bob</example></para>
189 <para><example>Full-Username:: V09SS0dST1VQYm9i</example></para>
190 </listitem></varlistentry>
193 <term>LANMAN-Challenge</term>
195 <listitem><para>The 8 byte <command>LANMAN Challenge</command> value,
196 generated randomly by the server, or (in cases such as
197 MSCHAPv2) generated in some way by both the server and
200 <para><example>LANMAN-Challege: 0102030405060708</example></para>
201 </listitem></varlistentry>
204 <term>LANMAN-Response</term>
206 <listitem><para>The 24 byte <command>LANMAN Response</command> value,
207 calculated from the user's password and the supplied
208 <command>LANMAN Challenge</command>. Typically, this
209 is provided over the network by a client wishing to authenticate.
211 <para><example>LANMAN-Response: 010203040506070809101112131415161718192021222324</example></para>
213 </listitem></varlistentry>
216 <term>NT-Response</term>
217 <listitem><para>The >= 24 byte <command>NT Response</command>
218 calculated from the user's password and the supplied
219 <command>LANMAN Challenge</command>. Typically, this is
220 provided over the network by a client wishing to authenticate.
222 <para><example>NT-Response: 010203040506070809101112131415161718192021222324</example></para>
224 </listitem></varlistentry>
227 <term>Password</term>
228 <listitem><para>The user's password. This would be
229 provided by a network client, if the helper is being
230 used in a legacy situation that exposes plaintext
231 passwords in this way.
233 <para><example>Password: samba2</example></para>
234 <para><example>Password:: c2FtYmEy</example></para>
236 </listitem></varlistentry>
239 <term>Request-User-Session-Key</term>
240 <listitem><para>Apon sucessful authenticaiton, return
241 the user session key associated with the login.
243 <para><example>Request-User-Session-Key: Yes</example></para>
245 </listitem></varlistentry>
248 <term>Request-LanMan-Session-Key</term>
249 <listitem><para>Apon sucessful authenticaiton, return
250 the LANMAN session key associated with the login.
252 <para><example>Request-LanMan-Session-Key: Yes</example></para>
254 </listitem></varlistentry>
256 <para><warning>Implementors should take care to base64 encode
257 any data (such as usernames/passwords) that may contain malicous user data, such as
258 a newline. They may also need to decode strings from
259 the helper, which likewise may have been base64 encoded.</warning></para>
269 <term>--username=USERNAME</term>
271 Specify username of user to authenticate
277 <term>--domain=DOMAIN</term>
279 Specify domain of user to authenticate
284 <term>--workstation=WORKSTATION</term>
286 Specify the workstation the user authenticated from
291 <term>--challenge=STRING</term>
292 <listitem><para>NTLM challenge (in HEXADECIMAL)</para>
297 <term>--lm-response=RESPONSE</term>
298 <listitem><para>LM Response to the challenge (in HEXADECIMAL)</para></listitem>
302 <term>--nt-response=RESPONSE</term>
303 <listitem><para>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</para></listitem>
307 <term>--password=PASSWORD</term>
308 <listitem><para>User's plaintext password</para><para>If
309 not specified on the command line, this is prompted for when
312 <para>For the NTLMSSP based server roles, this paramter
313 specifies the expected password, allowing testing without
314 winbindd operational.</para>
319 <term>--request-lm-key</term>
320 <listitem><para>Retreive LM session key</para></listitem>
324 <term>--request-nt-key</term>
325 <listitem><para>Request NT key</para></listitem>
329 <term>--diagnostics</term>
330 <listitem><para>Perform Diagnostics on the authentication
331 chain. Uses the password from <command>--password</command>
332 or prompts for one.</para>
337 <term>--require-membership-of={SID|Name}</term>
338 <listitem><para>Require that a user be a member of specified
339 group (either name or SID) for authentication to succeed.</para>
350 <title>EXAMPLE SETUP</title>
352 <para>To setup ntlm_auth for use by squid 2.5, with both basic and
353 NTLMSSP authentication, the following
354 should be placed in the <filename>squid.conf</filename> file.
356 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
357 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
358 auth_param basic children 5
359 auth_param basic realm Squid proxy-caching web server
360 auth_param basic credentialsttl 2 hours
361 </programlisting></para>
363 <note><para>This example assumes that ntlm_auth has been installed into your
364 path, and that the group permissions on
365 <filename>winbindd_privileged</filename> are as described above.</para></note>
367 <para>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above
368 example, the following should be added to the <filename>squid.conf</filename> file.
370 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
371 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
372 </programlisting></para>
377 <title>TROUBLESHOOTING</title>
379 <para>If you're experiencing problems with authenticating Internet Explorer running
380 under MS Windows 9X or Millenium Edition against ntlm_auth's NTLMSSP authentication
381 helper (--helper-protocol=squid-2.5-ntlmssp), then please read
382 <ulink url="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP">
383 the Microsoft Knowledge Base article #239869 and follow instructions described there</ulink>.
388 <title>VERSION</title>
390 <para>This man page is correct for version 3.0 of the Samba
395 <title>AUTHOR</title>
397 <para>The original Samba software and related utilities
398 were created by Andrew Tridgell. Samba is now developed
399 by the Samba Team as an Open Source project similar
400 to the way the Linux kernel is developed.</para>
402 <para>The ntlm_auth manpage was written by Jelmer Vernooij and
403 Andrew Bartlett.</para>