← Back to branch summary

~zulcss/samba/server-dailies-3.4

« back to all changes in this revision

Viewing changes to docs-xml/manpages-3/ntlm_auth.1.xml

  • Committer: Chuck Short
  • Date: 2010-09-28 20:38:39 UTC
  • Revision ID: zulcss@ubuntu.com-20100928203839-pgjulytsi9ue63x1
Initial version

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs-xml/manpages-3/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">3.4</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>Username</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>Domain: WORKGROUP</example></para>
 
180
                      <para><example>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>
 
359
auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
 
360
auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
 
361
auth_param basic children 5
 
362
auth_param basic realm Squid proxy-caching web server
 
363
auth_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>
 
373
auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
 
374
auth_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>