\coreProfileSilverbullet

This class represents an EAP 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()
randomString()
invitationMailSubject()
invitationMailBody()
setAnonymousIDSupport()
issueCertificate()
triggerNewOCSPStatement()
revokeCertificate()
tokenStatus()
findUserIdFromCert()
userStatus()
getUserExpiryDate()
setUserExpiryDate()
listAllUsers()
listActiveUsers()
addUser()
deactivateUser()
generateTokenLink()
createInvitation()
revokeInvitation()
refreshEligibility()
$institution
$instName
$realm
$identifier
$name
$termsAndConditions
HIDDEN
AVAILABLE
UNAVAILABLE
INCOMPLETE
NOTCONFIGURED
READINESS_LEVEL_NOTREADY
READINESS_LEVEL_SUFFICIENTCONFIG
READINESS_LEVEL_SHOWTIME
L_OK
L_REMARK
L_WARN
L_ERROR
SB_TOKENSTATUS_VALID
SB_TOKENSTATUS_PARTIALLY_REDEEMED
SB_TOKENSTATUS_REDEEMED
SB_TOKENSTATUS_EXPIRED
SB_TOKENSTATUS_INVALID
SB_CERTSTATUS_VALID
SB_CERTSTATUS_EXPIRED
SB_CERTSTATUS_REVOKED
SB_ACKNOWLEDGEMENT_REQUIRED_DAYS
PRODUCTNAME
saveDownloadDetails()
fetchEAPMethods()
levelPrecedenceAttributeJoin()
addInternalAttributes()
addDatabaseAttributes()
retrieveOptionsFromDatabase()
$privEaptypes
$idpNumberOfProfiles
$idpAttributes
$fedAttributes
$frontendHandle
$attributes
$databaseType
$entityOptionTable
$entityIdColumn
$databaseHandle
$loggerInstance
$languageInstance
N/A
readyForShowtime()
getRelevantIdentifier()
generateCsr()
signCsr()
httpRequest()
enumerateCertDetails()
generateToken()
No private properties found
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

SB_TOKENSTATUS_VALID

SB_TOKENSTATUS_VALID = 0

SB_TOKENSTATUS_PARTIALLY_REDEEMED

SB_TOKENSTATUS_PARTIALLY_REDEEMED = 1

SB_TOKENSTATUS_REDEEMED

SB_TOKENSTATUS_REDEEMED = 2

SB_TOKENSTATUS_EXPIRED

SB_TOKENSTATUS_EXPIRED = 3

SB_TOKENSTATUS_INVALID

SB_TOKENSTATUS_INVALID = 4

SB_CERTSTATUS_VALID

SB_CERTSTATUS_VALID = 1

SB_CERTSTATUS_EXPIRED

SB_CERTSTATUS_EXPIRED = 2

SB_CERTSTATUS_REVOKED

SB_CERTSTATUS_REVOKED = 3

SB_ACKNOWLEDGEMENT_REQUIRED_DAYS

SB_ACKNOWLEDGEMENT_REQUIRED_DAYS = 365

PRODUCTNAME

PRODUCTNAME = Managed IdP

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

$termsAndConditions

$termsAndConditions : 

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 —

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 installer location; NOOP because we do not cache anything in Silverbullet

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 inter-representation of the EAP type that is configured in this installer

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() : mixed|string|int

deletes all attributes in this profile except the _file ones, these are reported as array

Returns

mixed|string|int —

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

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) 

Adds an attribute for the entity instance into the database. Multiple instances of the same attribute are supported.

Parameters

attrName

Name of the attribute. This must be a well-known value from the profile_option_dict table in the DB.

attrLang

language of the attribute. Can be NULL.

attrValue

Value of the attribute. Can be anything; will be stored in the DB as-is.

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

randomString()

randomString(  length,   keyspace = 23456789abcdefghijkmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ) : 

produces a random string

Parameters

length

the length of the string to produce

keyspace

the pool of characters to use for producing the string

Throws

\Exception

Returns

invitationMailSubject()

invitationMailSubject() : 

returns the subject to use in an invitation mail

Returns

invitationMailBody()

invitationMailBody(  invitationLink) : 

returns the body to use in an invitation mail

Parameters

invitationLink

the activation token link to embed

Returns

setAnonymousIDSupport()

setAnonymousIDSupport(  shallwe) 

It's EAP-TLS and there is no point in anonymity

Parameters

shallwe

issueCertificate()

issueCertificate(  token,   importPassword) : mixed|string|int

issue a certificate based on a token

Parameters

token
importPassword

Returns

mixed|string|int —

triggerNewOCSPStatement()

triggerNewOCSPStatement(  serial) : 

triggers a new OCSP statement for the given serial number

Parameters

serial

the serial number of the cert in question (decimal)

Returns

DER-encoded OCSP status info (binary data!)

revokeCertificate()

revokeCertificate(  serial) : mixed|string|int

revokes a certificate

Parameters

serial

the serial number of the cert to revoke (decimal!)

Returns

mixed|string|int —

with revocation information

tokenStatus()

tokenStatus(  tokenvalue) : mixed|string|int

find out about the properties of an activation token

Parameters

tokenvalue

Returns

mixed|string|int —

the token properties

findUserIdFromCert()

findUserIdFromCert(  certUsername) : mixed|string|int

For a given certificate username, find the profile and username in CAT this needs to be static because we do not have a known profile instance

Parameters

certUsername

a username from CN or sAN:email

Returns

mixed|string|int —

userStatus()

userStatus(  userId) : mixed|string|int

find out about the status of a given SB user; retrieves the info regarding all his tokens (and thus all his certificates)

Parameters

userId

Returns

mixed|string|int —

of tokenStatus arrays

getUserExpiryDate()

getUserExpiryDate(  userId) : 

finds out the expiry date of a given user

Parameters

userId

Returns

setUserExpiryDate()

setUserExpiryDate(  userId, \DateTime  date) 

sets the expiry date of a user to a new date of choice

Parameters

userId
\DateTime date

listAllUsers()

listAllUsers() : mixed|string|int

lists all users of this SB profile

Returns

mixed|string|int —

listActiveUsers()

listActiveUsers() : mixed|string|int

lists all users which are currently active (i.e. have pending invitations and/or valid certs)

Returns

mixed|string|int —

addUser()

addUser(  username, \DateTime  expiry) : 

adds a new user to the profile

Parameters

username
\DateTime expiry

Returns

row ID of the new user in the database

deactivateUser()

deactivateUser(  userId) 

revoke all active certificates and pending invitations of a user

Parameters

userId

generateTokenLink()

generateTokenLink(  token) : 

creates a full HTTP link from the hex value of the token itself

Parameters

token

Returns

createInvitation()

createInvitation(  userId,   activationCount) 

creates a new invitation in the database

Parameters

userId
activationCount

revokeInvitation()

revokeInvitation(  invitationId) 

revokes an invitation

Parameters

invitationId

refreshEligibility()

refreshEligibility() 

updates the last_ack for all users (invoked when the admin claims to have re-verified continued eligibility of all users)

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 —

generateCsr()

generateCsr(  privateKey) : mixed|string|int

create a CSR

Parameters

privateKey

the private key to create the CSR with

Returns

mixed|string|int —

with the CSR and some meta info

signCsr()

signCsr(  csr,   expiryDays) : mixed|string|int

take a CSR and sign it with our issuing CA's certificate

Parameters

csr

the CSR

expiryDays

the number of days until the cert is going to expire

Returns

mixed|string|int —

the cert and some meta info

httpRequest()

httpRequest(  url, mixed|string|int  postValues) : 

performs an HTTP request. Currently unused, will be for external CA API calls.

Parameters

url

the URL to send the request to

mixed|string|int postValues

POST values to send

Returns

the returned HTTP content

enumerateCertDetails()

enumerateCertDetails(\mysqli_result  certQuery) : mixed|string|int

checks a certificate's status in the database and delivers its properties in an array

Parameters

\mysqli_result certQuery

Returns

mixed|string|int —

properties of the cert in questions

generateToken()

generateToken() : 

generates a new hex string to be used as an activation token

Returns