~zulcss/samba/server-dailies-3.4

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 intended to be used by other programs (currently

184

Squid

185

and

186

mod_ntlm_winbind)

187

.SH "OPERATIONAL REQUIREMENTS"

188

.PP

189

The

190

\fBwinbindd\fR(8)

191

daemon must be operational for many of these commands to function\&.

192

.PP

193

Some of these commands also require access to the directory

194

\FCwinbindd_privileged\F[]

195

196

\FC$LOCKDIR\F[]\&. This should be done either by running this command as root or providing group access to the

197

\FCwinbindd_privileged\F[]

198

directory\&. For security reasons, this directory should not be world\-accessable\&.

199

.SH "OPTIONS"

200

.PP

201

\-\-helper\-protocol=PROTO

202

.RS 4

203

Operate as a stdio\-based helper\&. Valid helper protocols are:

204

.PP

205

squid\-2\&.4\-basic

206

.RS 4

207

Server\-side helper for use with Squid 2\&.4\'s basic (plaintext) authentication\&.

208

.RE

209

.PP

210

squid\-2\&.5\-basic

211

.RS 4

212

Server\-side helper for use with Squid 2\&.5\'s basic (plaintext) authentication\&.

213

.RE

214

.PP

215

squid\-2\&.5\-ntlmssp

216

.RS 4

217

Server\-side helper for use with Squid 2\&.5\'s NTLMSSP authentication\&.

218

.sp

219

Requires access to the directory

220

\FCwinbindd_privileged\F[]

221

222

\FC$LOCKDIR\F[]\&. The protocol used is described here:

223

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

224

\FCYR\F[]

225

command\&. (Thus avoiding loss of information in the protocol exchange)\&.

226

.RE

227

.PP

228

ntlmssp\-client\-1

229

.RS 4

230

Client\-side helper for use with arbitrary external programs that may wish to use Samba\'s NTLMSSP authentication knowledge\&.

231

.sp

232

This 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

233

\FCYR\F[]

234

command (without any arguments) starts the authentication exchange\&.

235

.RE

236

.PP

237

gss\-spnego

238

.RS 4

239

Server\-side helper that implements GSS\-SPNEGO\&. This uses a protocol that is almost the same as

240

\FCsquid\-2\&.5\-ntlmssp\F[], but has some subtle differences that are undocumented outside the source at this stage\&.

241

.sp

242

Requires access to the directory

243

\FCwinbindd_privileged\F[]

244

245

\FC$LOCKDIR\F[]\&.

246

.RE

247

.PP

248

gss\-spnego\-client

249

.RS 4

250

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

251

.RE

252

.PP

253

ntlm\-server\-1

254

.RS 4

255

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\&.

256

.sp

257

This protocol consists of lines in the form:

258

\FCParameter: value\F[]

259

and

260

\FCParameter:: Base64\-encode value\F[]\&. The presence of a single period

261

\FC\&.\F[]

262

indicates that one side has finished supplying data to the other\&. (Which in turn could cause the helper to authenticate the user)\&.

263

.sp

264

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

265

.PP

266

Username

267

.RS 4

268

The username, expected to be in Samba\'s

269

\m[blue]\fBunix charset\fR\m[]\&.

270

.PP \fBExample\ \&1.\ \&\fR Username: bob

271

.PP \fBExample\ \&2.\ \&\fR Username:: Ym9i

272

.RE

273

.PP

274

Username

275

.RS 4

276

The user\'s domain, expected to be in Samba\'s

277

\m[blue]\fBunix charset\fR\m[]\&.

278

.PP \fBExample\ \&3.\ \&\fR Domain: WORKGROUP

279

.PP \fBExample\ \&4.\ \&\fR Domain:: V09SS0dST1VQ

280

.RE

281

.PP

282

Full\-Username

283

.RS 4

284

The fully qualified username, expected to be in Samba\'s

285

\m[blue]\fBunix charset\fR\m[]

286

and qualified with the

287

\m[blue]\fBwinbind separator\fR\m[]\&.

288

.PP \fBExample\ \&5.\ \&\fR Full\-Username: WORKGROUP\ebob

289

.PP \fBExample\ \&6.\ \&\fR Full\-Username:: V09SS0dST1VQYm9i

290

.RE

291

.PP

292

LANMAN\-Challenge

293

.RS 4

294

The 8 byte

295

\FCLANMAN Challenge\F[]

296

value, generated randomly by the server, or (in cases such as MSCHAPv2) generated in some way by both the server and the client\&.

297

.PP \fBExample\ \&7.\ \&\fR LANMAN\-Challege: 0102030405060708

298

.RE

299

.PP

300

LANMAN\-Response

301

.RS 4

302

The 24 byte

303

\FCLANMAN Response\F[]

304

value, calculated from the user\'s password and the supplied

305

\FCLANMAN Challenge\F[]\&. Typically, this is provided over the network by a client wishing to authenticate\&.

306

.PP \fBExample\ \&8.\ \&\fR LANMAN\-Response: 0102030405060708090A0B0C0D0E0F101112131415161718

307

.RE

308

.PP

309

NT\-Response

310

.RS 4

311

The >= 24 byte

312

\FCNT Response\F[]

313

calculated from the user\'s password and the supplied

314

\FCLANMAN Challenge\F[]\&. Typically, this is provided over the network by a client wishing to authenticate\&.

315

.PP \fBExample\ \&9.\ \&\fR NT\-Response: 0102030405060708090A0B0C0D0E0F101112131415161718

316

.RE

317

.PP

318

Password

319

.RS 4

320

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\&.

321

.PP \fBExample\ \&10.\ \&\fR Password: samba2

322

.PP \fBExample\ \&11.\ \&\fR Password:: c2FtYmEy

323

.RE

324

.PP

325

Request\-User\-Session\-Key

326

.RS 4

327

Apon sucessful authenticaiton, return the user session key associated with the login\&.

328

.PP \fBExample\ \&12.\ \&\fR Request\-User\-Session\-Key: Yes

329

.RE

330

.PP

331

Request\-LanMan\-Session\-Key

332

.RS 4

333

Apon sucessful authenticaiton, return the LANMAN session key associated with the login\&.

334

.PP \fBExample\ \&13.\ \&\fR Request\-LanMan\-Session\-Key: Yes

335

.RE

336

.if n \{\

337

.sp

338

.\}

339

.RS 4

340

.BM yellow

341

.it 1 an-trap

342

.nr an-no-space-flag 1

343

.nr an-break-flag 1

344

.br

345

.ps +1

346

\fBWarning\fR

347

.ps -1

348

.br

349

Implementors should take care to base64 encode

350

any data (such as usernames/passwords) that may contain malicous user data, such as

351

a newline\&. They may also need to decode strings from

352

the helper, which likewise may have been base64 encoded\&..sp .5v

353

.EM yellow

354

.RE

355

.RE

356

.RE

357

.PP

358

\-\-username=USERNAME

359

.RS 4

360

Specify username of user to authenticate

361

.RE

362

.PP

363

\-\-domain=DOMAIN

364

.RS 4

365

Specify domain of user to authenticate

366

.RE

367

.PP

368

\-\-workstation=WORKSTATION

369

.RS 4

370

Specify the workstation the user authenticated from

371

.RE

372

.PP

373

\-\-challenge=STRING

374

.RS 4

375

NTLM challenge (in HEXADECIMAL)

376

.RE

377

.PP

378

\-\-lm\-response=RESPONSE

379

.RS 4

380

LM Response to the challenge (in HEXADECIMAL)

381

.RE

382

.PP

383

\-\-nt\-response=RESPONSE

384

.RS 4

385

NT or NTLMv2 Response to the challenge (in HEXADECIMAL)

386

.RE

387

.PP

388

\-\-password=PASSWORD

389

.RS 4

390

User\'s plaintext password

391

.sp

392

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

393

.sp

394

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

395

.RE

396

.PP

397

\-\-request\-lm\-key

398

.RS 4

399

Retreive LM session key

400

.RE

401

.PP

402

\-\-request\-nt\-key

403

.RS 4

404

Request NT key

405

.RE

406

.PP

407

\-\-diagnostics

408

.RS 4

409

Perform Diagnostics on the authentication chain\&. Uses the password from

410

\FC\-\-password\F[]

411

or prompts for one\&.

412

.RE

413

.PP

414

\-\-require\-membership\-of={SID|Name}

415

.RS 4

416

Require that a user be a member of specified group (either name or SID) for authentication to succeed\&.

417

.RE

418

.PP

419

\-d|\-\-debuglevel=level

420

.RS 4

421

\fIlevel\fR

422

is an integer from 0 to 10\&. The default value if this parameter is not specified is 0\&.

423

.sp

424

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\&.

425

.sp

426

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\&.

427

.sp

428

Note that specifying this parameter here will override the

429

\m[blue]\fB\%smb.conf.5.html#\fR\m[]

430

parameter in the

431

\FCsmb\&.conf\F[]

432

file\&.

433

.RE

434

.PP

435

\-V|\-\-version

436

.RS 4

437

Prints the program version number\&.

438

.RE

439

.PP

440

\-s|\-\-configfile <configuration file>

441

.RS 4

442

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

443

\FCsmb\&.conf\F[]

444

for more information\&. The default configuration file name is determined at compile time\&.

445

.RE

446

.PP

447

\-l|\-\-log\-basename=logdirectory

448

.RS 4

449

Base directory name for log/debug files\&. The extension

450

\fB"\&.progname"\fR

451

will be appended (e\&.g\&. log\&.smbclient, log\&.smbd, etc\&.\&.\&.)\&. The log file is never removed by the client\&.

452

.RE

453

.PP

454

\-h|\-\-help

455

.RS 4

456

Print a summary of command line options\&.

457

.RE

458

.SH "EXAMPLE SETUP"

459

.PP

460

To setup ntlm_auth for use by squid 2\&.5, with both basic and NTLMSSP authentication, the following should be placed in the

461

\FCsquid\&.conf\F[]

462

file\&.

463

.sp

464

.if n \{\

465

.RS 4

466

.\}

467

.fam C

468

.ps -1

469

.nf

470

.if t \{\

471

.sp -1

472

.\}

473

.BB lightgray adjust-for-leading-newline

474

.sp -1

475

476

auth_param ntlm program ntlm_auth \-\-helper\-protocol=squid\-2\&.5\-ntlmssp

477

auth_param basic program ntlm_auth \-\-helper\-protocol=squid\-2\&.5\-basic

478

auth_param basic children 5

479

auth_param basic realm Squid proxy\-caching web server

480

auth_param basic credentialsttl 2 hours

481

.EB lightgray adjust-for-leading-newline

482

.if t \{\

483

.sp 1

484

.\}

485

.fi

486

.fam

487

.ps +1

488

.if n \{\

489

.RE

490

.\}

491

.if n \{\

492

.sp

493

.\}

494

.RS 4

495

.BM yellow

496

.it 1 an-trap

497

.nr an-no-space-flag 1

498

.nr an-break-flag 1

499

.br

500

.ps +1

501

\fBNote\fR

502

.ps -1

503

.br

504

.PP

505

This example assumes that ntlm_auth has been installed into your path, and that the group permissions on

506

\FCwinbindd_privileged\F[]

507

are as described above\&.

508

.sp .5v

509

.EM yellow

510

.RE

511

.PP

512

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

513

\FCsquid\&.conf\F[]

514

file\&.

515

.sp

516

.if n \{\

517

.RS 4

518

.\}

519

.fam C

520

.ps -1

521

.nf

522

.if t \{\

523

.sp -1

524

.\}

525

.BB lightgray adjust-for-leading-newline

526

.sp -1

527

528

auth_param ntlm program ntlm_auth \-\-helper\-protocol=squid\-2\&.5\-ntlmssp \-\-require\-membership\-of=\'WORKGROUP\eDomain Users\'

529

auth_param basic program ntlm_auth \-\-helper\-protocol=squid\-2\&.5\-basic \-\-require\-membership\-of=\'WORKGROUP\eDomain Users\'

530

.EB lightgray adjust-for-leading-newline

531

.if t \{\

532

.sp 1

533

.\}

534

.fi

535

.fam

536

.ps +1

537

.if n \{\

538

.RE

539

.\}

540

.SH "TROUBLESHOOTING"

541

.PP

542

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

543

the Microsoft Knowledge Base article #239869 and follow instructions described there\&.

544

.SH "VERSION"

545

.PP

546

This man page is correct for version 3 of the Samba suite\&.

547

.SH "AUTHOR"

548

.PP

549

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\&.

550

.PP

551

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