Ignore:
Timestamp:
May 23, 2008, 6:56:41 AM (17 years ago)
Author:
Paul Smedley
Message:

Update source to 3.0.29

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/samba-3.0/docs/manpages/ntlm_auth.1

    r44 r134  
    1 .\"Generated by db2man.xsl. Don't modify this, modify the source.
    2 .de Sh \" Subsection
    3 .br
    4 .if t .Sp
    5 .ne 5
    6 .PP
    7 \fB\\$1\fR
    8 .PP
    9 ..
    10 .de Sp \" Vertical space (when we can't use .PP)
    11 .if t .sp .5v
    12 .if n .sp
    13 ..
    14 .de Ip \" List item
    15 .br
    16 .ie \\n(.$>=3 .ne \\$3
    17 .el .ne 3
    18 .IP "\\$1" \\$2
    19 ..
    20 .TH "NTLM_AUTH" 1 "" "" ""
     1.\"     Title: ntlm_auth
     2.\"    Author:
     3.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
     4.\"      Date: 05/21/2008
     5.\"    Manual: User Commands
     6.\"    Source: Samba 3.0
     7.\"
     8.TH "NTLM_AUTH" "1" "05/21/2008" "Samba 3\.0" "User Commands"
     9.\" disable hyphenation
     10.nh
     11.\" disable justification (adjust text to left margin only)
     12.ad l
    2113.SH "NAME"
    2214ntlm_auth - tool to allow external access to Winbind's NTLM authentication function
    2315.SH "SYNOPSIS"
    2416.HP 1
    25 ntlm_auth [-d debuglevel] [-l logdir] [-s <smb config file>]
     17ntlm_auth [\-d\ debuglevel] [\-l\ logdir] [\-s\ <smb\ config\ file>]
    2618.SH "DESCRIPTION"
    2719.PP
    2820This tool is part of the
    2921\fBsamba\fR(7)
    30 suite.
     22suite\.
    3123.PP
    3224ntlm_auth
    33 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
     25is 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
    3426Squid
    3527and
    … …  
    3931The
    4032\fBwinbindd\fR(8)
    41 daemon must be operational for many of these commands to function.
     33daemon must be operational for many of these commands to function\.
    4234.PP
    4335Some of these commands also require access to the directory
    4436\fIwinbindd_privileged\fR
    4537in
    46 \fI$LOCKDIR\fR. This should be done either by running this command as root or providing group access to the
    47 \fIwinbindd_privileged\fR
    48 directory. For security reasons, this directory should not be world-accessable.
     38\fI$LOCKDIR\fR\. This should be done either by running this command as root or providing group access to the
     39\fIwinbindd_privileged\fR
     40directory\. For security reasons, this directory should not be world\-accessable\.
    4941.SH "OPTIONS"
    5042.PP
    51 --helper-protocol=PROTO
    52 .RS 3n
    53 Operate as a stdio-based helper. Valid helper protocols are:
    54 
    55 .RS 3n
    56 .PP
    57 squid-2.4-basic
    58 .RS 3n
    59 Server-side helper for use with Squid 2.4's basic (plaintext) authentication.
    60 .RE
    61 .PP
    62 squid-2.5-basic
    63 .RS 3n
    64 Server-side helper for use with Squid 2.5's basic (plaintext) authentication.
    65 .RE
    66 .PP
    67 squid-2.5-ntlmssp
    68 .RS 3n
    69 Server-side helper for use with Squid 2.5's NTLMSSP authentication.
     43\-\-helper\-protocol=PROTO
     44.RS 4
     45Operate as a stdio\-based helper\. Valid helper protocols are:
     46.PP
     47squid\-2\.4\-basic
     48.RS 4
     49Server\-side helper for use with Squid 2\.4\'s basic (plaintext) authentication\.
     50.RE
     51.PP
     52squid\-2\.5\-basic
     53.RS 4
     54Server\-side helper for use with Squid 2\.5\'s basic (plaintext) authentication\.
     55.RE
     56.PP
     57squid\-2\.5\-ntlmssp
     58.RS 4
     59Server\-side helper for use with Squid 2\.5\'s NTLMSSP authentication\.
    7060.sp
    7161Requires access to the directory
    7262\fIwinbindd_privileged\fR
    7363in
    74 \fI$LOCKDIR\fR. The protocol used is described here:
    75 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
     64\fI$LOCKDIR\fR\. The protocol used is described here:
     65http://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
    7666YR
    77 command. (Thus avoiding loss of information in the protocol exchange).
    78 .RE
    79 .PP
    80 ntlmssp-client-1
    81 .RS 3n
    82 Client-side helper for use with arbitary external programs that may wish to use Samba's NTLMSSP authentication knowlege.
    83 .sp
    84 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
     67command\. (Thus avoiding loss of information in the protocol exchange)\.
     68.RE
     69.PP
     70ntlmssp\-client\-1
     71.RS 4
     72Client\-side helper for use with arbitrary external programs that may wish to use Samba\'s NTLMSSP authentication knowledge\.
     73.sp
     74This helper is a client, and as such may be run by any user\. The protocol used is effectively the reverse of the previous protocol\. A
    8575YR
    86 command (without any arguments) starts the authentication exchange.
    87 .RE
    88 .PP
    89 gss-spnego
    90 .RS 3n
    91 Server-side helper that implements GSS-SPNEGO. This uses a protocol that is almost the same as
    92 squid-2.5-ntlmssp, but has some subtle differences that are undocumented outside the source at this stage.
     76command (without any arguments) starts the authentication exchange\.
     77.RE
     78.PP
     79gss\-spnego
     80.RS 4
     81Server\-side helper that implements GSS\-SPNEGO\. This uses a protocol that is almost the same as
     82squid\-2\.5\-ntlmssp, but has some subtle differences that are undocumented outside the source at this stage\.
    9383.sp
    9484Requires access to the directory
    9585\fIwinbindd_privileged\fR
    9686in
    97 \fI$LOCKDIR\fR.
    98 .RE
    99 .PP
    100 gss-spnego-client
    101 .RS 3n
    102 Client-side helper that implements GSS-SPNEGO. This also uses a protocol similar to the above helpers, but is currently undocumented.
    103 .RE
    104 .PP
    105 ntlm-server-1
    106 .RS 3n
    107 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.
    108 .sp
    109 This protocol consists of lines in for form:
     87\fI$LOCKDIR\fR\.
     88.RE
     89.PP
     90gss\-spnego\-client
     91.RS 4
     92Client\-side helper that implements GSS\-SPNEGO\. This also uses a protocol similar to the above helpers, but is currently undocumented\.
     93.RE
     94.PP
     95ntlm\-server\-1
     96.RS 4
     97Server\-side helper protocol, intended for use by a RADIUS server or the \'winbind\' plugin for pppd, for the provision of MSCHAP and MSCHAPv2 authentication\.
     98.sp
     99This protocol consists of lines in the form:
    110100Parameter: value
    111101and
    112 Paramter:: Base64-encode value. The presence of a single period
    113 .
    114 indicates that one side has finished supplying data to the other. (Which in turn could cause the helper to authenticate the user).
     102Parameter:: Base64\-encode value\. The presence of a single period
     103\.
     104indicates that one side has finished supplying data to the other\. (Which in turn could cause the helper to authenticate the user)\.
    115105.sp
    116106Curently implemented parameters from the external program to the helper are:
    117 
    118 .RS 3n
    119107.PP
    120108Username
    121 .RS 3n
    122 The username, expected to be in Samba's
    123 unix charset.
    124 .sp
    125 \fBExample 1. \fRUsername: bob
    126 .sp
    127 \fBExample 2. \fRUsername:: Ym9i
     109.RS 4
     110The username, expected to be in Samba\'s
     111\fIunix charset\fR\.
     112.PP \fBExample\ 1.\ \fR Username: bob
     113.PP \fBExample\ 2.\ \fR Username:: Ym9i
    128114.RE
    129115.PP
    130116Username
    131 .RS 3n
    132 The user's domain, expected to be in Samba's
    133 unix charset.
    134 .sp
    135 \fBExample 3. \fRDomain: WORKGROUP
    136 .sp
    137 \fBExample 4. \fRDomain:: V09SS0dST1VQ
    138 .RE
    139 .PP
    140 Full-Username
    141 .RS 3n
    142 The fully qualified username, expected to be in Samba's
    143 
     117.RS 4
     118The user\'s domain, expected to be in Samba\'s
     119\fIunix charset\fR\.
     120.PP \fBExample\ 3.\ \fR Domain: WORKGROUP
     121.PP \fBExample\ 4.\ \fR Domain:: V09SS0dST1VQ
     122.RE
     123.PP
     124Full\-Username
     125.RS 4
     126The fully qualified username, expected to be in Samba\'s
     127\fIunix charset\fR
    144128and qualified with the
    145 winbind separator.
    146 .sp
    147 \fBExample 5. \fRFull-Username: WORKGROUP\bob
    148 .sp
    149 \fBExample 6. \fRFull-Username:: V09SS0dST1VQYm9i
    150 .RE
    151 .PP
    152 LANMAN-Challenge
    153 .RS 3n
     129\fIwinbind separator\fR\.
     130.PP \fBExample\ 5.\ \fR Full\-Username: WORKGROUP\ebob
     131.PP \fBExample\ 6.\ \fR Full\-Username:: V09SS0dST1VQYm9i
     132.RE
     133.PP
     134LANMAN\-Challenge
     135.RS 4
    154136The 8 byte
    155137LANMAN Challenge
    156 value, generated randomly by the server, or (in cases such as MSCHAPv2) generated in some way by both the server and the client.
    157 .sp
    158 \fBExample 7. \fRLANMAN-Challege: 0102030405060708
    159 .RE
    160 .PP
    161 LANMAN-Response
    162 .RS 3n
     138value, generated randomly by the server, or (in cases such as MSCHAPv2) generated in some way by both the server and the client\.
     139.PP \fBExample\ 7.\ \fR LANMAN\-Challege: 0102030405060708
     140.RE
     141.PP
     142LANMAN\-Response
     143.RS 4
    163144The 24 byte
    164145LANMAN Response
    165 value, calculated from the user's password and the supplied
    166 LANMAN Challenge. Typically, this is provided over the network by a client wishing to authenticate.
    167 .sp
    168 \fBExample 8. \fRLANMAN-Response: 0102030405060708090A0B0C0D0E0F101112131415161718
    169 .RE
    170 .PP
    171 NT-Response
    172 .RS 3n
     146value, calculated from the user\'s password and the supplied
     147LANMAN Challenge\. Typically, this is provided over the network by a client wishing to authenticate\.
     148.PP \fBExample\ 8.\ \fR LANMAN\-Response: 0102030405060708090A0B0C0D0E0F101112131415161718
     149.RE
     150.PP
     151NT\-Response
     152.RS 4
    173153The >= 24 byte
    174154NT Response
    175 calculated from the user's password and the supplied
    176 LANMAN Challenge. Typically, this is provided over the network by a client wishing to authenticate.
    177 .sp
    178 \fBExample 9. \fRNT-Response: 0102030405060708090A0B0C0D0E0F101112131415161718
     155calculated from the user\'s password and the supplied
     156LANMAN Challenge\. Typically, this is provided over the network by a client wishing to authenticate\.
     157.PP \fBExample\ 9.\ \fR NT\-Response: 0102030405060708090A0B0C0D0E0F101112131415161718
    179158.RE
    180159.PP
    181160Password
    182 .RS 3n
    183 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.
    184 .sp
    185 \fBExample 10. \fRPassword: samba2
    186 .sp
    187 \fBExample 11. \fRPassword:: c2FtYmEy
    188 .RE
    189 .PP
    190 Request-User-Session-Key
    191 .RS 3n
    192 Apon sucessful authenticaiton, return the user session key associated with the login.
    193 .sp
    194 \fBExample 12. \fRRequest-User-Session-Key: Yes
    195 .RE
    196 .PP
    197 Request-LanMan-Session-Key
    198 .RS 3n
    199 Apon sucessful authenticaiton, return the LANMAN session key associated with the login.
    200 .sp
    201 \fBExample 13. \fRRequest-LanMan-Session-Key: Yes
     161.RS 4
     162The 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\.
     163.PP \fBExample\ 10.\ \fR Password: samba2
     164.PP \fBExample\ 11.\ \fR Password:: c2FtYmEy
     165.RE
     166.PP
     167Request\-User\-Session\-Key
     168.RS 4
     169Apon sucessful authenticaiton, return the user session key associated with the login\.
     170.PP \fBExample\ 12.\ \fR Request\-User\-Session\-Key: Yes
     171.RE
     172.PP
     173Request\-LanMan\-Session\-Key
     174.RS 4
     175Apon sucessful authenticaiton, return the LANMAN session key associated with the login\.
     176.PP \fBExample\ 13.\ \fR Request\-LanMan\-Session\-Key: Yes
    202177.RE
    203178.sp
    … …  
    206181.nr an-break-flag 1
    207182.br
    208 \fBWarning\fR
     183Warning
    209184Implementors should take care to base64 encode
    210185                any data (such as usernames/passwords) that may contain malicous user data, such as
    211                 a newline.  They may also need to decode strings from
    212                 the helper, which likewise may have been base64 encoded.
    213 .RE
    214 .RE
    215 .RE
    216 .RE
    217 .PP
    218 --username=USERNAME
    219 .RS 3n
     186                a newline\.  They may also need to decode strings from
     187                the helper, which likewise may have been base64 encoded\.
     188.RE
     189.RE
     190.PP
     191\-\-username=USERNAME
     192.RS 4
    220193Specify username of user to authenticate
    221194.RE
    222195.PP
    223 --domain=DOMAIN
    224 .RS 3n
     196\-\-domain=DOMAIN
     197.RS 4
    225198Specify domain of user to authenticate
    226199.RE
    227200.PP
    228 --workstation=WORKSTATION
    229 .RS 3n
     201\-\-workstation=WORKSTATION
     202.RS 4
    230203Specify the workstation the user authenticated from
    231204.RE
    232205.PP
    233 --challenge=STRING
    234 .RS 3n
     206\-\-challenge=STRING
     207.RS 4
    235208NTLM challenge (in HEXADECIMAL)
    236209.RE
    237210.PP
    238 --lm-response=RESPONSE
    239 .RS 3n
     211\-\-lm\-response=RESPONSE
     212.RS 4
    240213LM Response to the challenge (in HEXADECIMAL)
    241214.RE
    242215.PP
    243 --nt-response=RESPONSE
    244 .RS 3n
     216\-\-nt\-response=RESPONSE
     217.RS 4
    245218NT or NTLMv2 Response to the challenge (in HEXADECIMAL)
    246219.RE
    247220.PP
    248 --password=PASSWORD
    249 .RS 3n
    250 User's plaintext password
    251 .sp
    252 If not specified on the command line, this is prompted for when required.
    253 .sp
    254 For the NTLMSSP based server roles, this paramter specifies the expected password, allowing testing without winbindd operational.
    255 .RE
    256 .PP
    257 --request-lm-key
    258 .RS 3n
     221\-\-password=PASSWORD
     222.RS 4
     223User\'s plaintext password
     224.sp
     225If not specified on the command line, this is prompted for when required\.
     226.sp
     227For the NTLMSSP based server roles, this parameter specifies the expected password, allowing testing without winbindd operational\.
     228.RE
     229.PP
     230\-\-request\-lm\-key
     231.RS 4
    259232Retreive LM session key
    260233.RE
    261234.PP
    262 --request-nt-key
    263 .RS 3n
     235\-\-request\-nt\-key
     236.RS 4
    264237Request NT key
    265238.RE
    266239.PP
    267 --diagnostics
    268 .RS 3n
    269 Perform Diagnostics on the authentication chain. Uses the password from
    270 --password
    271 or prompts for one.
    272 .RE
    273 .PP
    274 --require-membership-of={SID|Name}
    275 .RS 3n
    276 Require that a user be a member of specified group (either name or SID) for authentication to succeed.
    277 .RE
    278 .PP
    279 -V
    280 .RS 3n
    281 Prints the program version number.
    282 .RE
    283 .PP
    284 -s <configuration file>
    285 .RS 3n
    286 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
    287 \fIsmb.conf\fR
    288 for more information. The default configuration file name is determined at compile time.
    289 .RE
    290 .PP
    291 -d|--debuglevel=level
    292 .RS 3n
     240\-\-diagnostics
     241.RS 4
     242Perform Diagnostics on the authentication chain\. Uses the password from
     243\-\-password
     244or prompts for one\.
     245.RE
     246.PP
     247\-\-require\-membership\-of={SID|Name}
     248.RS 4
     249Require that a user be a member of specified group (either name or SID) for authentication to succeed\.
     250.RE
     251.PP
     252\-d|\-\-debuglevel=level
     253.RS 4
    293254\fIlevel\fR
    294 is an integer from 0 to 10. The default value if this parameter is not specified is zero.
    295 .sp
    296 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.
    297 .sp
    298 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.
     255is an integer from 0 to 10\. The default value if this parameter is not specified is 0\.
     256.sp
     257The 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\.
     258.sp
     259Levels 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\.
    299260.sp
    300261Note that specifying this parameter here will override the
    301 
     262\fIlog level\fR
    302263parameter in the
    303 \fIsmb.conf\fR
    304 file.
    305 .RE
    306 .PP
    307 -l|--logfile=logdirectory
    308 .RS 3n
    309 Base directory name for log/debug files. The extension
    310 \fB".progname"\fR
    311 will be appended (e.g. log.smbclient, log.smbd, etc...). The log file is never removed by the client.
    312 .RE
    313 .PP
    314 -h|--help
    315 .RS 3n
    316 Print a summary of command line options.
     264\fIsmb\.conf\fR
     265file\.
     266.RE
     267.PP
     268\-V
     269.RS 4
     270Prints the program version number\.
     271.RE
     272.PP
     273\-s <configuration file>
     274.RS 4
     275The 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
     276\fIsmb\.conf\fR
     277for more information\. The default configuration file name is determined at compile time\.
     278.RE
     279.PP
     280\-l|\-\-log\-basename=logdirectory
     281.RS 4
     282Base directory name for log/debug files\. The extension
     283\fB"\.progname"\fR
     284will be appended (e\.g\. log\.smbclient, log\.smbd, etc\.\.\.)\. The log file is never removed by the client\.
     285.RE
     286.PP
     287\-h|\-\-help
     288.RS 4
     289Print a summary of command line options\.
    317290.RE
    318291.SH "EXAMPLE SETUP"
    319292.PP
    320 To setup ntlm_auth for use by squid 2.5, with both basic and NTLMSSP authentication, the following should be placed in the
    321 \fIsquid.conf\fR
    322 file.
    323 
    324 .sp
    325 
     293To setup ntlm_auth for use by squid 2\.5, with both basic and NTLMSSP authentication, the following should be placed in the
     294\fIsquid\.conf\fR
     295file\.
     296.sp
     297.RS 4
    326298.nf
    327 
    328 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp
    329 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic
     299auth_param ntlm program ntlm_auth \-\-helper\-protocol=squid\-2\.5\-ntlmssp
     300auth_param basic program ntlm_auth \-\-helper\-protocol=squid\-2\.5\-basic
    330301auth_param basic children 5
    331 auth_param basic realm Squid proxy-caching web server
     302auth_param basic realm Squid proxy\-caching web server
    332303auth_param basic credentialsttl 2 hours
    333 
    334304.fi
    335 
     305.RE
    336306.sp
    337307.it 1 an-trap
    … …  
    339309.nr an-break-flag 1
    340310.br
    341 \fBNote\fR
     311Note
    342312.PP
    343313This example assumes that ntlm_auth has been installed into your path, and that the group permissions on
    344314\fIwinbindd_privileged\fR
    345 are as described above.
    346 .PP
    347 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
    348 \fIsquid.conf\fR
    349 file.
    350 
    351 .sp
    352 
     315are as described above\.
     316.PP
     317To 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
     318\fIsquid\.conf\fR
     319file\.
     320.sp
     321.RS 4
    353322.nf
    354 
    355 auth_param ntlm program ntlm_auth --helper-protocol=squid-2.5-ntlmssp --require-membership-of='WORKGROUP\Domain Users'
    356 auth_param basic program ntlm_auth --helper-protocol=squid-2.5-basic --require-membership-of='WORKGROUP\Domain Users'
    357 
     323auth_param ntlm program ntlm_auth \-\-helper\-protocol=squid\-2\.5\-ntlmssp \-\-require\-membership\-of=\'WORKGROUP\eDomain Users\'
     324auth_param basic program ntlm_auth \-\-helper\-protocol=squid\-2\.5\-basic \-\-require\-membership\-of=\'WORKGROUP\eDomain Users\'
    358325.fi
    359 
     326.RE
    360327.SH "TROUBLESHOOTING"
    361328.PP
    362 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
    363 the Microsoft Knowledge Base article #239869 and follow instructions described there.
     329If 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
     330the Microsoft Knowledge Base article #239869 and follow instructions described there\.
    364331.SH "VERSION"
    365332.PP
    366 This man page is correct for version 3.0 of the Samba suite.
     333This man page is correct for version 3\.0 of the Samba suite\.
    367334.SH "AUTHOR"
    368335.PP
    369 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.
    370 .PP
    371 The ntlm_auth manpage was written by Jelmer Vernooij and Andrew Bartlett.
    372 
     336The 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\.
     337.PP
     338The ntlm_auth manpage was written by Jelmer Vernooij and Andrew Bartlett\.
Note: See TracChangeset for help on using the changeset viewer.