The fridgeserver protocol is implemented on top of XMLRPC over HTTP.

Methods

The following methods are available on the fridge server.

Authenticated methods

These methods must be authenticated with an HMAC-MD5, using the MD5 of the user’s password as a shared secret.

generate_nonce

Method call

generate_nonce(string cnonce, int timestamp, string username, string request_hmac)

Return value

map(
  'nonce' => string snonce  
  'hmac' => string response_hmac  
)  

To prevent replay attacks a nonce is used with each purchase request. This method asks the server to generate such a nonce and return it. The nonce is an arbitrary random string of printable characters. The server stores the nonce when it is generated and then checks it and deletes it when it is used to prevent reuse of old nonces. Nonces older than a certain age (currently 10 minutes) are also deleted to prevent the database from filling up.
cnonce is a client nonce generated by the client to prevent replays of the generate_nonce request filling up the server’s database.
timestamp is the current time in seconds since the Unix epoch. The server will reject the request if this is too old, to prevent replays.
username is the username of a the user on the server who will be making the request using the nonce.
request_hmac is an HMAC-MD5 to authenticate the user to the server and prevent unrecognised users from filling up the server’s database. It is generated using the user’s fridge password, as hmac_md5(cnonce . “,” . timestamp . “,” . username, md5(password)).

response_hmac is an HMAC-MD5 to verify the response, generated as hmac_md5(snonce . cnonce, md5(password)).

transfer

Method call

transfer(string snonce, string from_user, string to_user, int amount, string request_hmac)

Return value

map(
  'balance' => int new_balance  
  'hmac' => string response_hmac  
)  

The snonce must match a server nonce previously generated and not yet used.
from_user is the username of a (local) user on the server who is initiating the request and from whose account the given amount will be transferred.
to_user is the username of the local or remote user to whose account the given amount will be transferred. Remote users are specified by a string of the form “username@fridge” where fridge is the name of the remote fridge (which must be a special interfridge user on this fridge).
amount is the value of the transaction in cents. This must be positive to make an actual transfer. A purchase request with an amount of 0 is used to authenticate the user without actually making a transaction, for logging in to fridge and obtaining their current balance. A negative value is not allowed.
request_hmac is an HMAC-MD5 signing the request by the from_user. It is generated as hmac_md5(snonce . “,” . from_user . “,” . to_user . “,” . amount, md5(password)), where ‘password’ is the password of from_user. This prevents man-in-the-middle attacks where the message is altered between the client and the server, such as changing the amount. It also authenticates the user who is making the request to the server.
The server returns the new balance for the from_user (after the transfer has been made). It also returns the response_hmac, which is generated as hmac_md5(snonce . “,” . new_balance , md5(password)). This prevents a man-in-the-middle from faking a successful response.

purchase

Method call

purchase(string snonce, string user, array(map('code' => string code, 'quantity' => int quantity)) items, string request_hmac)

Return value

map(
  'balance' => int new_balance  
  'order_total' => int order_total  
  'hmac' => string response_hmac  
)  

The snonce must match a server nonce previously generated and not yet used.
user is the username of a (local) user on the server who is initiating the request and on whose account the purchase is to be made.
items is an array of items in the order. Each element of the array should include both the product code and the number of items of that product which are to be purchased.
request_hmac is an HMAC-MD5 signing the request by the user. It is generated as hmac_md5(snonce . “,” . user . “,” . items_string, md5(password)), where ‘password’ is the password of the user. This prevents man-in-the-middle attacks where the message is altered between the client and the server, such as changing the amount. It also authenticates the user who is making the request to the server. items_string here is a string constructed by concatenating all the items in the order, code and quantity, separated by commas, like “KK,1,LL,3”.
The server returns the new balance for the user (after the purchase has been made), and the total price of the order. It also returns the response_hmac, which is generated as hmac_md5(snonce . “,” . new_balance. “,” order_total, md5(password)). This prevents a man-in-the-middle from faking a successful response.

topup

Method call

topup(string snonce, string user, int amount, string request_hmac)

Return value

map(
  'balance' => int new_balance  
  'hmac' => string response_hmac  
)  

The snonce must match a server nonce previously generated and not yet used.
user is the username of a (local) user on the server who is initiating the request and to whose account the topup is to be credited.
amount is the value of the topup credit in cents. A positive value will increase the user’s balance.
request_hmac is an HMAC-MD5 signing the request by the user. It is generated as hmac_md5(snonce . “,” . user . “,” . amount, md5(password)), where ‘password’ is the password of the user. This prevents man-in-the-middle attacks where the message is altered between the client and the server, such as changing the amount. It also authenticates the user who is making the request to the server.
The server returns the new balance for the user (after the topup has been made). It also returns the response_hmac, which is generated as hmac_md5(snonce . “,” . new_balance , md5(password)). This prevents a man-in-the-middle from faking a successful response.

remote_purchase

Method call

remote_purchase(string snonce, string purchase_fridge, string user, array(map('code' => string code, 'quantity' => int quantity)) items, string request_hmac)

Return value

map(
  'balance' => int new_balance  
  'order_total' => int order_total  
  'hmac' => string response_hmac  
)  

This method is used to request that this fridge make a purchase at a remote fridge on behalf of a a user who has an account at this fridge. This fridge will call purchase on the remote fridge using its own credentials.
The snonce must match a server nonce previously generated and not yet used.
purchase_fridge is the name of the remote fridge at which the purchase is to be made.
user is the username of a (local) user on the server who is initiating the request and from whose account the price of the purchase will be deducted.
items is an array of items in the order. Each element of the array should include both the product code and the number of items of that product which are to be purchased.
request_hmac is an HMAC-MD5 signing the request by the user. It is generated as hmac_md5(snonce . “,” . purchase_fridge . “,” . user . “,” . items_string, md5(password)), where ‘password’ is the password of the user. This prevents man-in-the-middle attacks where the message is altered between the client and the server, such as changing the amount. It also authenticates the user who is making the request to the server. items_string here is a string constructed by concatenating all the items in the order, code and quantity, separated by commas, like “KK,1,LL,3”.
The server returns the new balance for the user (after the purchase has been made), and the total price of the order. It also returns the response_hmac, which is generated as hmac_md5(snonce . “,” . new_balance. “,” order_total, md5(password)). This prevents a man-in-the-middle from faking a successful response.

remote_topup

Method call

remote_topup(string snonce, string topup_fridge, string user, int amount, string request_hmac)

Return value

map(
  'balance' => int new_balance  
  'hmac' => string response_hmac  
)  

This method is used when a user who has an account at this fridge wishes to top it up by depositing money at a different fridge. It requests that the local fridge make a topup at a remote fridge on behalf of a used who has an account at this fridge, crediting the amount to their account at this fridge.
The snonce must match a server nonce previously generated and not yet used.
topup_fridge is the name of the remote fridge at which the topup is to be made. That is to say, the fridge at which the physical cash is deposited.
user is the username of a (local) user on the server who is initiating the request and to whose account the topup will be credited.
amount is the value of the topup credit in cents. A positive value will increase the user’s balance.
request_hmac is an HMAC-MD5 signing the request by the user. It is generated as hmac_md5(snonce . “,” . user . “,” . amount, md5(password)), where ‘password’ is the password of the user. This prevents man-in-the-middle attacks where the message is altered between the client and the server, such as changing the amount. It also authenticates the user who is making the request to the server.
The server returns the new balance for the user (after the topup has been made). It also returns the response_hmac, which is generated as hmac_md5(snonce . “,” . new_balance , md5(password)). This prevents a man-in-the-middle from faking a successful response.

Informational methods

These methods may be called freely.

get_stock

Method call

get_stock(optional string username)

Return value

array(
  map(  
    'product_code' => string product_code  
    'description' => string description  
    'in_stock' => int number_in_stock  
    'price' => int price  
    'category' => string category  
    'category_order' => int category_order  
  )  
)  

This method returns a list of items which are available for purchase on the fridge. If a username is given then the list is customised to that user, typically by adjusting the prices depending on whether or not they are a graduate.

get_fridges

Method call

get_fridges()

Return value

map(
  string fridge_name => string fridge_endpoint  
)  

This method gives a list of all remote fridges with which this fridge is peered, along with their HTTP endpoints for the fridgeserver protocol.

get_fridge_name

Method call

get_fridge_name()

Return value

string local_fridge_name

This method simply return the name of the fridge, as used by remote fridges to refer to it.

get_user_info

Method call

get_user_info(string username)

Return value

map(
  'real_name' => string real_name  
  'isadmin' => boolean isadmin  
)  

This method returns some information about the given local user.