= User Opt-in Consent =

Projects may want to establish general terms of use their users have to explicitly accept during sign-up and potentially also for the continued of an existing accounts. Additionally, the [https://en.wikipedia.org/wiki/General_Data_Protection_Regulation European GDPR law] requires projects to ask their users for consent before they are allowed to process personal information in certain ways, e.g. export user details to external statistic services. BOINC needs to be extended to support both.

== User Experience ==

When using the a BOINC manager to join a project (Add Project), the user is shown a Terms of Use / Project policy text. S/he must accept the terms of use before the account is created. As part of the account creation process, the agreement to the terms of use is recorded in the project's database.

Note: As of 2018-10-26, no BOINC managers use the Web RPCs described here to actually tell the BOINC project to record the consent to the terms of use in the database. Thus, whenever a user logs in for the first time s/he will will be presented with the terms of use Web page, asking them to agree. As more BOINC managers are changed to handle the consent features described here, this will change.

For account managers (AM), AMs can download a site's terms of use from `get_project_config.php`. Then present this text to a user. It will be the responsibility of an AM to present the text along with a checkbox for the user to agree to. (It must not be passive.) The `create_account.php` RPC will be modified slightly for AM to set a consent flag. Additionally, the `am_set_info.php` RPC will be modified to allow AM to update the a user's consent information.

For Web registration, the login page can provide the terms of use text. Users will have to accept the terms of use before creating an account. This agreement will be stored in the project's database.

For existing accounts: A project may decide that existing accounts should also agree to a terms of use. This is a separate feature from the user agreement to a terms of use when registering an account. Existing users will have to agree to a terms of use via a checkbox, and then that agreement is stored in the project's database.

== Existing code ==

As of April 2018, BOINC already contains a [wiki:TermsOfUse 'terms of use' mechanism] for the BOINC client when creating a new account. If the file 'terms_of_use.txt' (filename is hardcod-ed) is in the root of the project directory, the contents of the file will be presented to the user when s/he creates an account. However, there is no persistent 'storing' of the datetime the user consented to the terms of use.

For Web registration, the code does not use the [wiki:TermsOfUse] text. But it can be modified to do so.

Additionally, it is not known whether account managers, such as BAM!, use this terms-of-use mechanism.

`boinccmd` command-line client does not use the [wiki:TermsOfUse] mechanism. Thus when a user creates an account, s/he does not see any terms of use, even if it exists.

Lastly, the terms of use text file must be text. HTML should be supported, although this may be added later.

== Technical Implementation ==

=== Project config ===

A new project option will be included in `config.xml` for projects, `enable_login_mustagree_termsofuse` option. This flag will toggle whether or not the project requires **existing** users to agree to the terms of us of the site. Note, a site may toggle the feature where new accounts are required to agree to a terms of use in the OPS page. This config parameter is independent of the OPS page (see below).

=== Database ===

Two new tables: `consent` and `consent_type`

* `consent`
 * `id` - primary key of table - a unique id for each row. Not used for the consent functionality.
 * `userid` - the user id
 * `consent_type_id` - consent type id, corresponds to the 'id' in the `consent_type` table.
 * `consent_time` - `datetime` type attribute : unixtime of when user `id` gave consent to `consent_id`.
 * `consent_flag` - the boolean which explicitly stats that this user id has given consent to this consent id. If this is 0 (FALSE), the following boolean should be 1 (TRUE).
 * `consent_not_required` - a special boolean that indicates whether or not consent is not required. This feature may be used by certain special situation.
 * `source` - text field containing the technology actor which the user gave consent. See below.

* `consent_type`
  * `id` - consent type id, also the primary key.
  * `shortname` - consent name, these should be short and in ALLCAPS, e.g., ENROLL, STATSEXPORT, etc. There should be no spaces either.
  * `description` - text field describing the consent that user gives (or has given).
  * `enabled` - if true, this consent type is enabled. This is toggled in the OPS page for managing consent types.
  * `project_specific` - if false, this consent type is introduced by BOINC upstream. If true this consent type project-specific, and was added by the project via the ops pages.
  * `privacypref` - if true, (and enabled), this consent type will be shows in the preferences page in the privacy section. This allows projects to add consent types which deal with user privacy; and no additional coding is necessary.

==== Discussion ====

Some discussion on `source` string.

Examples

* If a user gives consent by registering for an account using the BOINC GUI client (BOINC manager), `source` would be set to 'client'. 
* If the account is created on a Web site registration page, `source` would be set to 'web'. 
* Account Managers should put their name in, e.g. `source` = 'BAM!' or `source` = '!GridRepublic'.
* command-line client uses 'boinccmd'.
* In the case where `source` is not specified (but consent is being used) then a default `source` of 'URL' can be used.
  * 'URL' represents the fact that a user can create an account using the RPC by typing the correct parameters into the URL bar of a browser, or using a command line tool such as curl.

Re: `consent_type` table

At first there will be two records in `consent_type`: 1) the main terms-of-use a user consents to when joining the project (ENROLL) and 2) a stats-exports consent type (STATSEXPORT). In effect, these are distributed by BOINC upstream. This allows for flexibility - a project may decide to present a user with multiple items to consent to. Each can be recorded in the `consent` table with a different `consent_type_id`, which corresponds to the row in the `consent_type` table, which contains the name and description. The `project_specific` field indicated a consent type that is introduced by BOINC upstream for all projects (false) or a specific consent for a project (true).

The `enabled` flag is fairly important. By default no consent types are enabled. The project admins may toggle this in the Manage Consent Types OPS page. If the 'ENROLL' type is enabled, users will have to agree to a terms of use when creating an account. (The terms of use file must also exist). Independently, if 'ENROLL' is enabled, and parameter 'enable_login_mustagree_termsofuse' is equal to 1 (TRUE), existing users must agree to the site's terms of use. 

If 'STATSEXPORT' type is enabled, users will see a new privacy preference option about statistics exports. They may give consent to this consent type in the user preference pages.

Re: `consent` table

Entries to this table are to be inserted for a `userid` and `consent_name`. This way a single user may consent to multiple policies. If a user withdraws consent, a new entry should be added. Effectively, no rows should be deleted from this table, only added. There may be a situation where a user has dozens of rows since s/he has given and withdrawn consent multiple times. This acts as a record of the user's consent to policies. The latest row, that is the row with last datetime, represents the current consent status.

The exception is when a user deletes his/her account. Then all `consent` table entries for that user's id are deleted.

=== RPC ===

RPCs that will need to change:
* `create_account.php`
* `am_set_info.php`

The main RPC that needs to be changed is `create_account.php`, which needs to insert a record into the `consent` table when the user creates his/her account- assuming s/he consents to a site's terms of use.

Additional parameters for `create_account.php` RPC are
* `consent_flag` = 0|1 - If true, sets the `consent_flag` to 1. If false the `consent_flag` is set to 0 and `consent_not_required` is set to 1.
* `source` = 'string'
  * example: 'client', see above discussion about `source` for more details.

What are the various outcomes of the create_account RPC, especially dealing with `consent_flag`.

* If consent_flag is not set (NULL), then this is a legacy connection: a old BOINC client or Account Manager. The account is created, but no entry in the `consent` table is made. Terms-of-use acceptance is delayed until a user accesses the Web site.
* `consent_flag`=1, terms-of-use was shown to the user, and accept by a remote source: BOINC client or AM.
* `consent_flag`=0, terms-of-use not shown but an account is being created is anonymous. See discussion of Anonymous Account below.
* N.B. Consent to statistics exports, STATSEXPORT, is not granted via create_account RPC.

`am_set_info.php` needs to be modified in order to contain a consent parameter, which also modifies the `consent` table in the database.

Additional parameters are
* `consent_name` = 'string' - This is the shortname of the consent_type to insert a new entry for.
* `consent_flag` - '0|1' - sets the consent_flag to 0 or 1.
* `consent_not_required` - '0|1' - sets the consent_not_required flag to 0 or 1.
* `consent_source` - 'string' 
  * example: 'client', see above discussion about `source` for more details.

am_set_info.php is used to insert a new record into the `consent` table, but only if all four of these additional parameters are present. If one is not present, the `consent` table will not be modified. However, the RPC will not return a failure. This is to ensure backwards compatibility. If all four parameters above are set, as below, then the RPC will insert a new entry into the `consent` table.

The design of am_set_info is to fully manage the consent on behalf of a user at a remote source, i.e., an AM. The AM must understand what these fields are and how to set them.

Example:
{{{
am_set_info.php?account_key=ASDF&consent_name=ENROLL&consent_flag=1&consent_not_required=0&consent_source=accountmanager
}}}

The RPC is attempting to set the consent information for a `consent_name` of ENROLL. It will check of consent_name ENROLL exists. If it does not an error message will be returned.

=== Web site ===

The Web site account registration page will have a new panel that includes the terms of use text. This will be the same text file as [wiki:TermsOfUse]. The text file is processed with PHP's `nl2br()` function in order to format the plain text into text that is readable in HTML. Admins should **not** put HTML tags into the plain text [wiki:TermsOfUse] file. (In the future, we hope to make this HTML compatible.)

The registration page will have an additional checkbox that requires a user agree to the terms of use. If this is not checked, the account will not be created, and an error shown to the user. Only when the checkbox is checked, will an account be created. A new record will be inserted into the `consent` table, in the same manner as the create_account RPC.

=== OPS pages ===

In the ops pages, there is a new 'Manage Consent types' page. Here the admins may add additional consent types, enable/disable them, and set whether or not the consent type should appear in the privacy preferences. Admins may **not** delete consent types. Howveer, admins may disable consent types that are no longer used. Technically, this is because the consent_type_id is a foreign key in the consent table, and deleting the consent type involves removing rows from the consent table. Since we do not want to delete rows in the consent table to preserve any audit trail that may be legally necessary, deleting consent types is not supported in the OPS pages.

=== Anonymous Accounts ===

There may be cases where a user uses an Account Manager (AM) which has the feature of anonymous accounts. Effectively the user agrees to the AM terms-of-use. They do no see or agree to the projects terms-of-use. It is these cases where the `consent_not_required` flag is set in the `consent` table. However, it should be said that there is no 100% anonymity. Users' IP addresses are nearly always logged by the Web site server, and could be traced back to a user's account.

To use this functionality, the create_account RPC is called with `consent_flag=0`.

= Usage =

From a project administrator's point-of-view. To enable the Opt-in feature:

== Consent to Terms-of-Use ==

1. First in the OPS pages, go to "Manage consent types". All consent types are disabled by default. You should enable `ENROLL` and `STATSEXPORT`, the two default consent types.
1. You must add a `terms_of_use.txt` text file in the root of the project directory. This is the same directory `config.xml` may be found. This file must have the exact filename `terms_of_use.txt`, with underscores. It contains your projects terms-of-use text. See TermsOfUse.
1. `config.xml` must be updated: add XML `<enable_login_mustagree_termsofuse>1</enable_login_mustagree_termsofuse>` to the `<config>` section.
  * Note: If this config option is **not** set but the other two above it **are set**, the behavior of the site will be as follows. New accounts, whether created from the BOINC client or the Web site, will see a terms-of-use dialog which the user must agree to. However, existing accounts, when they login, are not asked to agree to a terms-of-use.
1. In the web project config file: `html/project/project.inc`, add: `define("TERMSOFUSE_FILE", "../../terms_of_use.txt");`.
1. You may optionally enforce that account creation requests via RPC (i.e. by the BOINC client or an account manager) have to state the user's prior consent to the terms of use by enabling `account_creation_rpc_require_consent` in `config.xml`. Please note that this requires the latest BOINC client and server releaeses to work:
  * BOINC client version: TBA
  * BOINC server version: TBA

== Consent to statistics exports ==

How `STATSEXPORT` affects `db_dump`. If the `STATSEXPORT` consent_type is **enabled** in the OPS pages, users will be able to select whether they consent to having their statistics exported. This option is **false** by default. This option is found in the project preferences page, example: `https://projectURL/prefs.php?subset=project`. This option is also **false** by default.

Only if a user has consented to this `STATSEXPORT`, then `db_dump` will include their user account and their hosts in the anonymous statistics created: specifically the `host` and `user` XML output. However, the total aggregate number of number of users, hosts, and the total credit will include all (non-deleted) users and hosts, ignoring the STATSEXPORT consetnt type.

== Project-specific consent types ==

On the manage consent type OPS pages, you may add your own project-specific consent types. However, you must provide any custom code that **uses** this consent type.