T(Incomplete)?

GUI RPC protocol

BOINC uses the GUI RPC protocol to make the BOINC Manager communicate with the core client.

Note that the RPC server is the core client, and the RPC client is a GUI or add-on communicating with it (such as BOINC Manager). This may seem confusing. This terminology will be used on the rest of the page.

Basic structure

The protocol is based on XML, and it's strictly request-reply. The client sends requests to the server, and waits for a reply; a reply is never sent back by the server without getting a request first. Both requests and replies are terminated with the control character 0x03. Requests are inside <boinc_gui_rpc_request> elements, and replies from the client are inside <boinc_gui_rpc_reply> elements (in both cases there is a %x03 byte after the closing tag).

Note that the core client (RPC server) doesn't support pipelining of requests (pipelining means sending a batch of multiple requests without waiting for a reply, then getting all the replies together; this improves latency). For compatibility, pipelining must not be used.

If a command requires authentication but the client hasn't authenticated yet, the RPC server will reply

<boinc_gui_rpc_reply>
    <unauthorized/>
</boinc_gui_rpc_reply>

The client should be prepared to receive this in reply to any command.

Successful commands usually get the reply:

<boinc_gui_rpc_reply>
    <success/>
</boinc_gui_rpc_reply>

although individual commands may specify a different reply. For example, any command where the client is requesting information from the server would get that extra information in the command reply, instead of <success/>.

If a command isn't successful, the reply is:

<boinc_gui_rpc_reply>
    <error>human-readable error message</error>
</boinc_gui_rpc_reply>

A notable error message is "unrecognized op", which is returned if the server doesn't recognize a command.

Authentication

The RPC protocol allows the RPC client to authenticate itself using a password. Most RPC operations can only be done by an authenticated client. Some can be done without authentication, but only by a client running on the same machine.

Authentication on the RPC protocol is password-based, and negotiated with a challenge-response system. To initiate the authentication process, send an <auth1/> command:

<boinc_gui_rpc_request>
    <auth1/>
</boinc_gui_rpc_request>

The response will be the authentication challenge:

<boinc_gui_rpc_reply>
    <nonce>1198959933.057125</nonce>
</boinc_gui_rpc_reply>

The value of nonce is to be used as a salt with the password. It is randomly generated for each request. To calculate the response, concatenate the nonce and the password (nonce first), then calculate the MD5 hash of the result, i.e: md5(nonce+password). Finally, send an <auth2> request with the calculated hash, in hexadecimal format.

<boinc_gui_rpc_request>
    <auth2>
        <nonce_hash>d41d8cd98f00b204e9800998ecf8427e</nonce_hash>
    </auth2>
</boinc_gui_rpc_request>

The reply will be either <authorized/> or <unauthorized/>.

If the client hasn't authenticated yet, and it is connecting remotely (ie. not via localhost), <auth1/> is the only command that can be sent (all the rest return <unauthorized/>).