\coreProfileRADIUS

This class represents a profile with third-party EAP handling (i.e. a "real" RADIUS profile).

Profiles can inherit attributes from their IdP, if the IdP has some. Otherwise, one can set attribute in the Profile directly. If there is a conflict between IdP-wide and Profile-wide attributes, the more specific ones (i.e. Profile) win.

Summary

Methods
Properties
Constants
__construct()
profileFromRealm()
getRealmCheckOuterUsername()
updateFreshness()
getFreshness()
testCache()
updateCache()
incrementDownloadStats()
getUserDownloadStats()
destroy()
setRealm()
addSupportedEapMethod()
getEapMethodsinOrderOfPreference()
isEapTypeDefinitionComplete()
listDevices()
getCollapsedAttributes()
readinessLevel()
prepShowtime()
getAttributes()
getAttributeValue()
beginFlushAttributes()
commitFlushAttributes()
flushAttributes()
addAttribute()
fetchRawDataByIndex()
isDataRestricted()
__destruct()
createTemporaryDirectory()
rrmdir()
addAttributeEAPSpecific()
addAttributeDeviceSpecific()
setAnonymousIDSupport()
setRealmCheckUser()
setInputVerificationPreference()
beginFlushMethodLevelAttributes()
$institution
$instName
$realm
$identifier
$name
HIDDEN
AVAILABLE
UNAVAILABLE
INCOMPLETE
NOTCONFIGURED
READINESS_LEVEL_NOTREADY
READINESS_LEVEL_SUFFICIENTCONFIG
READINESS_LEVEL_SHOWTIME
L_OK
L_REMARK
L_WARN
L_ERROR
saveDownloadDetails()
fetchEAPMethods()
levelPrecedenceAttributeJoin()
addInternalAttributes()
addDatabaseAttributes()
retrieveOptionsFromDatabase()
$privEaptypes
$idpNumberOfProfiles
$idpAttributes
$fedAttributes
$frontendHandle
$attributes
$databaseType
$entityOptionTable
$entityIdColumn
$databaseHandle
$loggerInstance
$languageInstance
N/A
readyForShowtime()
getRelevantIdentifier()
fetchDeviceOrEAPLevelAttributes()
addAttributeAllLevels()
$deviceLevelAttributes
$eapLevelAttributes
N/A

Constants

HIDDEN

HIDDEN = -1

AVAILABLE

AVAILABLE = 0

UNAVAILABLE

UNAVAILABLE = 1

INCOMPLETE

INCOMPLETE = 2

NOTCONFIGURED

NOTCONFIGURED = 3

READINESS_LEVEL_NOTREADY

READINESS_LEVEL_NOTREADY = 0

READINESS_LEVEL_SUFFICIENTCONFIG

READINESS_LEVEL_SUFFICIENTCONFIG = 1

READINESS_LEVEL_SHOWTIME

READINESS_LEVEL_SHOWTIME = 2

L_OK

L_OK = 0

L_REMARK

L_REMARK = 4

L_WARN

L_WARN = 32

L_ERROR

L_ERROR = 256

Properties

$institution

$institution : 

DB identifier of the parent institution of this profile

Type

$instName

$instName : 

name of the parent institution of this profile in the current language

Type

$realm

$realm : 

realm of this profile (empty string if unset)

Type

$identifier

$identifier : 

the unique identifier of this entity instance refers to the integer row name in the DB -> int; Federation has no own DB, so the identifier is of no use there -> use Fedearation->$tld

Type

— identifier of the entity instance

$name

$name : 

the name of the entity in the current locale

Type

$privEaptypes

$privEaptypes : mixed|string|int

This array holds the supported EAP types (in object representation).

They are not synced against the DB after instantiation.

Type

mixed|string|int —

$idpNumberOfProfiles

$idpNumberOfProfiles : 

number of profiles of the IdP this profile is attached to

Type

$idpAttributes

$idpAttributes : 

IdP-wide attributes of the IdP this profile is attached to

Type

$fedAttributes

$fedAttributes : 

Federation level attributes that this profile is attached to via its IdP

Type

$frontendHandle

$frontendHandle : \core\DBConnection

This class also needs to handle frontend operations, so needs its own access to the FRONTEND datbase. This member stores the corresponding handle.

Type

\core\DBConnection —

$attributes

$attributes : mixed|string|int

This variable gets initialised with the known IdP attributes in the constructor. It never gets updated until the object is destroyed. So if attributes change in the database, and IdP attributes are to be queried afterwards, the object needs to be re-instantiated to have current values in this variable.

Type

mixed|string|int — of entity's attributes

$databaseType

$databaseType : 

The database to query for attributes regarding this entity

Type

— DB type

$entityOptionTable

$entityOptionTable : 

This variable contains the name of the table that stores the entity's options

Type

— DB table name

$entityIdColumn

$entityIdColumn : 

column name to find entity in that table

Type

— DB column name of entity

$databaseHandle

$databaseHandle : \core\DBConnection

We need database access. Be sure to instantiate the singleton, and then use its instance (rather than always accessing everything statically)

Type

\core\DBConnection — the instance of the default database we talk to usually

$loggerInstance

$loggerInstance : \core\common\Logging

We occasionally log stuff (debug/audit). Have an initialised Logging instance nearby is sure helpful.

Type

\core\common\Logging —

$languageInstance

$languageInstance : \core\common\Language

access to language settings to be able to switch textDomain

Type

\core\common\Language —

$deviceLevelAttributes

$deviceLevelAttributes : mixed|string|int

This array holds all attributes which are defined on device level only

Type

mixed|string|int —

$eapLevelAttributes

$eapLevelAttributes : mixed|string|int

This array holds all attributes which are defined on device level only

Type

mixed|string|int —

Methods

__construct()

__construct(  profileId, \core\IdP  idpObject = NULL) 

Class constructor for existing profiles (use IdP::newProfile() to actually create one). Retrieves all attributes and supported EAP types from the DB and stores them in the priv_ arrays.

sub-classes need to set the property $realm, $name themselves!

Parameters

profileId

identifier of the profile in the DB

\core\IdP idpObject

optionally, the institution to which this Profile belongs. Saves the construction of the IdP instance. If omitted, an extra query and instantiation is executed to find out.

profileFromRealm()

profileFromRealm( realm) 

find a profile, given its realm

Parameters

realm

getRealmCheckOuterUsername()

getRealmCheckOuterUsername() : 

Constructs the outer ID which should be used during realm tests. Obviously can only do something useful if the realm is known to the system.

Returns

the outer ID to use for realm check operations

updateFreshness()

updateFreshness() 

when options in the DB change, this can mean generated installers become stale. sub-classes must define whether this is the case for them

getFreshness()

getFreshness() 

gets the last-modified timestamp (useful for caching "dirty" check)

testCache()

testCache(  device) : 

This function tests if the configurator needs to be regenerated (properties of the Profile may have changed since the last configurator generation).

Parameters

device

device ID to check

Returns

a string with the path to the configurator download, or NULL if it needs to be regenerated

updateCache()

updateCache(  device,   path,   mime,   integerEapType) 

Updates database with new installler location

Parameters

device

the device identifier string

path

the path where the new installer can be found

mime

the MIME type of the new installer

integerEapType

the numeric representation of the EAP type for which this installer was generated

incrementDownloadStats()

incrementDownloadStats(  device,   area) : 

Log a new download for our stats

Parameters

device

the device id string

area

either admin or user

Returns

TRUE if incrementing worked, FALSE if not

getUserDownloadStats()

getUserDownloadStats(  device = NULL) : 

Retrieve current download stats from database, either for one specific device or for all devices

Parameters

device

the device id string

Returns

user downloads of this profile; if device is given, returns the counter as int, otherwise an array with devicename => counter

destroy()

destroy() 

Deletes the profile from database and uninstantiates itself.

Works fine also for Silver Bullet; the first query will simply do nothing because there are no stored options

setRealm()

setRealm(  realm) 

Specifies the realm of this profile.

Forcefully type-hinting $realm parameter to string - Scrutinizer seems to think that it can alternatively be an array<integer,?> which looks like a false positive. If there really is an issue, let PHP complain about it at runtime.

Parameters

realm

the realm (potentially with the local@ part that should be used for anonymous identities)

addSupportedEapMethod()

addSupportedEapMethod(\core\common\EAP  type,   preference) 

register new supported EAP method for this profile

Parameters

\core\common\EAP type

The EAP Type, as defined in class EAP

preference

preference of this EAP Type. If a preference value is re-used, the order of EAP types of the same preference level is undefined.

getEapMethodsinOrderOfPreference()

getEapMethodsinOrderOfPreference(  completeOnly) : mixed|string|int

Produces an array of EAP methods supported by this profile, ordered by preference

Parameters

completeOnly

if set and non-zero limits the output to methods with complete information

Returns

mixed|string|int —

list of EAP methods, (in object representation)

isEapTypeDefinitionComplete()

isEapTypeDefinitionComplete(\core\common\EAP  eaptype) : 

Performs a sanity check for a given EAP type - did the admin submit enough information to create installers for him?

Parameters

\core\common\EAP eaptype

the EAP type

Returns

TRUE if the EAP type is complete; an array of missing attribues if it's incomplete; FALSE if it's incomplete for other reasons

listDevices()

listDevices() : mixed|string|int

list all devices marking their availabiblity and possible redirects

Returns

mixed|string|int —

of device ids display names and their status

getCollapsedAttributes()

getCollapsedAttributes(mixed|string|int  eap = []) : mixed|string|int

prepare profile attributes for device modules Gets profile attributes taking into account the most specific level on which they may be defined as wel as the chosen language.

can be called with an optional $eap argument

Parameters

mixed|string|int eap

if specified, retrieves all attributes except those not pertaining to the given EAP type

Returns

mixed|string|int —

list of attributes in collapsed style (index is the attrib name, value is an array of different values)

readinessLevel()

readinessLevel() 

Does the profile contain enough information to generate installers with it? Silverbullet will always return TRUE; RADIUS profiles need to do some heavy lifting here.

  • @return int one of the constants above which tell if enough info is set to enable installers

prepShowtime()

prepShowtime() 

set the showtime property if prepShowTime says that there is enough info *and* the admin flagged the profile for showing

getAttributes()

getAttributes(  optionName = NULL) : mixed|string|int

This function retrieves the entity's attributes.

If called with the optional parameter, only attribute values for the attribute name in $optionName are retrieved; otherwise, all attributes are retrieved. The retrieval is in-memory from the internal attributes class member - no DB callback, so changes in the database during the class instance lifetime are not considered.

Parameters

optionName

optionally, the name of the attribute that is to be retrieved

Returns

mixed|string|int —

of arrays of attributes which were set for this IdP

getAttributeValue()

getAttributeValue(mixed|string|int  attributeArray, string|int  index1, string|int  index2) : \core\any

This is a helper fuction to retreave a value from two-dimmentional arrays The function tests if the value for the first indes is defined and then the same with the second and finally returns the value if something on the way is not defined, NULL is returned

Parameters

mixed|string|int attributeArray
string|int index1
string|int index2

Returns

\core\any —

value or NULL

beginFlushAttributes()

beginFlushAttributes() 

overrides the parent class definition: in Profile, we additionally need to delete the supported EAP types list in addition to just flushing the normal DB-based attributes

commitFlushAttributes()

commitFlushAttributes(mixed|string|int  tobedeleted) 

after a beginFlushAttributes, deletes all attributes which are in the tobedeleted array.

Parameters

mixed|string|int tobedeleted

array of database rows which are to be deleted

flushAttributes()

flushAttributes() 

deletes all attributes of this entity from the database

addAttribute()

addAttribute(  attrName,   attrLang,   attrValue) 

this is the variant which sets attributes which are valid profile-wide

Parameters

attrName

name of the attribute to set

attrLang

language of the attribute to set (if multilang, can be NULL)

attrValue

value of the attribute to set

fetchRawDataByIndex()

fetchRawDataByIndex(  table,   row) : string|bool

Retrieves data from the underlying tables, for situations where instantiating the IdP or Profile object is inappropriate

Parameters

table

institution_option or profile_option

row

rowindex

Returns

string|bool —

the data, or FALSE if something went wrong

isDataRestricted()

isDataRestricted(  table,   row) : 

Checks if a raw data pointer is public data (return value FALSE) or if yes who the authorised admins to view it are (return array of user IDs)

Parameters

table

which database table is this about

row

row index of the table

Returns

FALSE if the data is public, an array of owners of the data if it is NOT public

__destruct()

__destruct() 

destroys the entity.

Logs the end of lifetime of the entity to the debug log on level 5.

createTemporaryDirectory()

createTemporaryDirectory(  purpose = installer,   failIsFatal = 1) : mixed|string|int

create a temporary directory and return the location

Parameters

purpose

one of 'installer', 'logo', 'test' defined the purpose of the directory

failIsFatal

decides if a creation failure should cause an error; defaults to true

Returns

mixed|string|int —

the tuple of: base path, absolute path for directory, directory name

rrmdir()

rrmdir(  dir) 

this direcory delete function has been copied from PHP documentation

Parameters

dir

name of the directory to delete

addAttributeEAPSpecific()

addAttributeEAPSpecific(  attrName,   attrLang,   attrValue,   eapType) 

this is the variant which sets attributes for specific EAP types

Parameters

attrName

name of the attribute to set

attrLang

language of the attribute to set (if multilang, can be NULL)

attrValue

value of the attribute to set

eapType

identifier of the EAP type in the database. 0 if the attribute is valid for all EAP types.

addAttributeDeviceSpecific()

addAttributeDeviceSpecific(  attrName,   attrLang,   attrValue,   device) 

this is the variant which sets attributes for specific devices

Parameters

attrName

name of the attribute to set

attrLang

language of the attribute to set (if multilang, can be NULL)

attrValue

value of the attribute to set

device

identifier of the device in the databse. Omit the argument if attribute is valid for all devices.

setAnonymousIDSupport()

setAnonymousIDSupport(  shallwe) 

Toggle anonymous outer ID support.

Parameters

shallwe

TRUE to enable outer identities (needs valid $realm), FALSE to disable

setRealmCheckUser()

setRealmCheckUser(  shallwe,   localpart = NULL) 

Toggle special username for realm checks

Parameters

shallwe

TRUE to enable outer identities (needs valid $realm), FALSE to disable

localpart

the username

setInputVerificationPreference()

setInputVerificationPreference(  verify,   hint) 

should username be verified or even prefilled?

Parameters

verify

should the user input be verified by the installer?

hint

should the user be shown username formatting hints?

beginFlushMethodLevelAttributes()

beginFlushMethodLevelAttributes(  eapId,   deviceId) : mixed|string|int

deletes all attributes in this profile on the method level

Parameters

eapId

the numeric identifier of the EAP method

deviceId

the name of the device

Returns

mixed|string|int —

list of row id's of file-based attributes which weren't deleted

saveDownloadDetails()

saveDownloadDetails( idpIdentifier,  profileId,  deviceId,  area,  lang,  eapType) 

Parameters

idpIdentifier
profileId
deviceId
area
lang
eapType

fetchEAPMethods()

fetchEAPMethods() 

each profile has supported EAP methods, so get this from DB, Silver Bullet has one static EAP method.

levelPrecedenceAttributeJoin()

levelPrecedenceAttributeJoin(mixed|string|int  existing, mixed|string|int  new,   newlevel) : mixed|string|int

join new attributes to existing ones, but only if not already defined on a different level in the existing set

Parameters

mixed|string|int existing

the already existing attributes

mixed|string|int new

the new set of attributes

newlevel

the level of the new attributes

Returns

mixed|string|int —

the new set of attributes

addInternalAttributes()

addInternalAttributes(mixed|string|int  internalAttributes) : mixed|string|int

internal helper - some attributes are added by the constructor "ex officio" without actual input from the admin. We can streamline their addition in this function to avoid duplication.

Parameters

mixed|string|int internalAttributes
  • only names and value

Returns

mixed|string|int —

full attributes with all properties set

addDatabaseAttributes()

addDatabaseAttributes() : mixed|string|int

Retrieves profile attributes stored in the database

Returns

mixed|string|int —

The attributes in one array

retrieveOptionsFromDatabase()

retrieveOptionsFromDatabase(  query,   level) : mixed|string|int

retrieve attributes from a database. Only does SELECT queries.

Parameters

query

sub-classes set the query to execute to get to the options

level

the retrieved options get flagged with this "level" identifier

Returns

mixed|string|int —

the attributes in one array

readyForShowtime()

readyForShowtime() : 

Checks if the profile has enough information to have something to show to end users. This does not necessarily mean that there's a fully configured EAP type - it is sufficient if a redirect has been set for at least one device.

Returns

TRUE if enough information for showtime is set; FALSE if not

getRelevantIdentifier()

getRelevantIdentifier() : string|int

How is the object identified in the database?

Throws

\Exception

Returns

string|int —

fetchDeviceOrEAPLevelAttributes()

fetchDeviceOrEAPLevelAttributes(  devicesOrEAPMethods) : mixed|string|int

Retrieves attributes which pertain either to a specific EAP type or a specific device type.

Parameters

devicesOrEAPMethods

is either "DEVICES" or "STRINGS". Any other value throws an Exception

Throws

\Exception

Returns

mixed|string|int —

the list attributes in an array

addAttributeAllLevels()

addAttributeAllLevels(  attrName,   attrLang,   attrValue,   eapType,   device) 

adds an attribute to this profile; not the usual function from EntityWithDBProperties because this class also has per-EAP-type and per-device sub-settings

Parameters

attrName

name of the attribute to set

attrLang

language of the attribute to set (if multilang, can be NULL)

attrValue

value of the attribute to set

eapType

identifier of the EAP type in the database. 0 if the attribute is valid for all EAP types.

device

identifier of the device in the databse. Omit the argument if attribute is valid for all devices.