Manual

Provides an API for managing SAMBA passwd-style files

Introduction

Introduction – file format

SAMBA passwd-style files

SAMBA is a free implementation of CIFS/SMB. The password encryption on Unix and Windows is different, therefore SAMBA must have his own file where the passwords are encrypted either as NT-Hash and/or as LAN-Manager-Hash. LAN-Manager-Hashes are weak and shouldn't be used anymore, NT-Hashes are based on MD4, but no salt is used, therefore users with the same passwords have the same NT-Hash. In this file are also stored machine accounts, if the SAMBA server acts as PDC, such entries ends with $.

File_SMBPasswd::File_SMBPasswd()

File_SMBPasswd::File_SMBPasswd() – constructor

Synopsis

require_once 'File/SMBPasswd.php';

void File_SMBPasswd::File_SMBPasswd ( string $file )

Description

Creates a new File_SMBPasswd object and bind it to the given file.

Parameter

string $file - SAMBA password file to read

File_SMBPasswd::load()

File_SMBPasswd::load() – load the contents of an existing smbpasswd file

Synopsis

mixed File_SMBPasswd::load ( )

Description

Load the contents of smbpasswd file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::load()

<?php
require_once('File/SMBPasswd.php');

$fh     = new File_SMBPasswd('/usr/local/private/smbpasswd');
$status = $fh->load();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}
  
?>

File_SMBPasswd::getFile()

File_SMBPasswd::getFile() – get the value of the file property

Synopsis

string File_SMBPasswd::getFile ( )

Description

Get the value of file property. This property contains the filename of the current smbpasswd file.

Return value

string containing the filename.

Note

This function can not be called statically.

File_SMBPasswd::getAccounts()

File_SMBPasswd::getAccounts() – get the value of the accounts property

Synopsis

array File_SMBPasswd::getAccounts ( )

Description

Get the value of accounts property. This property contains all accounts of the current smbpasswd file.

Return value

array containing all accounts.

Note

This function can not be called statically.

File_SMBPasswd::addAccountEncrypted()

File_SMBPasswd::addAccountEncrypted() – adds a new account with pre-encrypted passwords.

Synopsis

mixed File_SMBPasswd::addAccountEncrypted ( string $user , int $userid , string $lmhash = '' , string $nthash = '' , string $comment = '' , string $flags = '[U ]' )

Description

Modifies an existing account. The passwords must be already encrypted.

Parameter

string $user - username to be added
int $userid - userid of the user
string $lmhash - LAN-Manager-Hash
string $nthash - NT-Hash
string $comment - comment
string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the systems password file.

See

Example

Using File_SMBPasswd::addAccountEncrypted()

<?php
require_once 'File/SMBPasswd.php';

// add account mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addAccountEncrypted(
    'mbretter', 
    1005, 
    '75BA30198E6D1975AAD3B435B51404EE', 
    'FC156AF7EDCD6C0EDDE3337D427F4EAC',
    'Michael Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>

File_SMBPasswd::addAccount()

File_SMBPasswd::addAccount() – add a new account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::addAccount ( string $user , int $userid , string $pass = '' , string $comment = '' , string $flags = '[U ]' )

Description

This method works in the same way as File_SMBPasswd::addAccountEncrypted() , except the password has to be given as plaintext. The encryption is done internaly.

Parameter

string $user - username to be added
int $userid - userid of the user
string $pass - plaintext-password
string $comment - comment
string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

Example

Using File_SMBPasswd::addAccount()

<?php
require_once 'File/SMBPasswd.php';

// add user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addAccount(
    'mbretter', 
    1004, 
    'MyPw',
    'Michael Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
    $fh->save();
}

?>

File_SMBPasswd::addUser()

File_SMBPasswd::addUser() – add a new user with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::addUser ( string $user , int $userid , string $pass = '' , string $comment = '' )

Description

This method works in the same way as File_SMBPasswd::addAccount() , except the flags are forced representing a user-account.

Parameter

string $user - username to be added
int $userid - userid of the user
string $pass - plaintext-password
string $comment - comment

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

Example

Using File_SMBPasswd::addUser()

<?php
require_once 'File/SMBPasswd.php';

// add user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addUser(
    'mbretter', 
    1004, 
    'MyPw',
    'Michael Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
    $fh->save();
}

?>

File_SMBPasswd::addMachine()

File_SMBPasswd::addMachine() – add a new maschine-account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::addMachine ( string $machine , int $userid , string $comment = '' )

Description

This method works in the same way as File_SMBPasswd::addAccount() , except the flags are forced representing a machine-account, a $ is implicitely added to the machinename.

Parameter

string $machine - machinename to be added
int $userid - userid of the user
string $comment - comment

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the machine to be added must already exist in the system password file.

See

Example

Using File_SMBPasswd::addMachine()

<?php
require_once 'File/SMBPasswd.php';

// add user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addMachine(
    'mypc', 
    10004, 
    'My Turbo PC');
if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
    $fh->save();
}

?>

File_SMBPasswd::modAccountEncrypted()

File_SMBPasswd::modAccountEncrypted() – modify an existing account with the given encrypted password.

Synopsis

mixed File_SMBPasswd::modAccountEncrypted ( string $user , int $userid , string $nthash = '' , string $lmhash = '' , string $comment = '' , string $flags = '' )

Description

Modifies an existing account using pre-encrypted passwords.

Parameter

string $user - username to be added
int $userid - userid of the user
string $nthash - new NT-Hash
string $lmhash - new LM-Hash
string $comment - comment
string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

Example

Using File_SMBPasswd::modAccountEncrypted()

<?php
require_once 'File/SMBPasswd.php';

// modify user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->modAccountEncrypted(
    'mbretter', 
    1005, 
    '75BA30198E6D1975AAD3B435B51404EE',
    'FC156AF7EDCD6C0EDDE3337D427F4EAC', 
    Michaela Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>

File_SMBPasswd::modAccount()

File_SMBPasswd::modAccount() – modify an exsting account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::modAccount ( string $user , int $userid , string $pass = '' , string $comment = '' , string $flags = '' )

Description

This method works in the same way as File_SMBPasswd::modAccountEncrypted() , except the password has to be given as plaintext. The encryption is done internaly.

Parameter

string $user - username to be modified
int $userid - userid of the user
string $pass - plaintext-password
string $comment - comment
string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

See

Example

Using File_SMBPasswd::modAccount()

<?php
require_once 'File/SMBPasswd.php';

// modify user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->modAccount(
    'mbretter', 
    1005, 
    'MyPwa',
    'Michaela Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>

File_SMBPasswd::modUser()

File_SMBPasswd::modUser() – modify an exsting account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::modUser ( string $user , int $userid , string $pass = '' , string $comment = '' , string $flags = '' )

Description

This method modifies an existing user, using a plaintext-password.

Parameter

string $user - username to be added
int $userid - userid of the user
string $pass - plaintext-password
string $comment - comment
string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

Example

Using File_SMBPasswd::modUser()

<?php
require_once 'File/SMBPasswd.php';

// modify user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->modUser(
    'mbretter', 
    1005, 
    'MyPwa',
    'Michaela Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>

File_SMBPasswd::delAccount()

File_SMBPasswd::delAccount() – deletes an existing account.

Synopsis

mixed File_SMBPasswd::delAccount ( string $name )

Description

This method deletes an existing account.

Parameter

string $name - account name to be deleted (username or machinename)

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

See

File_SMBPasswd::delUser()

Example

Using File_SMBPasswd::delAccount()

<?php
require_once 'File/SMBPasswd.php';

// delete user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->delAccount('mbretter');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>

File_SMBPasswd::delUser()

File_SMBPasswd::delUser() – deletes an existing user.

Synopsis

mixed File_SMBPasswd::delUser ( string $user )

Description

This method deletes an existing user.

Parameter

string $user - username to be deleted

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

See

File_SMBPasswd::delAccount()

Example

Using File_SMBPasswd::delAccount()

<?php
require_once 'File/SMBPasswd.php';

// delete user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->delUser('mbretter');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>

File_SMBPasswd::verifyAccountEncrypted()

File_SMBPasswd::verifyAccountEncrypted() – Verifies the given account with the given encrypted passwords.

Synopsis

mixed File_SMBPasswd::verifyAccountEncrypted ( string $user , string $nthash , string $lmhash = '' )

Description

This method verifies the given username and passwords against the entry in the loaded smbpasswd file. The given passwords must already be a valid NT-Hash or LM-Hash, whereas the LM-Hash is optional.

Parameter

string $user - username to be verified
string $nthash - the NT-Hash
string $lmhash - the LM-Hash

Return value

mixed - Returns TRUE on success, FALSE on failure.

See

File_SMBPasswd::verifyAccount()

Example

Using File_SMBPasswd::verifyAccount()

<?php
require_once 'File/SMBPasswd.php';

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
if ($fh->verifyAccountEncrypted('mbretter', '75BA30198E6D1975AAD3B435B51404EE')) {
    echo "Account is valid";
} else {
    echo "Account is in-valid";
}

?>

File_SMBPasswd::verifyAccount()

File_SMBPasswd::verifyAccount() – Verifies the given account with the given plaintext passwords.

Synopsis

mixed File_SMBPasswd::verifyAccount ( string $user , string $pass )

Description

This method verifies the given username and plaintext-password against the entry in the loaded smbpasswd file.

Parameter

string $user - username to be verified
string $pass - the plaintext password

Return value

mixed - Returns TRUE on success, FALSE on failure.

See

File_SMBPasswd::verifyAccountEncrypted()

Example

Using File_SMBPasswd::verifyAccount()

<?php
require_once 'File/SMBPasswd.php';

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
if ($fh->verifyAccount('mbretter', 'MyPw')) {
    echo "Account is valid";
} else {
    echo "Account is in-valid";
}

?>

File_SMBPasswd::lock()

File_SMBPasswd::lock() – lock the smbpasswd file

Synopsis

mixed File_SMBPasswd::lock ( )

Description

lock the smbpasswd file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::lock()

<?php
require_once('File/SMBPasswd.php');

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$status = $fh->lock();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}
  
?>

File_SMBPasswd::unlock()

File_SMBPasswd::unlock() – unlock the smbpasswd file

Synopsis

mixed File_SMBPasswd::unlock ( )

Description

unlock the smbpasswd file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::unlock()

<?php
require_once('File/SMBPasswd.php');

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$status = $fh->unlock();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}
  
?>

File_SMBPasswd::save()

File_SMBPasswd::save() – saves the smbpasswd file

Synopsis

mixed File_SMBPasswds:save ( )

Description

Saves the contents of File_SMBPasswd object as a corresponding smbpasswd file on the disc. Save implicitely locks the file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::save()

<?php
require_once('File_SMBPasswd.php');

$f = new File_SMBPasswd('./smbpasswd');
$f->load();
$ret = $f->addAccount('sepp3', 12, 'MyPw');
if (PEAR::isError($ret)) {
    echo $ret->getMessage();
    exit;
} 
$ret = $f->modAccount('sepp', '', 'MyPw');
if (PEAR::isError($ret)) {
    echo $ret->getMessage();
    exit;
} 
$ret = $f->delAccount('karli');
if (PEAR::isError($ret)) {
    echo $ret->getMessage();
    exit;
} 

$status = $f->save();

if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
}

?>

File_SMBPasswd::printAccounts()

File_SMBPasswd::printAccounts() – prints the contents of an existing smbpasswd file

Synopsis

void File_SMBPasswd::printAccounts ( )

Description

Print all accounts of the loaded smbpasswd file.

Return value

void

Note

This function can not be called statically.

Example

Using File_SMBPasswd::printAccounts()

<?php
require_once('File/SMBPasswd.php');

$f     = new File_SMBPasswd('/usr/local/private/smbpasswd');
$f->load();
$f->printaccounts();
  
?>