BOINC Client Communication Infrastructure, Part II

For all intents and purposes the BOINC Manager and BOINC Screensaver are the same type of application as far as the BOINC Daemon is concerned. They both use the BOINC GUI RPC protocol to direct the BOINC Daemon to perform certain tasks. For the purposes of this article I’m going to assume a valid TCP connection is established between the managing application and the BOINC Daemon.

While the protocol is based on XML, there are a few additional rules:

  • No line shall exceed 256 characters in length.
  • Line feeds shall separate all containers and tags.
  • Unicode is not supported. Everything should be MBCS.
  • Parsing of the XML is assumed to be line-by-line. XPath and XQuery queries are not very useful.

While this is valid XML, the BOINC XML parser will choke on it:


<Value1><Subvalue1>1</Subvalue1><Subvalue2>2</Subvalue2></Value1>

This is what it would have to look like for the BOINC XML parser to parse it correctly:


<Value1>
<Subvalue1>1</Subvalue1>
<Subvalue2>2</Subvalue2>
</Value1>

Another important piece of information about the protocol is that both requests and responses are terminated with a control character:


“03”

When sent via the managing application to the BOINC daemon it signifies that the request is complete and the daemon can process the request now. Likewise the managing application should wait for that control character before processing the response. For the remainder of this series of articles assume that all requests and responses to the requests are terminated with the control character.

Authentication

Authentication within BOINC is pretty basic. Like most other authentication systems it consists of a challenge and a response.

To initiate the authentication process send the following request:


<boinc_gui_rpc_request>
<major_version>5</major_version>
<minor_version>5</minor_version>
<release>15</release>
<auth1/>
</boinc_gui_rpc_request>

The response will be the challenge to the request to authenticate:


<boinc_gui_rpc_reply>
<major_version>5</major_version>
<minor_version>5</minor_version>
<release>13</release>
<nonce>1155697308.532692</nonce>
</boinc_gui_rpc_reply>

The value of nonce is to be used as a value to salt the password hash with. It is randomly generated for each request. MD5 is our primary hashing algorithm. If you had the following password:


password

The resulting string to be hashed would look like this:


1155697308.532692password

After MD5 gets done with hashing the challenge and password the result looks like this:


679f1ff0d1c7ed56321c6bc857cdcb43

So now the last part of the authentication process is to tell the BOINC Daemon what the answer to its challenge is. We do this by sending the following request:


<boinc_gui_rpc_request>
<major_version>5</major_version>
<minor_version>5</minor_version>
<release>15</release>
<auth2>
<nonce_hash>679f1ff0d1c7ed56321c6bc857cdcb43</nonce_hash>
</auth2>
</boinc_gui_rpc_request>

If successful you’ll see a response like this:


<boinc_gui_rpc_reply>
<major_version>5</major_version>
<minor_version>5</minor_version>
<release>13</release>
<authorized/>
</boinc_gui_rpc_reply>

A failure will look like this:


<boinc_gui_rpc_reply>
<major_version>5</major_version>
<minor_version>5</minor_version>
<release>13</release>
<unauthorized/>
</boinc_gui_rpc_reply>

Some interesting notes on authentication:

  • All RPCs are protected if the request is coming from a managing application on a remote computer.
  • All RPCs that can change the behavior of the BOINC Daemon are protected even if running on the same machine.
  • RPCs that just query the state of the client are not protected when the managing application is running on the same machine.
  • Currently <set_screensaver_mode> is the only exception to the above rules.

More interesting tidbits will follow in future articles…

—– Rom