Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
mnet

Classes

class  mnet_peer
 
class  mnet_xmlrpc_client
 Class representing an XMLRPC request against a remote machine. More...
 

Functions

 __construct ()
 Constructor creates and initialises parser resource and calls initialise.
 
 discard_data ($parser, $data)
 Discard the next chunk of character data.
 
 encrypted_to ($keyresource)
 
 end_element ($parser, $name)
 Switch the character-data handler to ignore the next chunk of data.
 
 free_resource ()
 Destroy the parser and free up any related resource.
 
 initialise ()
 Set default element handlers and initialise properties to empty.
 
 mnet_debug ($debugdata, $debuglevel=1)
 Output debug information about mnet.
 
 mnet_encrypt_message ($message, $remote_certificate)
 Encrypt a message and return it in an XML-Encrypted document.
 
 mnet_encxml_parser ()
 Old syntax of class constructor.
 
 mnet_fields_to_import (mnet_peer $peer)
 return an array of the profile fields to import from the given host, when creating/updating user accounts
 
 mnet_fields_to_send (mnet_peer $peer)
 return an array of the profile fields to send with user information to the given mnet host.
 
 mnet_generate_keypair ($dn=null, $days=28)
 Generate public/private keys and store in the config table.
 
 mnet_get_app_jumppath ($applicationid)
 
 mnet_get_hostname_from_uri ($uri=null)
 Strip extraneous detail from a URL or URI and return the hostname.
 
 mnet_get_hosts ($withdeleted=false)
 Returns information about MNet peers.
 
 mnet_get_keypair ()
 Get your SSL keys from the database, or create them (if they don't exist yet)
 
 mnet_get_peer_host ($mnethostid)
 
 mnet_get_public_key ($uri, $application=null)
 Get the remote machine's SSL Cert.
 
 mnet_get_service_info (mnet_peer $mnet_peer, $fulldata=true)
 return an array information about services enabled for the given peer.
 
 mnet_profile_field_options ()
 Return an array of information about all moodle's profile fields which ones are optional, which ones are forced.
 
 mnet_set_public_key ($uri, $key=null)
 Store a URI's public key in a static variable, or retrieve the key for a URI.
 
 mnet_sign_message ($message, $privatekey=null)
 Sign a message and return it in an XML-Signature document.
 
 mnet_sso_apply_indirection ($jumpurl, $url)
 Inline function to modify a url string so that mnet users are requested to log in at their mnet identity provider (if they are not already logged in) before ultimately being directed to the original url.
 
 mnet_strip_user ($user, $fields)
 given a user object (or array) and a list of allowed fields, strip out all the fields that should not be included.
 
 mnet_update_sso_access_control ($username, $mnet_host_id, $accessctrl)
 
 object_to_call ($object)
 
 parse ($data)
 Parse a block of XML text.
 
 parse_cipher ($parser, $data)
 Add the next chunk of character data to the cipher string for that tag.
 
 parse_digest ($parser, $data)
 Add the next chunk of character data to the digest string.
 
 parse_fault ($parser, $data)
 
 parse_object ($parser, $data)
 Add the next chunk of character data to the data_object string.
 
 parse_signature ($parser, $data)
 Add the next chunk of character data to the signature string.
 
 parse_timestamp ($parser, $data)
 Add the next chunk of character data to the remote_timestamp string.
 
 parse_wwwroot ($parser, $data)
 Add the next chunk of character data to the remote_wwwroot string.
 
 plaintext_is_ok ()
 
 refresh_key ()
 
 set_pushkey ()
 
 signature_verified ()
 
 start_element ($parser, $name, $attrs)
 Set the character-data handler to the right function for each element.
 
 static_location ($location)
 
 was_encrypted ()
 
 was_signed ()
 

Variables

array $cipher = []
 the chiper string.
 
string $data_object
 data_object string.
 
array $error = []
 error information with code and string keys.
 
bool $payload_encrypted
 true if $chiper has a value, otherwise false.
 
 $pushkey = false
 
string $remote_timestamp
 remote_timestamp string.
 
string $remote_wwwroot
 remote_wwwroot string.
 
string $remoteerror
 The remote error string, specified in the discard_data().
 
 $request_was_encrypted = false
 
 $request_was_signed = false
 
string $signature
 signature string.
 
 $signatureok = false
 
 $static_location = false
 
 $useprivatekey = ''
 
*author Donal McMullan donal catalyst net nz *version *license http
 
*author Donal McMullan donal catalyst net nz *version *license http
 
*author Donal McMullan donal catalyst net nz *version *license http
 
*author Donal McMullan donal catalyst net nz *version *license http
 
*author Donal McMullan donal catalyst net nz *version *license http
 
const RPC_FORBIDDENFUNCTION 4
 
const RPC_FORBIDDENMETHOD 6
 
const RPC_NOSUCHCLASS 2
 
const RPC_NOSUCHFILE 1
 
const RPC_NOSUCHFUNCTION 3
 
const RPC_NOSUCHMETHOD 5
 
const RPC_OK 0
 CONSTANTS ///////////////////////////////////////////////////////////.
 

Detailed Description

Function Documentation

◆ __construct()

__construct ( )

Constructor creates and initialises parser resource and calls initialise.

Return values
boolTrue

◆ discard_data()

discard_data ( $parser,
$data )

Discard the next chunk of character data.

This is used for tags that we're not interested in.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ end_element()

end_element ( $parser,
$name )

Switch the character-data handler to ignore the next chunk of data.

Parameters
mixed$parserThe XML parser
string$nameThe name of the tag, e.g. method_call
Return values
boolTrue

◆ initialise()

initialise ( )

Set default element handlers and initialise properties to empty.

Return values
boolTrue

◆ mnet_debug()

mnet_debug ( $debugdata,
$debuglevel = 1 )

Output debug information about mnet.

this will go to the error_log.

Parameters
mixed$debugdatathis can be a string, or array or object.
int$debugleveloptional , defaults to 1. bump up for very noisy debug info

◆ mnet_encrypt_message()

mnet_encrypt_message ( $message,
$remote_certificate )

Encrypt a message and return it in an XML-Encrypted document.

This function can encrypt any content, but it was written to provide a system of encrypting XML-RPC request and response messages. The message will be base64 encoded, so it does not need to be text - binary data should work.

We compute the SHA1 digest of the message. We compute a signature on that digest with our private key. We link to the public key that can be used to verify our signature. We base64 the message data. We identify our wwwroot - this must match our certificate's CN

The XML-RPC document will be parceled inside an XML-SIG document, which holds the base64_encoded XML as an object, the SHA1 digest of that document, and a signature of that document using the local private key. This signature will uniquely identify the RPC document as having come from this server.

See the {@Link http://www.w3.org/TR/xmlenc-core/ XML-ENC spec} at the W3c site

Parameters
string$messageThe data you want to sign
string$remote_certificatePeer's certificate in PEM format
Return values
stringAn XML-ENC document

◆ mnet_encxml_parser()

mnet_encxml_parser ( )

Old syntax of class constructor.

Deprecated in PHP7.

Deprecated
since Moodle 3.1

◆ mnet_fields_to_import()

mnet_fields_to_import ( mnet_peer $peer)

return an array of the profile fields to import from the given host, when creating/updating user accounts

Parameters
mnet_peer$peerthe peer we're getting the information from
Return values
array(like 'username', 'firstname', etc)

◆ mnet_fields_to_send()

mnet_fields_to_send ( mnet_peer $peer)

return an array of the profile fields to send with user information to the given mnet host.

Parameters
mnet_peer$peerthe peer to send the information to
Return values
array(like 'username', 'firstname', etc)

◆ mnet_generate_keypair()

mnet_generate_keypair ( $dn = null,
$days = 28 )

Generate public/private keys and store in the config table.

Use the distinguished name provided to create a CSR, and then sign that CSR with the same credentials. Store the keypair you create in the config table. If a distinguished name is not provided, create one using the fullname of 'the course with ID 1' as your organization name, and your hostname (as detailed in $CFG->wwwroot).

Parameters
array$dnThe distinguished name of the server
Return values
stringThe signature over that text

◆ mnet_get_hostname_from_uri()

mnet_get_hostname_from_uri ( $uri = null)

Strip extraneous detail from a URL or URI and return the hostname.

Parameters
string$uriThe URI of a file on the remote computer, optionally including its http:// prefix like http://www.example.com/index.html
Return values
stringJust the hostname

◆ mnet_get_hosts()

mnet_get_hosts ( $withdeleted = false)

Returns information about MNet peers.

Parameters
bool$withdeletedshould the deleted peers be returned too
Return values
array

◆ mnet_get_keypair()

mnet_get_keypair ( )

Get your SSL keys from the database, or create them (if they don't exist yet)

Get your SSL keys from the database, or (if they don't exist yet) call mnet_generate_keypair to create them

Parameters
string$stringThe text you want to sign
Return values
stringThe signature over that text

◆ mnet_get_public_key()

mnet_get_public_key ( $uri,
$application = null )

Get the remote machine's SSL Cert.

Parameters
string$uriThe URI of a file on the remote computer, including its http:// or https:// prefix
Return values
stringA PEM formatted SSL Certificate.

◆ mnet_get_service_info()

mnet_get_service_info ( mnet_peer $mnet_peer,
$fulldata = true )

return an array information about services enabled for the given peer.

in two modes, fulldata or very basic data.

Parameters
mnet_peer$mnet_peerthe peer to get information abut
boolean$fulldatawhether to just return which services are published/subscribed, or more information (defaults to full)
Return values
arrayIf $fulldata is false, an array is returned like: publish => array( serviceid => boolean, serviceid => boolean, ), subscribe => array( serviceid => boolean, serviceid => boolean, ) If $fulldata is true, an array is returned like: servicename => array( apiversion => array( name => string offer => boolean apiversion => int plugintype => string pluginname => string hostsubscribes => boolean hostpublishes => boolean ), )

◆ mnet_profile_field_options()

mnet_profile_field_options ( )

Return an array of information about all moodle's profile fields which ones are optional, which ones are forced.

This is used as the basis of providing lists of profile fields to the administrator to pick which fields to import/export over MNET

Return values
array(forced=> array, optional => array)

◆ mnet_set_public_key()

mnet_set_public_key ( $uri,
$key = null )

Store a URI's public key in a static variable, or retrieve the key for a URI.

Parameters
string$uriThe URI of a file on the remote computer, including its https:// prefix
mixed$keyA public key to store in the array OR null. If the key is null, the function will return the previously stored key for the supplied URI, should it exist.
Return values
mixedA public key OR true/false.

◆ mnet_sign_message()

mnet_sign_message ( $message,
$privatekey = null )

Sign a message and return it in an XML-Signature document.

This function can sign any content, but it was written to provide a system of signing XML-RPC request and response messages. The message will be base64 encoded, so it does not need to be text.

We compute the SHA1 digest of the message. We compute a signature on that digest with our private key. We link to the public key that can be used to verify our signature. We base64 the message data. We identify our wwwroot - this must match our certificate's CN

The XML-RPC document will be parceled inside an XML-SIG document, which holds the base64_encoded XML as an object, the SHA1 digest of that document, and a signature of that document using the local private key. This signature will uniquely identify the RPC document as having come from this server.

See the {@Link http://www.w3.org/TR/xmldsig-core/ XML-DSig spec} at the W3c site

Parameters
string$messageThe data you want to sign
resource$privatekeyThe private key to sign the response with
Return values
stringAn XML-DSig document

◆ mnet_sso_apply_indirection()

mnet_sso_apply_indirection ( $jumpurl,
$url )

Inline function to modify a url string so that mnet users are requested to log in at their mnet identity provider (if they are not already logged in) before ultimately being directed to the original url.

Parameters
string$jumpurlthe url which user should initially be directed to. This is a URL associated with a moodle networking peer when it is fulfiling a role as an identity provider (IDP). Different urls for different peers, the jumpurl is formed partly from the IDP's webroot, and partly from a predefined local path within that webwroot. The result of the user hitting this jump url is that they will be asked to login (at their identity provider (if they aren't already)), mnet will prepare the necessary authentication information, then redirect them back to somewhere at the content provider(CP) moodle (this moodle)
array$urlarray with 2 elements 0 - context the url was taken from, possibly just the url, possibly href="url" 1 - the destination url
Return values
stringthe url the remote user should be supplied with.

◆ mnet_strip_user()

mnet_strip_user ( $user,
$fields )

given a user object (or array) and a list of allowed fields, strip out all the fields that should not be included.

This can be used both for outgoing data and incoming data.

Parameters
mixed$userarray or object representing a database record
array$fieldsan array of allowed fields (usually from mnet_fields_to_{send,import}
Return values
mixedarray or object, depending what type of $user object was passed (datatype is respected)

◆ parse()

parse ( $data)

Parse a block of XML text.

The XML Text will be an XML-RPC request which is wrapped in an XML doc with a signature from the sender. This envelope may be encrypted and delivered within another XML envelope with a symmetric key. The parser should first decrypt this XML, and then place the XML-RPC request into the data_object property, and the signature into the signature property.

See the W3C's XML Encryption Syntax and Processing and XML-Signature Syntax and Processing guidelines for more detail on the XML.

--—XML-Envelope------------------------------— | | | Symmetric-key-----------------------— | | |_____________________________________| | | | | Encrypted data----------------------— | | | | | | | -XML-Envelope---------------— | | | | | | | | | | | –Signature----------— | | | | | | |______________________| | | | | | | | | | | | | –Signed-Payload-----— | | | | | | | | | | | | | | | XML-RPC Request | | | | | | | |______________________| | | | | | | | | | | | |_____________________________| | | | |_____________________________________| | | | |________________________________________________|

Parameters
string$dataThe XML that you want to parse
Return values
boolTrue on success - false on failure

◆ parse_cipher()

parse_cipher ( $parser,
$data )

Add the next chunk of character data to the cipher string for that tag.

The XML parser calls the character-data handler with 1024-character chunks of data. This means that the handler may be called several times for a single tag, so we use the concatenate operator (.) to build the tag content into a string. We should not encounter more than one of each tag type, except for the cipher tag. We will often see two of those. We prevent the content of these two tags being concatenated together by counting each tag, and using its 'number' as the key to an array of ciphers.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ parse_digest()

parse_digest ( $parser,
$data )

Add the next chunk of character data to the digest string.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ parse_object()

parse_object ( $parser,
$data )

Add the next chunk of character data to the data_object string.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ parse_signature()

parse_signature ( $parser,
$data )

Add the next chunk of character data to the signature string.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ parse_timestamp()

parse_timestamp ( $parser,
$data )

Add the next chunk of character data to the remote_timestamp string.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ parse_wwwroot()

parse_wwwroot ( $parser,
$data )

Add the next chunk of character data to the remote_wwwroot string.

Parameters
mixed$parserThe XML parser
string$dataThe content of the current tag (1024 byte chunk)
Return values
boolTrue

◆ start_element()

start_element ( $parser,
$name,
$attrs )

Set the character-data handler to the right function for each element.

For each tag (element) name, this function switches the character-data handler to the function that handles that element. Note that character data is referred to the handler in blocks of 1024 bytes.

Parameters
mixed$parserThe XML parser
string$nameThe name of the tag, e.g. method_call
array$attrsThe tag's attributes (if any exist).
Return values
boolTrue