| 43 | | If 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. |
| 44 | | |
| 45 | | To sign URLs, compile [KeySetup crypt_prog], BOINC's encryption utility program. 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. |
| | 47 | If hackers break into an account manager server, |
| | 48 | they could potentially cause the account manager to instruct all its clients |
| | 49 | to attach to malicious a BOINC project that runs a malicious application. |
| | 50 | To prevent this type of attack, the URLs distributed by an account manager are digitally signed. |
| | 51 | Each AM has its own signing key pair. |
| | 52 | The public key is distributed with the AM's configuration file and in all RPC replies. |
| | 53 | The private key should be stored only on a physically secure, |
| | 54 | non-connected host that is used to sign URLs. |
| | 55 | |
| | 56 | To sign URLs, compile [KeySetup crypt_prog], BOINC's encryption utility program. |
| | 57 | Generate a key pair and generate signatures for your URLs. |
| | 58 | At some point you'll need to commit to a permanent key pair, |
| | 59 | at which point you should move the private key to the signing machine (disconnected). |
| | 60 | Make a copy or two on CD-ROM also, and/or print it out on paper; keep these in a safe place. |
| | 61 | Delete all other copies of the private key. |
| 49 | | The 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. |
| 50 | | |
| 51 | | If 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. |
| 52 | | |
| 53 | | == Core client functionality == |
| 54 | | |
| 55 | | The BOINC core client uses the following files to keep track of account manager information. |
| | 65 | The AM mechanism can also be used to implement systems for configuring and controlling BOINC on large clusters. |
| | 66 | We call such systems 'farm managers'. |
| | 67 | Farm managers may want to provide fine-grained control over clients, e.g. the ability to suspend/resume results. |
| | 68 | This can be done using GUI RPCs (assuming that the farm manager able to |
| | 69 | contact clients via HTTP on the GUI RPC port). |
| | 70 | However, the farm manager must learn the GUI RPC port and password for each client. |
| | 71 | To support this, the AM configuration file (see below) can specify that |
| | 72 | the GUI RPC port and password are to be included in each AM RPC request. |
| | 73 | |
| | 74 | If a farm manager uses GUI RPC to attach/detach projects, it should not use the AM mechanism for this purpose. |
| | 75 | I.e., its AM RPC replies should not list any projects. |
| | 76 | The function of the AM mechanism, in this case, is to allow sysadmins to set up new clients by copying files. |
| | 77 | The AM mechanism takes care of registering new clients centrally. |
| | 78 | |
| | 79 | == Client functionality == |
| | 80 | |
| | 81 | The BOINC client uses the following files to keep track of account manager information. |
| 92 | | If 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. |
| | 121 | If the client finds acct_mgr_url.xml but not acct_mgr_login.xml, |
| | 122 | it prompts for a name and password, stores them in acct_mgr_login.xml, and makes an account manager RPC. |
| | 123 | The client offers menu items for making an account manager RPC, and for changing the name/password. |
| 199 | | password_hash:: |
| 200 | | the account password, hashed as MD5(password_lowercase(name)). |
| 201 | | host_cpid:: |
| 202 | | Identifies the host. |
| 203 | | previous_host_cpid:: |
| 204 | | The host identifier passed in the previous RPC. Host identifiers can change occasionally. This lets the account manager maintain host identity. |
| 205 | | domain_name:: |
| | 237 | * '''password_hash''': the account password, hashed as MD5(password_lowercase(name)). |
| | 238 | * '''host_cpid''': Identifies the host. |
| | 239 | * '''previous_host_cpid''': |
| | 240 | The host identifier passed in the previous RPC. |
| | 241 | Host identifiers can change occasionally. |
| | 242 | This lets the account manager maintain host identity. |
| | 243 | * '''domain_name''': |
| 252 | | 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. |
| 253 | | |
| 254 | | NOTE: 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. |
| | 297 | Specifies a resource share for this project. |
| | 298 | If present, this overrides the resource share reported by the project. |
| | 299 | Thus, account managers can provide per-host control of resource share. |
| | 300 | |
| | 301 | NOTE: the XML must be as above, with the <url> and <authenticator> elements on a single line, |
| | 302 | and the <account> and </account> tags on separate lines. |
| 260 | | * 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. |
| 261 | | * 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. |
| | 308 | * Cross-project ID (CPID). |
| | 309 | This is used in the statistics data exported by projects. |
| | 310 | The 'authoritative' CPID is stored on the host itself. |
| | 311 | A host's CPID changes whenever it attaches to a new project. |
| | 312 | CPID is propagated to projects in scheduler RPCs. |
| | 313 | If a host is attached to several projects, its CPID (as reported by those projects) |
| | 314 | may be inconsistent for several days. |
| | 315 | Because of these properties, CPID is not useful as a primary host identifier. |
| | 316 | * Project database ID (DBID). |
| | 317 | This is a project-specific integer identifier. |
| | 318 | On a given host, it changes only in the rare case |
| | 319 | where a user copies state files from one computer to another; |
| | 320 | in that case, one of the two computers is assigned a new ID after its next scheduler RPC. |
| 272 | | * 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. |
| 273 | | * 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. |
| | 331 | * On each account manager RPC, for each reported project, |
| | 332 | look up (user ID, project ID, DBID) in the host table (where 'DBID' is the one passed in the RPC request). |
| | 333 | If no record is found, create one. In any case, update the record with the CPID from the RPC request. |
| | 334 | * To show the user a list of their hosts, with current per-project credit: |
| | 335 | do a show_user.php RPC to each project to get a list of hosts. |
| | 336 | Update the corresponding records in the host table, based on the DBIDs returned by show_user.php. |
| | 337 | Delete any host table entries for this user/project that don't appear in the RPC reply. |
| | 338 | Ignore the CPIDs returned by the show_user RPC (they may not be consistent). |
| | 339 | Then do a query on the host table, grouping by CPID. |
| | 340 | |
