Development:MNet Protocol

Overview

Moodle Networks allows other sites to perform RPC calls on a Moodle instance in a secure fashion. (Most) requests are signed and encrypted for security. Sites are identified by their web root ($CFG->wwwroot in Moodle), and publish a public key (RSA). Requests and responses are encoded using XML-RPC, and signing and encryption are performed using XML-SIG and XML-ENC.

Application types

• MNet supports different types of applications, with different access URLs
• defined in mnet_application table
• lists names and URLs for RPC

Log in flow

• dramatis personae
  • user
  • IdP (identity provider) = site the user is logging in from
  • SP (service provider) = site the user is logging in to

Basic successful log in

1. user clicks on link on IdP
2. user is taken to /auth/mnet/jump.php with hostid parameter set to SP's ID, and (optionally) wantsurl set
3. IdP generates token and creates MNet session (see below)
4. IdP redirects user to SP's "land" url (as defined in mnet_application table) with token, idp, and wantsurl parameters set
5. user visits SP's land url
6. SP calls "auth/mnet/auth.php/user_authorise" on IdP via XML-RPC with token and user's useragent string as parameters
7. IdP verifies MNet session and returns user data
8. SP may fetch additional data from IdP, add user to its own DB, update enrolments on IdP, etc.
9. SP redirects user to wantsurl

MNet session

ID provider stores:

• host
• userid
• username
• sha1(useragent)
• token
• confirm timeout
• expires
• session id

Allowed RPC calls

• permissions stored in mnet_host2service x mnet_service2rpc x mnet_rpc (except for "dangerous" calls)
• modules/plugins must have ($module_)mnet_publishes function
• system
  • system/listMethods
  • system/methodSignature
  • system/methodHelp
  • system/listServices
  • system/keyswap
• auth
  • auth/$plugin/auth.php/$method -> file:/auth/$plugin/auth.php class:auth_plugin_$plugin method:$method
• enrol
  • auth/$plugin/enrol.php/$method -> file:/enrol/$plugin/enrol.php class:enrolment_plugin_$plugin method:$method
• portfolio (Moodle 2.0)
  • portfolio/$plugin/lib.php/$method -> file:/portfolio/type/$plugin/lib.php class:portfolio_plugin_$plugin method:$method
• repository (Moodle 2.0)
  • repository/$plugin/repository.class.php/$method -> file:repository/$plugin/repository.class.php class:repository_$plugin method:$method
• mod
  • mod/$module/rpclib.php/$function -> file:/mod/$module/rpclib.php function:$function
• dangerous (only if sender has plaintext_is_ok set)
  • dangerous/$path/$function -> file:/$path function:$function (response is not encrypted/signed)

see MNet services for more information on the default available methods

Security

• XML-RPC messages are encrypted/signed using public key cryptography
• use wrappers based on XML-SEC
• wrappers have "wwwroot" element to identify the sender
• Note: security may be compromised by a man-in-the-middle and/or DNS attack

encryption

• uses openssl's seal routine
• RC4-encrypted (128-bit key)
• RC4 key encrypted (RSA) with public key

signature

• digest: SHA-1
• signature: RSA (despite the XML-SIG wrapper claiming to be DSA)

key generation

• 1024 bit RSA
• self-signed
• send certificate as PEM-encoded
• X.509 certificate fields (only CN is actually checked)
• C (country name)
• ST (state or province name)
• L (locality name)
• O (organization name)
• OU (organizational unit name) = Moodle (or whatever software you are running)
• CN (common name) = $wwwroot (no trailing slashes)
• EMAILADDRESS (email address)

Error handling

see also MNet faults

if signature does not match

(see also http://moodle.org/mod/forum/discuss.php?d=102113)

• server sends "system/listServices" to client
• system/listServices is used so that the server will return a (signed) 7025 fault
• server retrieves key from response

if decryption fails

• try decrypting against old keys
• if able to decrypt, send fault #7025, signed with old private key, with certificate as content. This reduces an attacker's ability to perform a man-in-the-middle attack.
• otherwise, send fault #7023