| 1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>ntlm_auth</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="ntlm-auth.1"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ntlm_auth — tool to allow external access to Winbind's NTLM authentication function</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">ntlm_auth</code> [-d debuglevel] [-l logdir] [-s <smb config file>]</p></div></div><div class="refsect1" lang="en"><a name="id230785"></a><h2>DESCRIPTION</h2><p>This tool is part of the <a href="samba.7.html"><span class="citerefentry"><span class="refentrytitle">samba</span>(7)</span></a> suite.</p><p><span><strong class="command">ntlm_auth</strong></span> is a helper utility that authenticates |
|---|
| 2 | users using NT/LM authentication. It returns 0 if the users is authenticated |
|---|
| 3 | successfully and 1 if access was denied. ntlm_auth uses winbind to access |
|---|
| 4 | the user and authentication data for a domain. This utility |
|---|
| 5 | is only indended to be used by other programs (currently |
|---|
| 6 | <a href="http://www.squid-cache.org/" target="_top">Squid</a> |
|---|
| 7 | and <a href="http://download.samba.org/ftp/unpacked/lorikeet/trunk/mod_ntlm_winbind/" target="_top">mod_ntlm_winbind</a>) |
|---|
| 8 | </p></div><div class="refsect1" lang="en"><a name="id231151"></a><h2>OPERATIONAL REQUIREMENTS</h2><p> |
|---|
| 9 | The <a href="winbindd.8.html"><span class="citerefentry"><span class="refentrytitle">winbindd</span>(8)</span></a> daemon must be operational |
|---|
| 10 | for many of these commands to function.</p><p>Some of these commands also require access to the directory |
|---|
| 11 | <code class="filename">winbindd_privileged</code> in |
|---|
| 12 | <code class="filename">$LOCKDIR</code>. This should be done either by running |
|---|
| 13 | this command as root or providing group access |
|---|
| 14 | to the <code class="filename">winbindd_privileged</code> directory. For |
|---|
| 15 | security reasons, this directory should not be world-accessable. </p></div><div class="refsect1" lang="en"><a name="id231192"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">--helper-protocol=PROTO</span></dt><dd><p> |
|---|
| 16 | Operate as a stdio-based helper. Valid helper protocols are: |
|---|
| 17 | </p><div class="variablelist"><dl><dt><span class="term">squid-2.4-basic</span></dt><dd><p> |
|---|
| 18 | Server-side helper for use with Squid 2.4's basic (plaintext) |
|---|
| 19 | authentication. </p></dd><dt><span class="term">squid-2.5-basic</span></dt><dd><p> |
|---|
| 20 | Server-side helper for use with Squid 2.5's basic (plaintext) |
|---|
| 21 | authentication. </p></dd><dt><span class="term">squid-2.5-ntlmssp</span></dt><dd><p> |
|---|
| 22 | Server-side helper for use with Squid 2.5's NTLMSSP |
|---|
| 23 | authentication. </p><p>Requires access to the directory |
|---|
| 24 | <code class="filename">winbindd_privileged</code> in |
|---|
| 25 | <code class="filename">$LOCKDIR</code>. The protocol used is |
|---|
| 26 | described here: <a href="http://devel.squid-cache.org/ntlm/squid_helper_protocol.html" target="_top">http://devel.squid-cache.org/ntlm/squid_helper_protocol.html</a>. |
|---|
| 27 | This protocol has been extended to allow the |
|---|
| 28 | NTLMSSP Negotiate packet to be included as an argument |
|---|
| 29 | to the <span><strong class="command">YR</strong></span> command. (Thus avoiding |
|---|
| 30 | loss of information in the protocol exchange). |
|---|
| 31 | </p></dd><dt><span class="term">ntlmssp-client-1</span></dt><dd><p> |
|---|
| 32 | Client-side helper for use with arbitary external |
|---|
| 33 | programs that may wish to use Samba's NTLMSSP |
|---|
| 34 | authentication knowlege. </p><p>This helper is a client, and as such may be run by any |
|---|
| 35 | user. The protocol used is |
|---|
| 36 | effectivly the reverse of the previous protocol. A |
|---|
| 37 | <span><strong class="command">YR</strong></span> command (without any arguments) |
|---|
| 38 | starts the authentication exchange. |
|---|
| 39 | </p></dd><dt><span class="term">gss-spnego</span></dt><dd><p> |
|---|
| 40 | Server-side helper that implements GSS-SPNEGO. This |
|---|
| 41 | uses a protocol that is almost the same as |
|---|
| 42 | <span><strong class="command">squid-2.5-ntlmssp</strong></span>, but has some |
|---|
| 43 | subtle differences that are undocumented outside the |
|---|
| 44 | source at this stage. |
|---|
| 45 | </p><p>Requires access to the directory |
|---|
| 46 | <code class="filename">winbindd_privileged</code> in |
|---|
| 47 | <code class="filename">$LOCKDIR</code>. |
|---|
| 48 | </p></dd><dt><span class="term">gss-spnego-client</span></dt><dd><p> |
|---|
| 49 | Client-side helper that implements GSS-SPNEGO. This |
|---|
| 50 | also uses a protocol similar to the above helpers, but |
|---|
| 51 | is currently undocumented. |
|---|
| 52 | </p></dd><dt><span class="term">ntlm-server-1</span></dt><dd><p> |
|---|
| 53 | Server-side helper protocol, intended for use by a |
|---|
| 54 | RADIUS server or the 'winbind' plugin for pppd, for |
|---|
| 55 | the provision of MSCHAP and MSCHAPv2 authentication. |
|---|
| 56 | </p><p>This protocol consists of lines in for form: |
|---|
| 57 | <span><strong class="command">Parameter: value</strong></span> and <span><strong class="command">Paramter:: |
|---|
| 58 | Base64-encode value</strong></span>. The presence of a single |
|---|
| 59 | period <span><strong class="command">.</strong></span> indicates that one side has |
|---|
| 60 | finished supplying data to the other. (Which in turn |
|---|
| 61 | could cause the helper to authenticate the |
|---|
| 62 | user). </p><p>Curently implemented parameters from the |
|---|
| 63 | external program to the helper are:</p><div class="variablelist"><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>Implementors should take care to base64 encode |
|---|
| 64 | any data (such as usernames/passwords) that may contain malicous user data, such as |
|---|
| 65 | a newline. They may also need to decode strings from |
|---|
| 66 | the helper, which likewise may have been base64 encoded.</div><dl><dt><span class="term">Username</span></dt><dd><p>The username, expected to be in |
|---|
| 67 | Samba's <a class="indexterm" name="id230552"></a>unix charset. |
|---|
| 68 | </p><div class="example"><a name="id230560"></a><p class="title"><b>Example 1. </b></p>Username: bob</div><div class="example"><a name="id230565"></a><p class="title"><b>Example 2. </b></p>Username:: Ym9i</div></dd><dt><span class="term">Username</span></dt><dd><p>The user's domain, expected to be in |
|---|
| 69 | Samba's <a class="indexterm" name="id230579"></a>unix charset. |
|---|
| 70 | </p><div class="example"><a name="id230588"></a><p class="title"><b>Example 3. </b></p>Domain: WORKGROUP</div><div class="example"><a name="id230593"></a><p class="title"><b>Example 4. </b></p>Domain:: V09SS0dST1VQ</div></dd><dt><span class="term">Full-Username</span></dt><dd><p>The fully qualified username, expected to be in |
|---|
| 71 | Samba's <a class="indexterm" name="id230606"></a> and qualified with the |
|---|
| 72 | <a class="indexterm" name="id230612"></a>winbind separator. |
|---|
| 73 | </p><div class="example"><a name="id230622"></a><p class="title"><b>Example 5. </b></p>Full-Username: WORKGROUP\bob</div><div class="example"><a name="id230626"></a><p class="title"><b>Example 6. </b></p>Full-Username:: V09SS0dST1VQYm9i</div></dd><dt><span class="term">LANMAN-Challenge</span></dt><dd><p>The 8 byte <span><strong class="command">LANMAN Challenge</strong></span> value, |
|---|
| 74 | generated randomly by the server, or (in cases such as |
|---|
| 75 | MSCHAPv2) generated in some way by both the server and |
|---|
| 76 | the client. |
|---|
| 77 | </p><div class="example"><a name="id271749"></a><p class="title"><b>Example 7. </b></p>LANMAN-Challege: 0102030405060708</div></dd><dt><span class="term">LANMAN-Response</span></dt><dd><p>The 24 byte <span><strong class="command">LANMAN Response</strong></span> value, |
|---|
| 78 | calculated from the user's password and the supplied |
|---|
| 79 | <span><strong class="command">LANMAN Challenge</strong></span>. Typically, this |
|---|
| 80 | is provided over the network by a client wishing to authenticate. |
|---|
| 81 | </p><div class="example"><a name="id271778"></a><p class="title"><b>Example 8. </b></p>LANMAN-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</div></dd><dt><span class="term">NT-Response</span></dt><dd><p>The >= 24 byte <span><strong class="command">NT Response</strong></span> |
|---|
| 82 | calculated from the user's password and the supplied |
|---|
| 83 | <span><strong class="command">LANMAN Challenge</strong></span>. Typically, this is |
|---|
| 84 | provided over the network by a client wishing to authenticate. |
|---|
| 85 | </p><div class="example"><a name="id271808"></a><p class="title"><b>Example 9. </b></p>NT-Response: 0102030405060708090A0B0C0D0E0F101112131415161718</div></dd><dt><span class="term">Password</span></dt><dd><p>The user's password. This would be |
|---|
| 86 | provided by a network client, if the helper is being |
|---|
| 87 | used in a legacy situation that exposes plaintext |
|---|
| 88 | passwords in this way. |
|---|
| 89 | </p><div class="example"><a name="id271826"></a><p class="title"><b>Example 10. </b></p>Password: samba2</div><div class="example"><a name="id271830"></a><p class="title"><b>Example 11. </b></p>Password:: c2FtYmEy</div></dd><dt><span class="term">Request-User-Session-Key</span></dt><dd><p>Apon sucessful authenticaiton, return |
|---|
| 90 | the user session key associated with the login. |
|---|
| 91 | </p><div class="example"><a name="id271847"></a><p class="title"><b>Example 12. </b></p>Request-User-Session-Key: Yes</div></dd><dt><span class="term">Request-LanMan-Session-Key</span></dt><dd><p>Apon sucessful authenticaiton, return |
|---|
| 92 | the LANMAN session key associated with the login. |
|---|
| 93 | </p><div class="example"><a name="id271864"></a><p class="title"><b>Example 13. </b></p>Request-LanMan-Session-Key: Yes</div></dd></dl></div></dd></dl></div></dd><dt><span class="term">--username=USERNAME</span></dt><dd><p> |
|---|
| 94 | Specify username of user to authenticate |
|---|
| 95 | </p></dd><dt><span class="term">--domain=DOMAIN</span></dt><dd><p> |
|---|
| 96 | Specify domain of user to authenticate |
|---|
| 97 | </p></dd><dt><span class="term">--workstation=WORKSTATION</span></dt><dd><p> |
|---|
| 98 | Specify the workstation the user authenticated from |
|---|
| 99 | </p></dd><dt><span class="term">--challenge=STRING</span></dt><dd><p>NTLM challenge (in HEXADECIMAL)</p></dd><dt><span class="term">--lm-response=RESPONSE</span></dt><dd><p>LM Response to the challenge (in HEXADECIMAL)</p></dd><dt><span class="term">--nt-response=RESPONSE</span></dt><dd><p>NT or NTLMv2 Response to the challenge (in HEXADECIMAL)</p></dd><dt><span class="term">--password=PASSWORD</span></dt><dd><p>User's plaintext password</p><p>If |
|---|
| 100 | not specified on the command line, this is prompted for when |
|---|
| 101 | required. </p><p>For the NTLMSSP based server roles, this paramter |
|---|
| 102 | specifies the expected password, allowing testing without |
|---|
| 103 | winbindd operational.</p></dd><dt><span class="term">--request-lm-key</span></dt><dd><p>Retreive LM session key</p></dd><dt><span class="term">--request-nt-key</span></dt><dd><p>Request NT key</p></dd><dt><span class="term">--diagnostics</span></dt><dd><p>Perform Diagnostics on the authentication |
|---|
| 104 | chain. Uses the password from <span><strong class="command">--password</strong></span> |
|---|
| 105 | or prompts for one.</p></dd><dt><span class="term">--require-membership-of={SID|Name}</span></dt><dd><p>Require that a user be a member of specified |
|---|
| 106 | group (either name or SID) for authentication to succeed.</p></dd><dt><span class="term">-V</span></dt><dd><p>Prints the program version number. |
|---|
| 107 | </p></dd><dt><span class="term">-s <configuration file></span></dt><dd><p>The file specified contains the |
|---|
| 108 | configuration details required by the server. The |
|---|
| 109 | information in this file includes server-specific |
|---|
| 110 | information such as what printcap file to use, as well |
|---|
| 111 | as descriptions of all the services that the server is |
|---|
| 112 | to provide. See <code class="filename">smb.conf</code> for more information. |
|---|
| 113 | The default configuration file name is determined at |
|---|
| 114 | compile time.</p></dd><dt><span class="term">-d|--debuglevel=level</span></dt><dd><p><em class="replaceable"><code>level</code></em> is an integer |
|---|
| 115 | from 0 to 10. The default value if this parameter is |
|---|
| 116 | not specified is zero.</p><p>The higher this value, the more detail will be |
|---|
| 117 | logged to the log files about the activities of the |
|---|
| 118 | server. At level 0, only critical errors and serious |
|---|
| 119 | warnings will be logged. Level 1 is a reasonable level for |
|---|
| 120 | day-to-day running - it generates a small amount of |
|---|
| 121 | information about operations carried out.</p><p>Levels above 1 will generate considerable |
|---|
| 122 | amounts of log data, and should only be used when |
|---|
| 123 | investigating a problem. Levels above 3 are designed for |
|---|
| 124 | use only by developers and generate HUGE amounts of log |
|---|
| 125 | data, most of which is extremely cryptic.</p><p>Note that specifying this parameter here will |
|---|
| 126 | override the <a class="indexterm" name="id272086"></a> parameter |
|---|
| 127 | in the <code class="filename">smb.conf</code> file.</p></dd><dt><span class="term">-l|--logfile=logdirectory</span></dt><dd><p>Base directory name for log/debug files. The extension |
|---|
| 128 | <code class="constant">".progname"</code> will be appended (e.g. log.smbclient, |
|---|
| 129 | log.smbd, etc...). The log file is never removed by the client. |
|---|
| 130 | </p></dd><dt><span class="term">-h|--help</span></dt><dd><p>Print a summary of command line options. |
|---|
| 131 | </p></dd></dl></div></div><div class="refsect1" lang="en"><a name="id272131"></a><h2>EXAMPLE SETUP</h2><p>To setup ntlm_auth for use by squid 2.5, with both basic and |
|---|
| 132 | NTLMSSP authentication, the following |
|---|
| 133 | should be placed in the <code class="filename">squid.conf</code> file. |
|---|
| 134 | </p><pre class="programlisting"> |
|---|
| 135 | auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp |
|---|
| 136 | auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic |
|---|
| 137 | auth_param basic children 5 |
|---|
| 138 | auth_param basic realm Squid proxy-caching web server |
|---|
| 139 | auth_param basic credentialsttl 2 hours |
|---|
| 140 | </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This example assumes that ntlm_auth has been installed into your |
|---|
| 141 | path, and that the group permissions on |
|---|
| 142 | <code class="filename">winbindd_privileged</code> are as described above.</p></div><p>To setup ntlm_auth for use by squid 2.5 with group limitation in addition to the above |
|---|
| 143 | example, the following should be added to the <code class="filename">squid.conf</code> file. |
|---|
| 144 | </p><pre class="programlisting"> |
|---|
| 145 | auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users' |
|---|
| 146 | auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users' |
|---|
| 147 | </pre></div><div class="refsect1" lang="en"><a name="id272183"></a><h2>TROUBLESHOOTING</h2><p>If you're experiencing problems with authenticating Internet Explorer running |
|---|
| 148 | under MS Windows 9X or Millenium Edition against ntlm_auth's NTLMSSP authentication |
|---|
| 149 | helper (--helper-protocol=squid-2.5-ntlmssp), then please read |
|---|
| 150 | <a href="http://support.microsoft.com/support/kb/articles/Q239/8/69.ASP" target="_top"> |
|---|
| 151 | the Microsoft Knowledge Base article #239869 and follow instructions described there</a>. |
|---|
| 152 | </p></div><div class="refsect1" lang="en"><a name="id272202"></a><h2>VERSION</h2><p>This man page is correct for version 3.0 of the Samba |
|---|
| 153 | suite.</p></div><div class="refsect1" lang="en"><a name="id272212"></a><h2>AUTHOR</h2><p>The original Samba software and related utilities |
|---|
| 154 | were created by Andrew Tridgell. Samba is now developed |
|---|
| 155 | by the Samba Team as an Open Source project similar |
|---|
| 156 | to the way the Linux kernel is developed.</p><p>The ntlm_auth manpage was written by Jelmer Vernooij and |
|---|
| 157 | Andrew Bartlett.</p></div></div></body></html> |
|---|
