Changes between Initial Version and Version 1 of AccountManagement


Ignore:
Timestamp:
Jul 15, 2007, 8:29:53 PM (17 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AccountManagement

    v1 v1  
     1= Account management systems =
     2
     3To create an account with BOINC projects, a participant must:
     4
     5    * Locate BOINC project web sites, e.g. using Google.
     6    * Read the web sites, and decide which to join;
     7    * Download and install the BOINC client software.
     8
     9and then for each selected project:
     10
     11    * Go through the Attach to Project wizard.
     12
     13If the participant chooses N projects, there are N web sites to visit and N Wizards to complete. This is tedious if there are lots of projects.
     14
     15This document describes BOINC's support for 'account management systems', which streamline the process of finding and joining BOINC projects. A typical account management system is implemented as a web site. The participant experience is:
     16
     17    * Visit the account manager site, set up a 'meta-account' (name, email, password), browse a list of projects, and click checkboxes to select projects.
     18    * Download and install the BOINC client software from the account manager.
     19    * Enter the meta-account name and password in a BOINC client dialog.
     20
     21This requires many fewer interactions than the manual approach.
     22
     23== Implementation ==
     24
     25An account management system works as follows:
     26
     27[[image http://boinc.berkeley.edu/acct_mgt2.png]]
     28
     29   1. The participant sets up his meta-account and selects projects.
     30   2. The account manager issues a create account RPC to each selected project.
     31   3. the participant downloads and installs the BOINC client software from the account manager. The install package includes a file (specific to the account manager) containing the URL of the account manager.
     32   4. The BOINC client runs, and asks the participant to enter the name and password of his meta-account.
     33   5. The BOINC client does an RPC to the account manager, obtaining a list of accounts. It then attaches to these accounts and proceeds.
     34
     35RPCs to create, look up, and modify accounts are described [WebRpc here].
     36
     37== Security ==
     38
     39If hackers break into an account manager server, they could potentially cause the account manager to instruct all its clients to attach to malicious a BOINC project that runs a malicious application. To prevent this type of attack, the URLs distributed by an account manager are digitally signed. Each AM has its own signing key pair. The public key is distributed with the AM's configuration file and in all RPC replies. The private key should be stored only on a physically secure, non-connected host that is used to sign URLs.
     40
     41To sign URLs, compile [KeySetup crypt_prog], BOINC's encryption utility program. (Instructions for downloading and compiling code are [ServerIntro here].) Generate a key pair and generate signatures for your URLs. At some point you'll need to commit to a permanent key pair, at which point you should move the private key to the signing machine (disconnected). Make a copy or two on CD-ROM also, and/or print it out on paper; keep these in a safe place. Delete all other copies of the private key.
     42
     43== Farm managers ==
     44
     45The AM mechanism can also be used to implement systems for configuring and controlling BOINC on large clusters. We call such systems 'farm managers'. Farm managers may want to provide fine-grained control over clients, e.g. the ability to suspend/resume results. This can be done using GUI RPCs (assuming that the farm manager able to contact clients via HTTP on the GUI RPC port). However, the farm manager must learn the GUI RPC port and password for each client. To support this, the AM configuration file (see below) can specify that the GUI RPC port and password are to be included in each AM RPC request.
     46
     47If a farm manager uses GUI RPC to attach/detach projects, it should not use the AM mechanism for this purpose. I.e., its AM RPC replies should not list any projects. The function of the AM mechanism, in this case, is to allow sysadmins to set up new clients by copying files. The AM mechanism takes care of registering new clients centrally.
     48
     49== Core client functionality ==
     50
     51The BOINC core client uses the following files to keep track of account manager information.
     52
     53acct_mgr_url.xml
     54    This file identifies the account manager. It is typically bundled with the BOINC client in an installer package. Its format is:
     55{{{
     56<acct_mgr>
     57    <name>Name of BOINC account management system</name>
     58    <url>http://acctmgr.com/</url>
     59    [ <send_gui_rpc_info/> ]
     60    <signing_key>
     611024
     62ae843acebd4c7250b0fa575d14971b17a56a386a6bb1733d98f4b00460c26159
     63c8b3217e6cdff938ec0454330c70553fbe3d1f0d0184d8c628db2e093121ee98
     648ddbda6e8991879317afccab41f84e9de4903a656f4d3f3e4e7dbc0af9362a05
     656ece5ff401a380f3a1d1254d477f7bc84fdcebcca6cb035e776452d3d6d21471
     660000000000000000000000000000000000000000000000000000000000000000
     670000000000000000000000000000000000000000000000000000000000000000
     680000000000000000000000000000000000000000000000000000000000000000
     690000000000000000000000000000000000000000000000000000000000010001
     70.
     71    </signing_key>
     72</acct_mgr>
     73}}}
     74    The URL is that of the account manager's web site.
     75
     76    If the <send_gui_rpc_info/> tag is present, account manager RPCs will include the client's GUI RPC port and password hash (see below).
     77acct_mgr_login.xml
     78    This file contains meta-account information. Its format is:
     79{{{
     80<acct_mgr_login>
     81   <login>name</login>
     82   <password_hash>xxx</password_hash>
     83</acct_mgr_login>
     84}}}
     85The password is stored as MD5(password_lowercase(login)).
     86
     87If the core client finds acct_mgr_url.xml but not acct_mgr_login.xml, it prompts for a name and password, stores them in acct_mgr_login.xml, and makes an account manager RPC. The core client offers menu items for making an account manager RPC, and for changing the name/password.
     88
     89== Account manager RPCs ==
     90
     91An account manager must provide a get_project_config.php file containing its name and minimum password length, and containing a <account_manager/> tag.
     92
     93In addition, an account manager must provide the following RPC, which uses an HTTP POST request.
     94
     95 URL::
     96        BASE_URL/rpc.php, where BASE_URL is the URL of the account manager web site.
     97 input::
     98{{{
     99<acct_mgr_request>
     100    <name>John</name>
     101    <password_hash>xxx</password_hash>
     102    <host_cpid>b11ddc5f36c9a86ff093c96e6930646a</host_cpid>
     103    <previous_host_cpid>b11ddc5f36c9a86ff093c96e6930646a</previous_host_cpid>
     104    <domain_name>host.domain</domain_name>
     105    <client_version>5.3.2</client_version>
     106    <run_mode>auto</run_mode>
     107    <global_preferences>
     108        <source_project>http://a.b.c</source_project>
     109        <source_scheduler>http://a.b.c</source_scheduler>
     110        <mod_time>1144105331</mod_time>
     111        ... [ global preferences ]
     112    </global_preferences>
     113    <project>
     114       <url>http://setiathome.berkeley.edu/</url>
     115       <project_name>SETI@home</project_name>
     116       <suspended_via_gui>0</suspended_via_gui>
     117       <account_key>397d250e02ec02be8141b8d109d5ec73e5</account_key>
     118       <hostid>NNN</hostid>
     119       [ <attached_via_acct_mgr/> ]
     120    </project>
     121    [ ... other projects ]
     122    [ <gui_rpc_port>N</gui_rpc_port> ]
     123    [ <gui_rpc_password>xxxx</gui_rpc_password> ]
     124    ...
     125</acct_mgr_request>
     126}}}
     127 output::
     128{{{
     129<acct_mgr_reply>
     130    <name>Account Manager Name</name>
     131    <signing_key>
     1321024
     133ae843acebd4c7250b0fa575d14971b17a56a386a6bb1733d98f4b00460c26159
     134c8b3217e6cdff938ec0454330c70553fbe3d1f0d0184d8c628db2e093121ee98
     1358ddbda6e8991879317afccab41f84e9de4903a656f4d3f3e4e7dbc0af9362a05
     1366ece5ff401a380f3a1d1254d477f7bc84fdcebcca6cb035e776452d3d6d21471
     1370000000000000000000000000000000000000000000000000000000000000000
     1380000000000000000000000000000000000000000000000000000000000000000
     1390000000000000000000000000000000000000000000000000000000000000000
     1400000000000000000000000000000000000000000000000000000000000010001
     141.
     142    </signing_key>
     143    [ <message>this is a message</message> ]
     144    [ ... ]
     145    [ <error>MSG</error> ]
     146    [ <repeat_sec>xxx</repeat_sec> ]
     147    [
     148    <global_preferences>
     149        [ <source_project>http://a.b.c</source_project> ]
     150        [ <source_scheduler>http://a.b.c</source_scheduler> ]
     151        <mod_time>1144105331</mod_time>
     152        ... [ global preferences ]
     153    </global_preferences>
     154    ]
     155    [ <host_venue>venue</host_venue> ]
     156    [
     157    <account>
     158       <url>URL</url>
     159       <url_signature>
     160397d250e02ec02be8141b8d196a118d909d5ec73e592ed50f9d0ad1ce5bf87de
     161e37f48079db76128b20f913a04e911489330a7cab8c346177f1682d236bc7201
     16242b32665d0d83474bf12aebd97b2bb9a4c4461fa3f0b49bbd40ecfa16715ced7
     163f72103eb0995be77cac54f253c0ba639a814d3293646ae11894e9d1367a98790
     164.
     165       </url_signature>
     166       <authenticator>KEY</authenticator>
     167       [ <update>0|1</update> ]
     168       [ <detach>0|1</detach> ]
     169       [ <dont_request_more_work>0|1</dont_request_more_work> ]
     170       [ <detach_when_done>0|1</detach_when_done> ]
     171       [ <resource_share>X</resource_share> ]
     172    </account>
     173    ...
     174    ]
     175</acct_mgr_reply>
     176}}}
     177 action::
     178        Returns a list of the accounts associated with this meta-account. The arguments are:
     179
     180 password_hash::
     181    the account password, hashed as MD5(password_lowercase(name)).
     182 host_cpid::
     183    Identifies the host.
     184 previous_host_cpid::
     185    The host identifier passed in the previous RPC. Host identifiers can change occasionally. This lets the account manager maintain host identity.
     186 domain_name::
     187    The host's domain name.
     188 run mode::
     189    The current mode (always/auto/never).
     190 gui_rpc_port, gui_rpc_password::
     191    GUI RPC information. Included only if the <send_gui_rpc_info> element is included in the AM URL file (see above).
     192 global_preferences::
     193    The current global preferences.
     194 venue::
     195    The host venue
     196
     197In addition, a list of projects and their suspended flags is included.
     198
     199The return values are:
     200
     201 repeat_sec::
     202    A time interval after which another RPC should be done.
     203 signing_key::
     204    The public key used to sign URLs, in an encoded notation. Use the BOINC crypt_prog program to generate this.
     205 message::
     206    A message to be displayed to the user.
     207 global_preferences::
     208    New global preferences. Included only if these are newer than those in the request message.
     209
     210For each account, the following items are returned:
     211
     212 url::
     213    The project URL
     214 url_signature::
     215    A signature for the URL. Use the BOINC crypt_prog program to generate this.
     216 authenticator::
     217    The account's authenticator.
     218 detach::
     219    If nonzero, the client should detach this project.
     220 update::
     221    If nonzero, the client should contact this project to get new global preferences.
     222 dont_request_more_work::
     223    If nonzero, don't request any more work from this project.
     224 detach_when_done::
     225    If nonzero, detach from this project when all work is completed
     226 resource_share::
     227    Specifies a resource share for this project. If present, this overrides the resource share reported by the project. Thus, account managers can provide per-host control of resource share.
     228
     229NOTE: the XML must be as above, with the <url> and <authenticator> elements on a single line, and the <account> and </account> tags on separate lines.
     230
     231== Host identification ==
     232
     233BOINC uses two ID spaces for hosts:
     234
     235    * Cross-project ID (CPID). This is used in the statistics data exported by projects. The 'authoritative' CPID is stored on the host itself. A host's CPID changes whenever it attaches to a new project. CPID is propagated to projects in scheduler RPCs. If a host is attached to several projects, its CPID (as reported by those projects) may be inconsistent for several days. Because of these properties, CPID is not useful as a primary host identifier.
     236    * Project database ID (DBID). This is a project-specific integer identifier. On a given host, it changes only in the rare case where a user copies state files from one computer to another; in that case, one of the two computers is assigned a new ID after its next scheduler RPC.
     237
     238An account manager RPC request includes the host's CPID, and its DBID on all projects to which it's attached (see above).
     239
     240A suggested method of maintaining a user's hosts is as follows:
     241
     242    * Maintain a host table with columns
     243          * user ID
     244          * project ID
     245          * DBID
     246          * CPID
     247    * On each account manager RPC, for each reported project, look up (user ID, project ID, DBID) in the host table (where 'DBID' is the one passed in the RPC request). If no record is found, create one. In any case, update the record with the CPID from the RPC request.
     248    * To show the user a list of their hosts, with current per-project credit: do a show_user.php RPC to each project to get a list of hosts. Update the corresponding records in the host table, based on the DBIDs returned by show_user.php. Delete any host table entries for this user/project that don't appear in the RPC reply. Ignore the CPIDs returned by the show_user RPC (they may not be consistent). Then do a query on the host table, grouping by CPID.