\devices\msDevice_W10

This class defines common functions needed by all Windows installers

A device is a fairly abstract notion. In most cases it represents a particular operating system or a set of operationg systems like MS Windows Vista and newer.

The purpose of this class is to preapare a setup for the device configurator, collect all necessary information from the database, taking into account limitations, that a given device may present (like a set of supported EAP methods).

All that is required from the device module is to produce a conigurator file and pass its name back to the API.

Summary

Methods
Properties
Constants
copyBasicFiles()
copyPwdFiles()
copyGeantLinkFiles()
echo_nsi()
sprint_nsi()
__construct()
writeDeviceInfo()
uuid()
setup()
calculatePreferredEapType()
writeInstaller()
__destruct()
createTemporaryDirectory()
rrmdir()
$LANGS
$codePage
$lang
$useGeantLink
$FPATH
$specialities
$supportedEapMethods
$nomenclature_fed
$nomenclature_inst
$attributes
$module_path
$selectedEap
$selectedEapObject
$sign
$signer
$device_id
$options
$support_email_substitute
$support_url_substitute
$installerBasename
$deviceUUID
L_OK
L_REMARK
L_WARN
L_ERROR
prepareInstallerLang()
combineLogo()
signInstaller()
compileNSIS()
writeNsisDefines()
msInfoFile()
writeAdditionalDeletes()
writeClientP12File()
writeTlsUserProfile()
setSupportedEapMethods()
copyFile()
translateFile()
translateString()
saveCertificateFiles()
dumpAttibutes()
determineOuterIdString()
$clientCert
$loggerInstance
$languageInstance
N/A
scaleLogo()
findSourceFile()
getInstallerBasename()
getDeviceId()
getSSIDs()
getConsortia()
saveLogoFile()
saveInfoFile()
getProfileAttributes()
prepareEapConfig()
writeWLANprofile()
writeLANprofile()
writeMainNSH()
writeProfilesNSH()
copyStandardNsi()
copyFiles()
$background
$mime_extensions
$tlsOtherUsername
N/A

Constants

L_OK

L_OK = 0

L_REMARK

L_REMARK = 4

L_WARN

L_WARN = 32

L_ERROR

L_ERROR = 256

Properties

$LANGS

$LANGS : 

Type

$codePage

$codePage : 

Type

$lang

$lang : 

Type

$useGeantLink

$useGeantLink : 

Type

$FPATH

$FPATH : 

stores the path to the temporary working directory for a module instance

Type

$specialities

$specialities : mixed|string|int

array of specialities - will be displayed on the admin download as "footnote"

Type

mixed|string|int — specialities

$supportedEapMethods

$supportedEapMethods : mixed|string|int

list of supported EAP methods

Type

mixed|string|int — EAP methods

$nomenclature_fed

$nomenclature_fed : 

the custom displayable variant of the term 'federation'

Type

$nomenclature_inst

$nomenclature_inst : 

the custom displayable variant of the term 'institution'

Type

$attributes

$attributes : mixed|string|int

Array passing all options to the device module.

$attrbutes array contains option values defined for the institution and a particular profile (possibly overriding one another) ready for the device module to consume.

For each of the options the value is another array of vales (even if only one value is present). Some attributes may be missing if they have not been configured for a viven institution or profile.

The following attributes are meant to be used by device modules:

  • general:geo_coordinates - geographical coordinates of the institution or a campus
  • support:info_file - consent file displayed to the users
  • general:logo_file - file data containing institution logo
  • support:eap_types - URL to a local support page for a specific eap methiod, not to be confused with general:url
  • support:email - email for users to contact for local instructions
  • support:phone - telephone number for users to contact for local instructions
  • support:url - URL where the user will find local instructions
  • internal:info_file - the pathname of the info_file saved in the working directory
  • internal:logo_file - array of pathnames of logo_files saved in the working directory
  • internal:CAs - the value is an array produced by X509::processCertificate() with the following filds
  • internal:SSID - an array indexed by SSID strings with values either TKIP or AES; if TKIP is set the both WPA/TKIP and WPA2/AES should be set if AES is set the this is a WPA2/AES only SSID; the consortium's defined SSIDs are always set as the first array elements. -internal:profile_count - the number of profiles for the associated IdP

these attributes are available and can be used, but the "internal" attributes are better suited for modules

  • eap:ca_file - certificate of the CA signing the RADIUS server key
  • media:SSID - additional SSID to configure, WPA2/AES only (device modules should use internal:SSID)
  • media:SSID_with_legacy - additional SSID to configure, WPA2/AES and WPA/TKIP (device modules should use internal:SSID)

Type

mixed|string|int —

$module_path

$module_path : 

stores the path to the module source location and is used by copyFile and translateFile the only reason for it to be a public variable ies that it is set by the DeviceFactory class module_path should not be used by module drivers.

Type

$selectedEap

$selectedEap : mixed|string|int

* The optimal EAP type selected given profile and device

Type

mixed|string|int —

$selectedEapObject

$selectedEapObject : 

Type

$sign

$sign : 

the path to the profile signing program device modules which require signing should use this property to exec the signer the signer program must accept two arguments - input and output file names the signer program mus operate in the local directory and filenames are relative to this directory

Type

$signer

$signer : 

Type

$device_id

$device_id : 

The string identifier of the device (don't show this to users)

Type

$options

$options : mixed|string|int

See devices-template.php for a list of available options

Type

mixed|string|int —

$support_email_substitute

$support_email_substitute : 

This string will be shown if no support email was configured by the admin

Type

$support_url_substitute

$support_url_substitute : 

This string will be shown if no support URL was configured by the admin

Type

$installerBasename

$installerBasename : 

This string should be used by all installer modules to set the installer file basename.

Type

$deviceUUID

$deviceUUID : 

stores identifier used by GEANTLink profiles

Type

$clientCert

$clientCert : 

stores the PKCS#12 DER representation of a client certificate for SilverBullet

Type

$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 —

$background

$background : 

Type

$mime_extensions

$mime_extensions : mixed|string|int

An array with shorthand definitions for MIME types

Type

mixed|string|int —

$tlsOtherUsername

$tlsOtherUsername : 

Type

Methods

copyBasicFiles()

copyBasicFiles() 

copyPwdFiles()

copyPwdFiles() 

copyGeantLinkFiles()

copyGeantLinkFiles() 

echo_nsi()

echo_nsi(  in) : 

function to escape double quotes in a special NSI-compatible way

Parameters

in

input string

Returns

sprint_nsi()

sprint_nsi(  input) : 

Parameters

input

input string

Returns

__construct()

__construct() 

device module constructor should be defined by each module.

The one important thing to do is to call setSupportedEapMethods with an array of EAP methods the device supports

writeDeviceInfo()

writeDeviceInfo() : 

prepare usage information for the installer every device module should override this method

Returns

HTML text to be displayed

uuid()

uuid(  prefix,  deterministicSource = NULL) : 

generates a UUID, for the devices which identify file contents by UUID

Parameters

prefix

an extra prefix to set before the UUID

deterministicSource

Returns

UUID (possibly prefixed)

setup()

setup(\core\AbstractProfile  profile,  token = NULL,  importPassword = NULL) 

Set up working environment for a device module

Sets up the device module environment taking into account the actual profile selected by the user in the GUI. The selected profile is passed as the Profile $profile argumant.

This method needs to be called after the device instance has been created (the GUI class does that)

setup performs the following tasks:

  • collect profile attributes and pass them as the attributes property;
  • create the temporary working directory
  • process CA certificates and store them as 'internal:CAs' attribute
  • process and save optional info files and store references to them in 'internal:info_file' attribute

Parameters

\core\AbstractProfile profile

the profile object which will be passed by the caller

token
importPassword

calculatePreferredEapType()

calculatePreferredEapType(mixed|string|int  eapArrayofObjects) 

Selects the preferred eap method based on profile EAP configuration and device EAP capabilities

Parameters

mixed|string|int eapArrayofObjects

an array of eap methods supported by a given device

writeInstaller()

writeInstaller() 

__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

prepareInstallerLang()

prepareInstallerLang() 

combineLogo()

combineLogo( logos = NULL,  fedLogo = NULL) 

Parameters

logos
fedLogo

signInstaller()

signInstaller() 

compileNSIS()

compileNSIS() 

writeNsisDefines()

writeNsisDefines( eap,  attr) 

Parameters

eap
attr

msInfoFile()

msInfoFile( attr) 

Parameters

attr

writeAdditionalDeletes()

writeAdditionalDeletes( profiles) 

Parameters

profiles

writeClientP12File()

writeClientP12File() 

writeTlsUserProfile()

writeTlsUserProfile() 

setSupportedEapMethods()

setSupportedEapMethods(mixed|string|int  eapArray) 

sets the supported EAP methods for a device

Parameters

mixed|string|int eapArray

the list of EAP methods the device supports

copyFile()

copyFile(  source_name,   output_name = NULL) : 

Copy a file from the module location to the temporary directory.

If the second argument is provided then the file will be saved under the name taken form this argument. If only one parameter is given, source and destination filenames are the same Source file can be located either in the Files subdirectory or in the sibdirectory of Files named the same as device_id. The second option takes precedence.

Parameters

source_name

The source file name

output_name

The destination file name

Returns

result of the copy operation

translateFile()

translateFile(  source_name,   output_name = NULL,   encoding) 

Copy a file from the module location to the temporary directory aplying transcoding.

Transcoding is only required for Windows installers, and no Unicode support in NSIS (NSIS version below 3) Trancoding is only applied if the third optional parameter is set and nonzero If CONFIG['NSIS']_VERSION is set to 3 or more, no transcoding will be applied regardless of the third parameter value. If the second argument is provided and is not equal to 0, then the file will be saved under the name taken from this argument. If only one parameter is given or the second is equal to 0, source and destination filenames are the same. The third optional parameter, if nonzero, should be the character set understood by iconv This is required by the Windows installer and is expected to go away in the future. Source file can be located either in the Files subdirectory or in the sibdirectory of Files named the same as device_id. The second option takes precedence.

Parameters

source_name

The source file name

output_name

The destination file name

encoding

Set Windows charset if non-zero

translateString()

translateString(  source_string,   encoding) 

Transcode a string adding double quotes escaping

Transcoding is only required for Windows installers, and no Unicode support in NSIS (NSIS version below 3) Trancoding is only applied if the third optional parameter is set and nonzero If CONFIG['NSIS']_VERSION is set to 3 or more, no transcoding will be applied regardless of the second parameter value. The second optional parameter, if nonzero, should be the character set understood by iconv This is required by the Windows installer and is expected to go away in the future.

Parameters

source_string

The source string

encoding

Set Windows charset if non-zero

saveCertificateFiles()

saveCertificateFiles(  format) : mixed|string|int

Save certificate files in either DER or PEM format

Certificate files will be saved in the module working directory.

Parameters

format

only "der" and "pem" are currently allowed

Returns

mixed|string|int —

an array of arrays or FALSE on error saved certificate file names are avalable under the 'file' index additional array entries are indexed as 'sha1', 'md5', and 'root'. sha1 and md5 are correcponding certificate hashes root is set to 1 for the CA roor certicicate and 0 otherwise

dumpAttibutes()

dumpAttibutes(  file) 

dumps attributes for debugging purposes

dumpAttibutes method is supplied for debuging purposes, it simply dumps the attribute array to a file with name passed in the attribute.

Parameters

file

the output file name

determineOuterIdString()

determineOuterIdString() : 

collates the string to use as EAP outer ID

Returns

scaleLogo()

scaleLogo( imagePath,  maxSize) 

Parameters

imagePath
maxSize

findSourceFile()

findSourceFile(  file) : string|bool

some modules have a complex directory structure. This helper finds resources in that structure. Mostly used in the Windows modules.

Parameters

file

the filename to search for (without path)

Returns

string|bool —

the filename as found, with path, or FALSE if it does not exist

getInstallerBasename()

getInstallerBasename() 

Generate installer filename base.

Device module should use this name adding an extension. Normally the device identifier follows the Consortium name. The sting taken for the device identifier equals (by default) to the index in the listDevices array, but can be overriden with the 'device_id' device option.

getDeviceId()

getDeviceId() : 

returns the device_id of the current device

Returns

getSSIDs()

getSSIDs() : mixed|string|int

returns the list of SSIDs that installers should treat.

Includes both SSIDs to be set up (and whether it's a TKIP-mixed or AES-only SSID) and SSIDs to be deleted

Returns

mixed|string|int —

getConsortia()

getConsortia() : mixed|string|int

returns the list of Hotspot 2.0 / Passpoint roaming consortia to set up

Returns

mixed|string|int —

saveLogoFile()

saveLogoFile(mixed|string|int  logos,   type) : mixed|string|int

saves a number of logos to a cache directory on disk.

Parameters

mixed|string|int logos

list of logos (binary strings each)

type

a qualifier what type of logo this is

Throws

\Exception

Returns

mixed|string|int —

list of filenames and the mime types

saveInfoFile()

saveInfoFile(  blob) : mixed|string|int

saves the Terms of Use file onto disk

Parameters

blob

the Terms of Use

Throws

\Exception

Returns

mixed|string|int —

with one entry, containging the filename and mime type

getProfileAttributes()

getProfileAttributes(\core\AbstractProfile  profile) : mixed|string|int

returns the attributes of the profile for which to generate an installer

In condensed notion, and most specific level only (i.e. ignores overriden attributes from a higher level)

Parameters

\core\AbstractProfile profile

Returns

mixed|string|int —

prepareEapConfig()

prepareEapConfig( attr) 

Parameters

attr

writeWLANprofile()

writeWLANprofile(  wlanProfileName,   ssid,   auth,   encryption, mixed|string|int  eapConfig,   profileNumber) : 

produce PEAP, TLS and TTLS configuration files for Windows 8

Parameters

wlanProfileName
ssid
auth

can be one of "WPA", "WPA2"

encryption

can be one of: "TKIP", "AES"

mixed|string|int eapConfig

XML configuration block with EAP config data

profileNumber

counter, which profile number is this

Returns

writeLANprofile()

writeLANprofile( eapConfig) 

Parameters

eapConfig

writeMainNSH()

writeMainNSH( eap,  attr) 

Parameters

eap
attr

writeProfilesNSH()

writeProfilesNSH( wlanProfiles,  caArray,  wired) 

Parameters

wlanProfiles
caArray
wired

copyStandardNsi()

copyStandardNsi() 

copyFiles()

copyFiles( eap) 

Parameters

eap