Documentation

Horde_Auth_Cyrsql extends Horde_Auth_Sql
in package

The Horde_Auth_Cyrsql class provides a SQL implementation of the Horde authentication system for the Cyrus IMAP server. Most of the functionality is the same as for the SQL class; only what is different overrides the parent class implementations.

The table structure for the auth system is as follows:

CREATE TABLE accountuser (
    username    VARCHAR(255) BINARY NOT NULL DEFAULT '',
    password    VARCHAR(32) BINARY NOT NULL DEFAULT '',
    prefix      VARCHAR(50) NOT NULL DEFAULT '',
    domain_name VARCHAR(255) NOT NULL DEFAULT '',
    UNIQUE KEY username (username)
);

CREATE TABLE adminuser (
    username    VARCHAR(50) BINARY NOT NULL DEFAULT '',
    password    VARCHAR(50) BINARY NOT NULL DEFAULT '',
    type        INT(11) NOT NULL DEFAULT '0',
    SID         VARCHAR(255) NOT NULL DEFAULT '',
    home        VARCHAR(255) NOT NULL DEFAULT '',
    PRIMARY KEY (username)
);

CREATE TABLE alias (
    alias       VARCHAR(255) NOT NULL DEFAULT '',
    dest        LONGTEXT,
    username    VARCHAR(50) NOT NULL DEFAULT '',
    status      INT(11) NOT NULL DEFAULT '1',
    PRIMARY KEY (alias)
);

CREATE TABLE domain (
    domain_name VARCHAR(255) NOT NULL DEFAULT '',
    prefix      VARCHAR(50) NOT NULL DEFAULT '',
    maxaccounts INT(11) NOT NULL DEFAULT '20',
    quota       INT(10) NOT NULL DEFAULT '20000',
    transport   VARCHAR(255) NOT NULL DEFAULT 'cyrus',
    freenames   ENUM('YES','NO') NOT NULL DEFAULT 'NO',
    freeaddress ENUM('YES','NO') NOT NULL DEFAULT 'NO',
    PRIMARY KEY (domain_name),
    UNIQUE KEY prefix (prefix)
);

CREATE TABLE domainadmin (
    domain_name VARCHAR(255) NOT NULL DEFAULT '',
    adminuser   VARCHAR(255) NOT NULL DEFAULT ''
);

CREATE TABLE search (
    search_id   VARCHAR(255) NOT NULL DEFAULT '',
    search_sql  TEXT NOT NULL,
    perpage     INT(11) NOT NULL DEFAULT '0',
    timestamp   TIMESTAMP(14) NOT NULL,
    PRIMARY KEY (search_id),
    KEY search_id (search_id)
);

CREATE TABLE virtual (
    alias       VARCHAR(255) NOT NULL DEFAULT '',
    dest        LONGTEXT,
    username    VARCHAR(50) NOT NULL DEFAULT '',
    status      INT(11) NOT NULL DEFAULT '1',
    KEY alias (alias)
);

CREATE TABLE log (
    id          INT(11) NOT NULL AUTO_INCREMENT,
    msg         TEXT NOT NULL,
    user        VARCHAR(255) NOT NULL DEFAULT '',
    host        VARCHAR(255) NOT NULL DEFAULT '',
    time        DATETIME NOT NULL DEFAULT '2000-00-00 00:00:00',
    pid         VARCHAR(255) NOT NULL DEFAULT '',
    PRIMARY KEY (id)
);
Tags
author

Ilya Krel mail@krel.org

author

Jan Schneider jan@horde.org

category

Horde

copyright

2002-2017 Horde LLC

license

http://www.horde.org/licenses/lgpl21 LGPL-2.1

Table of Contents

$_capabilities  : array<string|int, mixed>
An array of capabilities, so that the driver can report which operations it supports and which it doesn't.
$_credentials  : array<string|int, mixed>
The credentials currently being authenticated.
$_db  : Horde_Db_Adapter
Handle for the current database connection.
$_error  : array<string|int, mixed>
Authentication error information.
$_history_api  : Horde_History
History object.
$_imap  : Horde_Imap_Client_Base
Horde_Imap_Client object.
$_lock_api  : Horde_Lock
Lock object.
$_logger  : Horde_Log_Logger
Logger object.
$_params  : array<string|int, mixed>
Hash containing parameters needed for the drivers.
__construct()  : mixed
Constructor.
addUser()  : mixed
Add a set of authentication credentials.
authenticate()  : bool
Finds out if a set of login credentials are valid, and if requested, mark the user as logged in in the current session.
exists()  : bool
Checks if $userId exists in the system.
getCredential()  : mixed
Returns internal credential value(s).
getError()  : mixed
Returns the error type or message for an invalid authentication.
getParam()  : string
Returns the named parameter for the current auth driver.
hasCapability()  : bool
Queries the current driver to find out if it supports the given capability.
isLocked()  : bool|array<string|int, mixed>
Returns whether a user is currently locked.
listUsers()  : mixed
List all users in the system.
lockUser()  : mixed
Locks a user indefinitely or for a specified time.
removeUser()  : mixed
Delete a set of authentication credentials.
resetPassword()  : string
Reset a user's password. Used for example when the user does not remember the existing password.
searchUsers()  : array<string|int, mixed>
Searches the users for a substring.
setCredential()  : mixed
Sets an internal credential value.
setError()  : mixed
Sets the error message for an invalid authentication.
transparent()  : bool
Automatic authentication.
unlockUser()  : mixed
Unlocks a user and optionally resets the bad login count.
updateUser()  : mixed
Update a set of authentication credentials.
validateAuth()  : bool
Checks for triggers that may invalidate the current auth.
_authenticate()  : mixed
Find out if a set of login credentials are valid.
_badLogin()  : mixed
Handles a bad login.
_comparePasswords()  : bool
Compare an encrypted password to a plaintext string to see if they match.
_resetBadLogins()  : mixed
Resets the bad login counter.
_sort()  : array<string|int, mixed>
Basic sort implementation.
_calc_expiration()  : int
Calculate a timestamp and return it along with the field name

Properties

$_capabilities

An array of capabilities, so that the driver can report which operations it supports and which it doesn't.

protected array<string|int, mixed> $_capabilities = array('add' => \true, 'list' => \true, 'remove' => \true, 'resetpassword' => \false, 'update' => \true, 'authenticate' => \true)

$_credentials

The credentials currently being authenticated.

protected array<string|int, mixed> $_credentials = array('change' => \false, 'credentials' => array(), 'expire' => \null, 'userId' => '')

$_db

Handle for the current database connection.

protected Horde_Db_Adapter $_db

$_error

Authentication error information.

protected array<string|int, mixed> $_error

$_history_api

History object.

protected Horde_History $_history_api

$_imap

Horde_Imap_Client object.

protected Horde_Imap_Client_Base $_imap

$_lock_api

Lock object.

protected Horde_Lock $_lock_api

$_logger

Logger object.

protected Horde_Log_Logger $_logger

$_params

Hash containing parameters needed for the drivers.

protected array<string|int, mixed> $_params = array()

Methods

__construct()

Constructor.

public __construct([array<string|int, mixed> $params = array() ]) : mixed
Parameters
$params : array<string|int, mixed> = array()

Parameters:

  • domain_field: (string) If set to anything other than 'none' this is used as field name where domain is stored. DEFAULT: 'domain_name'
  • folders: (array) An array of folders to create under username. DEFAULT: NONE
  • hidden_accounts: (array) An array of system accounts to hide from the user interface. DEFAULT: None.
  • imap: (Horde_Imap_Client_Base) [REQUIRED] An IMAP client object.
  • quota: (integer) The quota (in kilobytes) to grant on the mailbox. DEFAULT: NONE
  • userhierarchy: (string) The user hierarchy prefix (UTF-8). DEFAULT: 'user.'
Tags
throws
InvalidArgumentException
Return values
mixed —

addUser()

Add a set of authentication credentials.

public addUser(string $userId, array<string|int, mixed> $credentials) : mixed
Parameters
$userId : string

The userId to add.

$credentials : array<string|int, mixed>

The credentials to add.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

authenticate()

Finds out if a set of login credentials are valid, and if requested, mark the user as logged in in the current session.

public authenticate(string $userId, array<string|int, mixed> $credentials[, bool $login = true ]) : bool
Parameters
$userId : string

The userId to check.

$credentials : array<string|int, mixed>

The credentials to check.

$login : bool = true

Whether to log the user in. If false, we'll only test the credentials and won't modify the current session. Defaults to true.

Return values
bool —

Whether or not the credentials are valid.

exists()

Checks if $userId exists in the system.

public exists(string $userId) : bool
Parameters
$userId : string

User ID for which to check

Return values
bool —

Whether or not $userId already exists.

getCredential()

Returns internal credential value(s).

public getCredential([mixed $name = null ]) : mixed
Parameters
$name : mixed = null

The credential value to get. If null, will return the entire credential list. Valid names:

  • 'change': (boolean) Do credentials need to be changed?
  • 'credentials': (array) The credentials needed to authenticate.
  • 'expire': (integer) UNIX timestamp of the credential expiration date.
  • 'userId': (string) The user ID.
Return values
mixed —

The credential information, or null if the credential doesn't exist.

getError()

Returns the error type or message for an invalid authentication.

public getError([bool $msg = false ]) : mixed
Parameters
$msg : bool = false

If true, returns the message string (if set).

Return values
mixed —

Error type, error message (if $msg is true) or false if entry doesn't exist.

getParam()

Returns the named parameter for the current auth driver.

public getParam(string $param) : string
Parameters
$param : string

The parameter to fetch.

Return values
string —

The parameter's value, or null if it doesn't exist.

hasCapability()

Queries the current driver to find out if it supports the given capability.

public hasCapability(string $capability) : bool
Parameters
$capability : string

The capability to test for.

Return values
bool —

Whether or not the capability is supported.

isLocked()

Returns whether a user is currently locked.

public isLocked(string $userId[, bool $show_details = false ]) : bool|array<string|int, mixed>
Parameters
$userId : string

The user to check.

$show_details : bool = false

Return timeout too?

Tags
throws
Horde_Auth_Exception
Return values
bool|array<string|int, mixed> —

If $show_details is a true, an array with 'locked' and 'lock_timeout' values. Whether the user is locked, otherwise.

listUsers()

List all users in the system.

public listUsers([bool $sort = false ]) : mixed
Parameters
$sort : bool = false

Sort the users?

Tags
throws
Horde_Auth_Exception
Return values
mixed —

The array of userIds.

lockUser()

Locks a user indefinitely or for a specified time.

public lockUser(string $userId, int $time) : mixed
Parameters
$userId : string

The user to lock.

$time : int

The duration in minutes, 0 = permanent.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

removeUser()

Delete a set of authentication credentials.

public removeUser(string $userId) : mixed
Parameters
$userId : string

The userId to delete.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

resetPassword()

Reset a user's password. Used for example when the user does not remember the existing password.

public resetPassword(string $userId) : string
Parameters
$userId : string

The user id for which to reset the password.

Tags
throws
Horde_Auth_Exception
Return values
string —

The new password on success.

searchUsers()

Searches the users for a substring.

public searchUsers(string $search) : array<string|int, mixed>
Parameters
$search : string

The search term.

Tags
since

Horde_Auth 2.2.0

Return values
array<string|int, mixed> —

A list of all matching users.

setCredential()

Sets an internal credential value.

public setCredential(string $type, mixed $value) : mixed
Parameters
$type : string

The credential name to set. See getCredential() for the list of valid credentials/types.

$value : mixed

The credential value to set.

Return values
mixed —

setError()

Sets the error message for an invalid authentication.

public setError(string $type[, string $msg = null ]) : mixed
Parameters
$type : string

The type of error (Horde_Auth::REASON_* constant).

$msg : string = null

The error message/reason for invalid authentication.

Return values
mixed —

transparent()

Automatic authentication.

public transparent() : bool

Transparent authentication should set 'userId', 'credentials', or 'params' in $this->_credentials as needed - these values will be used to set the credentials in the session.

Transparent authentication should normally never throw an error - false should be returned.

Tags
throws
Horde_Auth_Exception
Return values
bool —

Whether transparent login is supported.

unlockUser()

Unlocks a user and optionally resets the bad login count.

public unlockUser(string $userId[, bool $resetBadLogins = false ]) : mixed
Parameters
$userId : string

The user to unlock.

$resetBadLogins : bool = false

Reset bad login counter?

Tags
throws
Horde_Auth_Exception
Return values
mixed —

updateUser()

Update a set of authentication credentials.

public updateUser(string $oldID, string $newID, array<string|int, mixed> $credentials) : mixed
Parameters
$oldID : string

The old userId.

$newID : string

The new userId. [NOT SUPPORTED]

$credentials : array<string|int, mixed>

The new credentials

Tags
throws
Horde_Auth_Exception
Return values
mixed —

validateAuth()

Checks for triggers that may invalidate the current auth.

public validateAuth() : bool

These triggers are independent of the credentials.

Return values
bool —

True if the results of authenticate() are still valid.

_authenticate()

Find out if a set of login credentials are valid.

protected _authenticate(string $userId, array<string|int, mixed> $credentials) : mixed
Parameters
$userId : string

The userId to check.

$credentials : array<string|int, mixed>

The credentials to use.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

_badLogin()

Handles a bad login.

protected _badLogin(string $userId) : mixed
Parameters
$userId : string

The user with a bad login.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

_comparePasswords()

Compare an encrypted password to a plaintext string to see if they match.

protected _comparePasswords(string $encrypted, string $plaintext) : bool
Parameters
$encrypted : string

The crypted password to compare against.

$plaintext : string

The plaintext password to verify.

Return values
bool —

True if matched, false otherwise.

_resetBadLogins()

Resets the bad login counter.

protected _resetBadLogins(string $userId) : mixed
Parameters
$userId : string

The user to reset.

Tags
throws
Horde_Auth_Exception
Return values
mixed —

_sort()

Basic sort implementation.

protected _sort(array<string|int, mixed> $users, bool $sort) : array<string|int, mixed>

If the backend has listUsers and doesn't have a native sorting option, fall back to this method.

Parameters
$users : array<string|int, mixed>

An array of usernames.

$sort : bool

Whether to sort or not.

Return values
array<string|int, mixed> —

the users, sorted or not

_calc_expiration()

Calculate a timestamp and return it along with the field name

private _calc_expiration(string $type) : int
Parameters
$type : string

The timestamp parameter.

Return values
int —

'timestamp' intended field value or null

Search results