docs/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 </refmeta>
   9
  10
  11 <refnamediv>
  12         <refname>ntlm_auth</refname>
  13         <refpurpose>tool to allow external access to Winbind's NTLM authentication function</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17         <cmdsynopsis>
  18                 <command>ntlm_auth</command>
  19                 <arg choice="opt">-d debuglevel</arg>
  20                 <arg choice="opt">-l logdir</arg>
  21                 <arg choice="opt">-s &lt;smb config file&gt;</arg>
  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 indended 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>Curently implemented parameters from the
 157                 external program to the helper are:</para>
 158                 <variablelist>
 159                   <varlistentry>
 160                   <term>Username</term>
 161
 162                 <listitem><para>The username, expected to be in
 163                 Samba's <smbconfoption name="unix charset"/>.
 164                 </para>
 165
 166                       <para><example>Username: bob</example></para>
 167                       <para><example>Username:: Ym9i</example></para>
 168                     </listitem></varlistentry>
 169
 170                   <varlistentry>
 171                   <term>Username</term>
 172                 <listitem><para>The user's domain, expected to be in
 173                 Samba's <smbconfoption name="unix charset"/>.
 174                 </para>
 175
 176                       <para><example>Domain: WORKGROUP</example></para>
 177                       <para><example>Domain:: V09SS0dST1VQ</example></para>
 178                     </listitem></varlistentry>
 179
 180                   <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"/>.
 186                 </para>
 187
 188                       <para><example>Full-Username: WORKGROUP\bob</example></para>
 189                       <para><example>Full-Username:: V09SS0dST1VQYm9i</example></para>
 190                     </listitem></varlistentry>
 191
 192                   <varlistentry>
 193                   <term>LANMAN-Challenge</term>
 194
 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
 198                 the client.
 199                 </para>
 200                       <para><example>LANMAN-Challege: 0102030405060708</example></para>
 201                     </listitem></varlistentry>
 202
 203                   <varlistentry>
 204                   <term>LANMAN-Response</term>
 205
 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.
 210                 </para>
 211                       <para><example>LANMAN-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</example></para>
 212
 213                     </listitem></varlistentry>
 214
 215                   <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.
 221                  </para>
 222                       <para><example>NT-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</example></para>
 223
 224                     </listitem></varlistentry>
 225
 226                   <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.
 232                  </para>
 233                       <para><example>Password: samba2</example></para>
 234                       <para><example>Password:: c2FtYmEy</example></para>
 235
 236                     </listitem></varlistentry>
 237
 238                   <varlistentry>
 239                   <term>Request-User-Session-Key</term>
 240                 <listitem><para>Apon sucessful authenticaiton, return
 241                 the user session key associated with the login.
 242                  </para>
 243                       <para><example>Request-User-Session-Key: Yes</example></para>
 244
 245                     </listitem></varlistentry>
 246
 247                   <varlistentry>
 248                   <term>Request-LanMan-Session-Key</term>
 249                 <listitem><para>Apon sucessful authenticaiton, return
 250                 the LANMAN session key associated with the login.
 251                  </para>
 252                       <para><example>Request-LanMan-Session-Key: Yes</example></para>
 253
 254                     </listitem></varlistentry>
 255
 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>
 260         </variablelist>
 261
 262                 </listitem>
 263                 </varlistentry>
 264         </variablelist>
 265         </listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term>--username=USERNAME</term>
 270         <listitem><para>
 271         Specify username of user to authenticate
 272         </para></listitem>
 273
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term>--domain=DOMAIN</term>
 278         <listitem><para>
 279         Specify domain of user to authenticate
 280         </para></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term>--workstation=WORKSTATION</term>
 285         <listitem><para>
 286         Specify the workstation the user authenticated from
 287         </para></listitem>
 288       </varlistentry>
 289
 290         <varlistentry>
 291         <term>--challenge=STRING</term>
 292         <listitem><para>NTLM challenge (in HEXADECIMAL)</para>
 293         </listitem>
 294         </varlistentry>
 295
 296         <varlistentry>
 297         <term>--lm-response=RESPONSE</term>
 298         <listitem><para>LM Response to the challenge (in HEXADECIMAL)</para></listitem>
 299         </varlistentry>
 300
 301         <varlistentry>
 302         <term>--nt-response=RESPONSE</term>
 303         <listitem><para>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</para></listitem>
 304         </varlistentry>
 305
 306         <varlistentry>
 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
 310         required.  </para>
 311
 312           <para>For the NTLMSSP based server roles, this parameter
 313           specifies the expected password, allowing testing without
 314           winbindd operational.</para>
 315         </listitem>
 316         </varlistentry>
 317
 318         <varlistentry>
 319         <term>--request-lm-key</term>
 320         <listitem><para>Retreive LM session key</para></listitem>
 321         </varlistentry>
 322
 323         <varlistentry>
 324         <term>--request-nt-key</term>
 325         <listitem><para>Request NT key</para></listitem>
 326         </varlistentry>
 327
 328       <varlistentry>
 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>
 333         </listitem>
 334         </varlistentry>
 335
 336         <varlistentry>
 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>
 340             </listitem>
 341         </varlistentry>
 342
 343           &stdarg.server.debug;
 344           &popt.common.samba;
 345           &stdarg.help;
 346
 347         </variablelist>
 348 </refsect1>
 349
 350 <refsect1>
 351         <title>EXAMPLE SETUP</title>
 352
 353         <para>To setup ntlm_auth for use by squid 2.5, with both basic and
 354         NTLMSSP authentication, the following
 355         should be placed in the <filename>squid.conf</filename> file.
 356 <programlisting>
 357 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
 358 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
 359 auth_param basic children 5
 360 auth_param basic realm Squid proxy-caching web server
 361 auth_param basic credentialsttl 2 hours
 362 </programlisting></para>
 363
 364 <note><para>This example assumes that ntlm_auth has been installed into your
 365       path, and that the group permissions on
 366       <filename>winbindd_privileged</filename> are as described above.</para></note>
 367
 368         <para>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above
 369         example, the following should be added to the <filename>squid.conf</filename> file.
 370 <programlisting>
 371 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
 372 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
 373 </programlisting></para>
 374
 375 </refsect1>
 376
 377 <refsect1>
 378         <title>TROUBLESHOOTING</title>
 379
 380         <para>If you're experiencing problems with authenticating Internet Explorer running
 381         under MS Windows 9X or Millenium Edition against ntlm_auth's NTLMSSP authentication
 382         helper (--helper-protocol=squid-2.5-ntlmssp), then please read
 383         <ulink url="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP">
 384         the Microsoft Knowledge Base article #239869 and follow instructions described there</ulink>.
 385         </para>
 386 </refsect1>
 387
 388 <refsect1>
 389         <title>VERSION</title>
 390
 391         <para>This man page is correct for version 3.0 of the Samba
 392         suite.</para>
 393 </refsect1>
 394
 395 <refsect1>
 396         <title>AUTHOR</title>
 397
 398         <para>The original Samba software and related utilities
 399         were created by Andrew Tridgell. Samba is now developed
 400         by the Samba Team as an Open Source project similar
 401         to the way the Linux kernel is developed.</para>
 402
 403         <para>The ntlm_auth manpage was written by Jelmer Vernooij and
 404         Andrew Bartlett.</para>
 405 </refsect1>
 406
 407 </refentry>