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