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.1</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>Currently implemented parameters from the
 160                 external program to the helper are:</para>
 161                 <variablelist>
 162                   <varlistentry>
 163                     <term>Username</term>
 164                     <listitem><para>The username, expected to be in
 165                     Samba's <smbconfoption name="unix charset"/>.
 166                     </para>
 167                     <varlistentry>
 168                       <term>Examples:</term>
 169                       <para>Username: bob</para>
 170                       <para>Username:: Ym9i</para>
 171                     </varlistentry>
 172                     </listitem>
 173                   </varlistentry>
 174
 175                   <varlistentry>
 176                     <term>NT-Domain</term>
 177                     <listitem><para>The user's domain, expected to be in
 178                     Samba's <smbconfoption name="unix charset"/>.
 179                     </para>
 180
 181                     <varlistentry>
 182                       <term>Examples:</term>
 183                       <para>NT-Domain: WORKGROUP</para>
 184                       <para>NT-Domain:: V09SS0dST1VQ</para>
 185                     </varlistentry>
 186                     </listitem>
 187                   </varlistentry>
 188
 189                   <varlistentry>
 190                     <term>Full-Username</term>
 191                     <listitem><para>The fully qualified username, expected to be
 192                     in Samba's <smbconfoption name="unix charset"/> and qualified
 193                     with the <smbconfoption name="winbind separator"/>.</para>
 194                     <varlistentry>
 195                       <term>Examples:</term>
 196                       <para>Full-Username: WORKGROUP\bob</para>
 197                       <para>Full-Username:: V09SS0dST1VQYm9i</para>
 198                     </varlistentry>
 199                     </listitem>
 200                   </varlistentry>
 201
 202                   <varlistentry>
 203                     <term>LANMAN-Challenge</term>
 204                     <listitem><para>The 8 byte <command>LANMAN Challenge</command>
 205                     value, generated randomly by the server, or (in cases such
 206                     as MSCHAPv2) generated in some way by both the server and
 207                     the client.</para>
 208                     <varlistentry>
 209                       <term>Examples:</term>
 210                       <para>LANMAN-Challenge: 0102030405060708</para>
 211                     </varlistentry>
 212                     </listitem>
 213                   </varlistentry>
 214
 215                   <varlistentry>
 216                     <term>LANMAN-Response</term>
 217                     <listitem><para>The 24 byte <command>LANMAN Response</command> value,
 218                     calculated from the user's password and the supplied
 219                     <command>LANMAN Challenge</command>.  Typically, this
 220                     is provided over the network by a client wishing to authenticate.
 221                     </para>
 222                     <varlistentry>
 223                       <term>Examples:</term>
 224                       <para>LANMAN-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</para>
 225                     </varlistentry>
 226                     </listitem>
 227                   </varlistentry>
 228
 229                   <varlistentry>
 230                     <term>NT-Response</term>
 231                     <listitem><para>The >= 24 byte <command>NT Response</command>
 232                     calculated from the user's password and the supplied
 233                     <command>LANMAN Challenge</command>.  Typically, this is
 234                     provided over the network by a client wishing to authenticate.
 235                     </para>
 236                     <varlistentry>
 237                       <term>Examples:</term>
 238                       <para>NT-Response: 0102030405060708090A0B0C0D0E0F10111213141516171</para>
 239                       </varlistentry>
 240                     </listitem>
 241                   </varlistentry>
 242
 243                   <varlistentry>
 244                     <term>Password</term>
 245                     <listitem><para>The user's password.  This would be
 246                     provided by a network client, if the helper is being
 247                     used in a legacy situation that exposes plaintext
 248                     passwords in this way.</para>
 249                     <varlistentry>
 250                       <term>Examples:</term>
 251                       <para>Password: samba2</para>
 252                       <para>Password:: c2FtYmEy</para>
 253                     </varlistentry>
 254                     </listitem>
 255                   </varlistentry>
 256
 257                   <varlistentry>
 258                     <term>Request-User-Session-Key</term>
 259                     <listitem><para>Upon successful authenticaiton, return
 260                     the user session key associated with the login.</para>
 261                     <varlistentry>
 262                       <term>Examples:</term>
 263                       <para>Request-User-Session-Key: Yes</para>
 264                     </varlistentry>
 265                     </listitem>
 266                   </varlistentry>
 267
 268                   <varlistentry>
 269                     <term>Request-LanMan-Session-Key</term>
 270                     <listitem><para>Upon successful authenticaiton, return
 271                     the LANMAN session key associated with the login.
 272                     </para>
 273                     <varlistentry>
 274                       <term>Examples:</term>
 275                       <para>Request-LanMan-Session-Key: Yes</para>
 276                     </varlistentry>
 277                     </listitem>
 278                   </varlistentry>
 279
 280                 </variablelist>
 281                 </listitem>
 282                 </varlistentry>
 283                 </variablelist>
 284                   <warning><para>Implementers should take care to base64 encode
 285                   any data (such as usernames/passwords) that may contain malicous user data, such as
 286                   a newline. They may also need to decode strings from
 287                   the helper, which likewise may have been base64 encoded.</para></warning>
 288                 </listitem>
 289       </varlistentry>
 290
 291       <varlistentry>
 292         <term>--username=USERNAME</term>
 293         <listitem><para>
 294         Specify username of user to authenticate
 295         </para></listitem>
 296
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term>--domain=DOMAIN</term>
 301         <listitem><para>
 302         Specify domain of user to authenticate
 303         </para></listitem>
 304       </varlistentry>
 305
 306       <varlistentry>
 307         <term>--workstation=WORKSTATION</term>
 308         <listitem><para>
 309         Specify the workstation the user authenticated from
 310         </para></listitem>
 311       </varlistentry>
 312
 313         <varlistentry>
 314         <term>--challenge=STRING</term>
 315         <listitem><para>NTLM challenge (in HEXADECIMAL)</para>
 316         </listitem>
 317         </varlistentry>
 318
 319         <varlistentry>
 320         <term>--lm-response=RESPONSE</term>
 321         <listitem><para>LM Response to the challenge (in HEXADECIMAL)</para></listitem>
 322         </varlistentry>
 323
 324         <varlistentry>
 325         <term>--nt-response=RESPONSE</term>
 326         <listitem><para>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</para></listitem>
 327         </varlistentry>
 328
 329         <varlistentry>
 330         <term>--password=PASSWORD</term>
 331         <listitem><para>User's plaintext password</para><para>If
 332         not specified on the command line, this is prompted for when
 333         required.  </para>
 334
 335           <para>For the NTLMSSP based server roles, this parameter
 336           specifies the expected password, allowing testing without
 337           winbindd operational.</para>
 338         </listitem>
 339         </varlistentry>
 340
 341         <varlistentry>
 342         <term>--request-lm-key</term>
 343         <listitem><para>Retrieve LM session key</para></listitem>
 344         </varlistentry>
 345
 346         <varlistentry>
 347         <term>--request-nt-key</term>
 348         <listitem><para>Request NT key</para></listitem>
 349         </varlistentry>
 350
 351       <varlistentry>
 352         <term>--diagnostics</term>
 353         <listitem><para>Perform Diagnostics on the authentication
 354         chain.  Uses the password from <command>--password</command>
 355         or prompts for one.</para>
 356         </listitem>
 357         </varlistentry>
 358
 359         <varlistentry>
 360             <term>--require-membership-of={SID|Name}</term>
 361             <listitem><para>Require that a user be a member of specified
 362             group (either name or SID) for authentication to succeed.</para>
 363             </listitem>
 364         </varlistentry>
 365
 366           &stdarg.server.debug;
 367           &popt.common.samba;
 368           &stdarg.help;
 369
 370         </variablelist>
 371 </refsect1>
 372
 373 <refsect1>
 374         <title>EXAMPLE SETUP</title>
 375
 376         <para>To setup ntlm_auth for use by squid 2.5, with both basic and
 377         NTLMSSP authentication, the following
 378         should be placed in the <filename>squid.conf</filename> file.
 379 <programlisting>
 380 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
 381 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
 382 auth_param basic children 5
 383 auth_param basic realm Squid proxy-caching web server
 384 auth_param basic credentialsttl 2 hours
 385 </programlisting></para>
 386
 387 <note><para>This example assumes that ntlm_auth has been installed into your
 388       path, and that the group permissions on
 389       <filename>winbindd_privileged</filename> are as described above.</para></note>
 390
 391         <para>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above
 392         example, the following should be added to the <filename>squid.conf</filename> file.
 393 <programlisting>
 394 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
 395 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
 396 </programlisting></para>
 397
 398 </refsect1>
 399
 400 <refsect1>
 401         <title>TROUBLESHOOTING</title>
 402
 403         <para>If you're experiencing problems with authenticating Internet Explorer running
 404         under MS Windows 9X or Millennium Edition against ntlm_auth's NTLMSSP authentication
 405         helper (--helper-protocol=squid-2.5-ntlmssp), then please read
 406         <ulink url="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP">
 407         the Microsoft Knowledge Base article #239869 and follow instructions described there</ulink>.
 408         </para>
 409 </refsect1>
 410
 411 <refsect1>
 412         <title>VERSION</title>
 413
 414         <para>This man page is correct for version 3 of the Samba
 415         suite.</para>
 416 </refsect1>
 417
 418 <refsect1>
 419         <title>AUTHOR</title>
 420
 421         <para>The original Samba software and related utilities
 422         were created by Andrew Tridgell. Samba is now developed
 423         by the Samba Team as an Open Source project similar
 424         to the way the Linux kernel is developed.</para>
 425
 426         <para>The ntlm_auth manpage was written by Jelmer Vernooij and
 427         Andrew Bartlett.</para>
 428 </refsect1>
 429
 430 </refentry>