Development:MNet Protocol: Difference between revisions

Revision as of 20:16, 18 February 2010

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

user clicks on link on IdP
user is taken to /auth/mnet/jump.php with hostid parameter set to SP's ID, and (optionally) wantsurl set
IdP generates token and creates MNet session (see below)
IdP redirects user to SP's "land" url (as defined in mnet_application table) with token, idp, and wantsurl parameters set
user visits SP's land url
SP calls "auth/mnet/auth.php/user_authorise" on IdP via XML-RPC with token and user's useragent string as parameters
IdP verifies MNet session and returns user data
SP may fetch additional data from IdP, add user to its own DB, update enrolments on IdP, etc.
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 Development: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
see also Mnet keys

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

if signature does not match

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

Documentation