Provided by: winbind_3.0.28a-1ubuntu4_i386 bug

NAME

       ntlm_auth   -   tool   to  allow  external  access  to  Winbind’s  NTLM
       authentication function

SYNOPSIS

       ntlm_auth [-ddebuglevel] [-llogdir] [-s<smbconfigfile>]

DESCRIPTION

       This tool is part of the samba(7) suite.

       ntlm_auth is a helper utility  that  authenticates  users  using  NT/LM
       authentication. It returns 0 if the users is authenticated successfully
       and 1 if access was denied. ntlm_auth uses winbind to access  the  user
       and  authentication data for a domain. This utility is only indended to
       be used by other programs (currently Squid and mod_ntlm_winbind)

OPERATIONAL REQUIREMENTS

       The winbindd(8) daemon must be operational for many of  these  commands
       to function.

       Some   of   these   commands  also  require  access  to  the  directory
       winbindd_privileged in /var/run/samba. This should be  done  either  by
       running  this  command  as  root  or  providing  group  access  to  the
       winbindd_privileged directory. For  security  reasons,  this  directory
       should not be world-accessable.

OPTIONS

       --helper-protocol=PROTO
          Operate as a stdio-based helper. Valid helper protocols are:

             squid-2.4-basic
                Server-side  helper for use with Squid 2.4’s basic (plaintext)
                authentication.

             squid-2.5-basic
                Server-side helper for use with Squid 2.5’s basic  (plaintext)
                authentication.

             squid-2.5-ntlmssp
                Server-side   helper   for   use   with  Squid  2.5’s  NTLMSSP
                authentication.

                Requires  access  to  the  directory  winbindd_privileged   in
                /var/run/samba.   The   protocol   used   is  described  here:
                http://devel.squid-cache.org/ntlm/squid_helper_protocol.html.
                This protocol has been extended to allow the NTLMSSP Negotiate
                packet to be included as an argument to the YR command.  (Thus
                avoiding loss of information in the protocol exchange).

             ntlmssp-client-1
                Client-side  helper  for  use  with arbitary external programs
                that may wish to use Samba’s NTLMSSP authentication  knowlege.

                This  helper  is a client, and as such may be run by any user.
                The protocol used is effectivly the reverse  of  the  previous
                protocol.  A  YR  command  (without  any arguments) starts the
                authentication exchange.

             gss-spnego
                Server-side helper that implements  GSS-SPNEGO.  This  uses  a
                protocol that is almost the same as squid-2.5-ntlmssp, but has
                some subtle differences  that  are  undocumented  outside  the
                source at this stage.

                Requires   access  to  the  directory  winbindd_privileged  in
                /var/run/samba.

             gss-spnego-client
                Client-side helper that implements GSS-SPNEGO. This also  uses
                a  protocol  similar  to  the  above helpers, but is currently
                undocumented.

             ntlm-server-1
                Server-side helper protocol, intended  for  use  by  a  RADIUS
                server  or the ’winbind’ plugin for pppd, for the provision of
                MSCHAP and MSCHAPv2 authentication.

                This protocol consists of lines in for form: Parameter:  value
                and  Paramter::  Base64-encode value. The presence of a single
                period indicates that one side has finished supplying data  to
                the   other.   (Which  in  turn  could  cause  the  helper  to
                authenticate the user).

                Curently implemented parameters from the external  program  to
                the helper are:

                   Username
                      The username, expected to be in Samba’s unix charset.

                      Example1.Username: bob

                      Example2.Username:: Ym9i

                   Username
                      The  user’s  domain,  expected  to  be  in  Samba’s unix
                      charset.

                      Example3.Domain: WORKGROUP

                      Example4.Domain:: V09SS0dST1VQ

                   Full-Username
                      The fully qualified username, expected to be in Samba’s

                      and qualified with the winbind separator.

                      Example5.Full-Username: WORKGROUPb

                      Example6.Full-Username:: V09SS0dST1VQYm9i

                   LANMAN-Challenge
                      The 8 byte LANMAN Challenge value, generated randomly by
                      the  server, or (in cases such as MSCHAPv2) generated in
                      some way by both the server and the client.

                      Example7.LANMAN-Challege: 0102030405060708

                   LANMAN-Response
                      The 24 byte LANMAN Response value, calculated  from  the
                      user’s  password  and  the  supplied  LANMAN  Challenge.
                      Typically, this is provided over the network by a client
                      wishing to authenticate.

                      Example8.LANMAN-Response:
                      0102030405060708090A0B0C0D0E0F101112131415161718

                   NT-Response
                      The >= 24 byte NT Response calculated  from  the  user’s
                      password  and  the supplied LANMAN Challenge. Typically,
                      this is provided over the network by a client wishing to
                      authenticate.

                      Example9.NT-Response:
                      0102030405060708090A0B0C0D0E0F101112131415161718

                   Password
                      The user’s password. This would be provided by a network
                      client,  if  the  helper  is  being  used  in  a  legacy
                      situation that exposes plaintext passwords in this  way.

                      Example10.Password: samba2

                      Example11.Password:: c2FtYmEy

                   Request-User-Session-Key
                      Apon  sucessful  authenticaiton, return the user session
                      key associated with the login.

                      Example12.Request-User-Session-Key: Yes

                   Request-LanMan-Session-Key
                      Apon sucessful authenticaiton, return the LANMAN session
                      key associated with the login.

                      Example13.Request-LanMan-Session-Key: Yes

                   Warning
                   Implementors    should   take   care   to   base64   encode
                             any data (such as usernames/passwords)  that  may
                   contain  malicous  user  data, such as           a newline.
                   They may also need to  decode  strings  from            the
                   helper, which likewise may have been base64 encoded.

       --username=USERNAME
          Specify username of user to authenticate

       --domain=DOMAIN
          Specify domain of user to authenticate

       --workstation=WORKSTATION
          Specify the workstation the user authenticated from

       --challenge=STRING
          NTLM challenge (in HEXADECIMAL)

       --lm-response=RESPONSE
          LM Response to the challenge (in HEXADECIMAL)

       --nt-response=RESPONSE
          NT or NTLMv2 Response to the challenge (in HEXADECIMAL)

       --password=PASSWORD
          User’s plaintext password

          If  not  specified  on  the  command line, this is prompted for when
          required.

          For the NTLMSSP based server  roles,  this  paramter  specifies  the
          expected password, allowing testing without winbindd operational.

       --request-lm-key
          Retreive LM session key

       --request-nt-key
          Request NT key

       --diagnostics
          Perform  Diagnostics  on the authentication chain. Uses the password
          from --password or prompts for one.

       --require-membership-of={SID|Name}
          Require that a user be a member of specified group (either  name  or
          SID) for authentication to succeed.

       -V
          Prints the program version number.

       -s <configuration file>
          The  file  specified  contains the configuration details required by
          the server. The information in this  file  includes  server-specific
          information   such  as  what  printcap  file  to  use,  as  well  as
          descriptions of all the services that the server is to provide.  See
          smb.conf  for  more information. The default configuration file name
          is determined at compile time.

       -d|--debuglevel=level
          level is an integer  from  0  to  10.  The  default  value  if  this
          parameter is not specified is zero.

          The  higher  this  value,  the more detail will be logged to the log
          files about the activities of the server. At level 0, only  critical
          errors  and serious warnings will be logged. Level 1 is a reasonable
          level for day-to-day running  -  it  generates  a  small  amount  of
          information about operations carried out.

          Levels  above  1 will generate considerable amounts of log data, and
          should only be used when investigating a problem. Levels above 3 are
          designed for use only by developers and generate HUGE amounts of log
          data, most of which is extremely cryptic.

          Note that specifying this parameter here will override the

          parameter in the smb.conf file.

       -l|--logfile=logdirectory
          Base directory name for log/debug files. The  extension  ".progname"
          will  be  appended  (e.g.  log.smbclient, log.smbd, etc...). The log
          file is never removed by the client.

       -h|--help
          Print a summary of command line options.

EXAMPLE SETUP

       To setup ntlm_auth for use by squid 2.5, with both  basic  and  NTLMSSP
       authentication,  the following should be placed in the squid.conf file.

       auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
       auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
       auth_param basic children 5
       auth_param basic realm Squid proxy-caching web server
       auth_param basic credentialsttl 2 hours

       Note
       This example assumes that ntlm_auth has been installed into your  path,
       and  that the group permissions on winbindd_privileged are as described
       above.

       To setup ntlm_auth for use  by  squid  2.5  with  group  limitation  in
       addition  to  the  above  example, the following should be added to the
       squid.conf file.

       auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of=’WORKGROUPauth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of=’WORKGROUP

TROUBLESHOOTING

       If you’re experiencing problems with authenticating  Internet  Explorer
       running  under  MS  Windows 9X or Millenium Edition against ntlm_auth’s
       NTLMSSP  authentication  helper  (--helper-protocol=squid-2.5-ntlmssp),
       then  please  read  the  Microsoft  Knowledge  Base article #239869 and
       follow instructions described there.

VERSION

       This man page is correct for version 3.0 of the Samba suite.

AUTHOR

       The original Samba software  and  related  utilities  were  created  by
       Andrew  Tridgell.  Samba  is now developed by the Samba Team as an Open
       Source project similar to the way the Linux kernel is developed.

       The ntlm_auth  manpage  was  written  by  Jelmer  Vernooij  and  Andrew
       Bartlett.

                                                                  NTLM_AUTH(1)