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 <smb config file></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> 410