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">&doc.version;</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 authentication, 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 authentication, 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 malicious 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         &popt.autohelp;
 395         &cmdline.common.debug.client;
 396         &cmdline.common.config.client;
 397         &cmdline.common.option;
 398         &cmdline.version;
 399
 400         </variablelist>
 401 </refsect1>
 402
 403 <refsect1>
 404         <title>EXAMPLE SETUP</title>
 405
 406         <para>To setup ntlm_auth for use by squid 2.5, with both basic and
 407         NTLMSSP authentication, the following
 408         should be placed in the <filename>squid.conf</filename> file.
 409 <programlisting>
 410 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
 411 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
 412 auth_param basic children 5
 413 auth_param basic realm Squid proxy-caching web server
 414 auth_param basic credentialsttl 2 hours
 415 </programlisting></para>
 416
 417 <note><para>This example assumes that ntlm_auth has been installed into your
 418       path, and that the group permissions on
 419       <filename>winbindd_privileged</filename> are as described above.</para></note>
 420
 421         <para>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above
 422         example, the following should be added to the <filename>squid.conf</filename> file.
 423 <programlisting>
 424 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
 425 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
 426 </programlisting></para>
 427
 428 </refsect1>
 429
 430 <refsect1>
 431         <title>TROUBLESHOOTING</title>
 432
 433         <para>If you're experiencing problems with authenticating Internet Explorer running
 434         under MS Windows 9X or Millennium Edition against ntlm_auth's NTLMSSP authentication
 435         helper (--helper-protocol=squid-2.5-ntlmssp), then please read
 436         <ulink url="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP">
 437         the Microsoft Knowledge Base article #239869 and follow instructions described there</ulink>.
 438         </para>
 439 </refsect1>
 440
 441 <refsect1>
 442         <title>VERSION</title>
 443
 444         <para>This man page is part of version &doc.version; of the Samba
 445         suite.</para>
 446 </refsect1>
 447
 448 <refsect1>
 449         <title>AUTHOR</title>
 450
 451         <para>The original Samba software and related utilities
 452         were created by Andrew Tridgell. Samba is now developed
 453         by the Samba Team as an Open Source project similar
 454         to the way the Linux kernel is developed.</para>
 455
 456         <para>The ntlm_auth manpage was written by Jelmer Vernooij and
 457         Andrew Bartlett.</para>
 458 </refsect1>
 459
 460 </refentry>