create-user.tex

% !TEX root = Documentation.tex

\label{create-user.php}
\section{create-user.php}
The create-user.php site offers the opportunity to create a new user and to set the right for this specific user. User creation follows the idea of dropping rights, 
which only allows a user to create another user with less rights than he has himself. To ensure this, create-user.php is just visible to users with a role, higher than student.
This includes the following roles: admin [role code: 4], professor [role code: 3], scientific coworker [role code: 2]. \\
Furthermore only professors and admins are allowed to create users at a different institution, scientific coworker are only allowed to create users at the 
same institution as they are. In the same way, the erasing of users is limited to professors and admin users.
\paragraph{Create a new user}
Creating a user leads to modifications in the Dim\_User table and the authentication database. This database updates are proceeded, if the user clicks on 
the ``create user'' button, which calls the ``create\_user\_script.php'' file to process the form data and insert them into the database.
\paragraph{Create new institution}
The creation of new institution is also limited to people logged in as professors and admin. Each department is created separetely, even if an institution owns several departments, 
taking part in the 2Org-Cows project. This improves the adjustability of rights sticked to the specific department in case of splitted user rights on certain datasets.
The data inserted for the creation of an institution are processed by the create\_institution\_script.php file.
\paragraph{Delete user}
Furthermore, the create-user.php allows the deletion of existing users. This is limited to users with the role code 4 and 3 (admin and professor), therefore the form is just visible 
to users of that role. To prevent accidental deletions, a separate checkbox has to be checked, to delete a user. User deletion is limited to users from the same institution and exclude 
the current user. The deletion of the user is proceeded by the delete\_user\_script.php .
\paragraph{Update password}
To allow users, who forgot their password, to regain access to their accounts, users with higher roles can set the password for users in their institution. 
As there is, up till now, no further security in the password updates, these actions are limited to high profile users. In case it might be necessary, further protection mechanisms to the 
password updates, such as requesting a secret, etc. could be implemented. The password updates are processed by the set-password.php script.
\paragraph{Grant rights}
As the data in the database are bound to specific groups, the rights management on the group level has to be performed with the administration aswell. Therefore, all departments are 
retrieved from the database and listed in a table. To improve the overview to the departments, the table is splitted into institutions and departments. Finally, the table includes 
one checkbox per department, which sets a value in the corresponding table. The table also shows with the checkboxes, which departments are granted access rights to the data tables 
of the institution invoked. As all permissions are stored in a translation table in the database, an own script updates this table 
and sets the value for the access on the data.
\paragraph{CSRF protection}
As there are multiple forms on one page, the csrf protection tokens are applied as split calculation tokens. In this case, the \$\_SESSION token just contains an random number, generated with 
\texttt{uniqid()}. For the hidden input field, this number is part of the input for an SHA256 hash calculation with \texttt{hash\_hmac()}, where a string and the number from the \$\_SESSION variable are 
the input. The same operation takes place in all the scripts, the output is then compared to the submitted \$\_POST variable, using \texttt{strcmp()}.

\subsection{create\_user\_script.php}
The create\_user\_script.php is the processing file for the entries to create a new user in the web interface for the database. Basically the script just performs the validity checks 
of the form data provided in create-user.php and an \textbf{INSERT} query to the MySQL database.\\
At the beginning the script checks whether the provided check bytes submitted in create-user.php match those from the session. Again this is a CSRF-protection in case the session has
been hijacked. If there are no problems on the CSRF protection, the script checks for the validity of the form provided. This part already takes place in the html, where the tag 
``required'' is set for all fields, but a controll in the script should avoid empty fields in the database.
\paragraph{Type checking of entries}
For the validity checks the following steps are taken:
\begin{itemize}
 \item validity check of the e-mail adress provided
 \item check whether the desired username is available
 \item check, whether the password matches matches the control field
 \item check whether the user permissions, entered in the form, are allowed to be performed by the user invoked
 \item check whether the user invoked is allowed to select an institution different from his own
 \item check whether the entered permissions are met by the other data entered into the database, such as check, if a user role is possible or if a group exists.
\end{itemize}
All manual input on free text fields, such as the username, etc. is not checked again by the script and taken for true and granted. During the script, only one value is changed 
automatically, which is the username, as it is set to a small letter string.
\paragraph{Data gathering from different tables}
If any of these checks fails, the user receives an error notice and is directed to the form.As the group, department and the country entries are stored in a different
way in the database, than in the user session, the database values have to be retrieved from the database. Therefore, the corresponding institution, department and country are 
queried from the Dim\_Group table. As the country is stored as an integer value, the corresponding ID\_Country has to be queried from the Dim\_Country in the next step.\\
The passwords are stored as bcrypt hash values in a separate database, the hashing is performed after the validity checks for the form. 
\paragraph{Data insertion}
The next step is to insert all data into the 
Dim\_User table in the agri\_star\_001 database. During this step the ID\_User value, which identifies the user during further operation, is set as the resulting auto-increment 
value for the primary key from the database. To allow sufficiently large user amounts, the ID\_User field is of the type BIGINT. 
The insert is proceeded in an objective style, generating the query first, then assigning the values to the query (\texttt{mysqli::prepare(\$query)}, \texttt{mysqli::bind\_param(parameters)}) and 
than executing the query (\texttt{mysqli::execute}). 
The transaction id of that insert is retrieved, as it is used as ID\_User, to map the data in the auth database to the corresponding user. 
In the next step the username, the password hash and the ID\_User are inserted into the auth database, using the same process as for the Dim\_User table.\\
The scripts quits with a success message.

\label{create_institution_script.php}
\subsection{create\_institution\_script.php}
The create\_institution\_script.php is the processing script for the entries in the institution form. Again it is basically an \textbf{INSERT} query to the database, where no 
external have to be retrieved from other tables in the database. 
\paragraph{Type checking} The only type checking for an input field, being performed by the create\_institution\_script.php, is the check 
of the provided e-mail address. This check just checks for the basic match with e-mail regulations. Furthermore, a logical check is performed on the selected country, where the 
script checks, whether the selected country exists in the database. In all other cases, the user input is not checked again by the script and taken for granted and true. 
If all fields are filled, the provided data is put into the Dim\_Group table in the database, using a similar method as for the users.
\paragraph{Rights management} To allow groupwise right grants, a separate table with all institutions in the Dim\_Group keeps track of the granted rights. Therefore, it is important to create 
connections between all groups created during the project. In order to do this, the transaction ID is retrieved from the database and all other ID\_Group values are queried from the database. Than 
these values are written into the grants table, where one column is the giving group and another column is the receiving group. \\
Finally the script quits with a success message.

\subsection{delete\_user\_script.php}
The deletion of a user does not lead to all his data being wiped out of the Dim\_User and the auth table, instead the user is simply kept from successfully logging into the frontend. 
Therefore, the password in the auth table is updated to a cryptographically save binary string. Furthermore, the column user\_not\_active in the Dim\_User table is set to 1, which 
does not show the user in any active state anymore. The script exits with a success message and refers to the create-user.php page.

\subsection{set-password.php}
In case a user has forgotten his password, these can be resetted by a user with a role higher than 2 (professor and admin). As there is no further checking, whether the user taking the action is 
allowed to set the password, this is type of a trust system, which should exist in the institution taking part in the project.
The set-password.php script does the following steps:
\begin{itemize}
\item check if the two password fields match
\item hashing the password, using the bcrypt standard with 12 rounds, to increase calculation requirements for password cracking
\item saving the password hash to the auth database
\end{itemize}
If all entries are fine, the script quits successfully and refers to the create-user.php page again.

\subsection{grant-rights.php}
The permissions administration in the rights table is written with the grant-rights.php into the database. Unlike the former scripts, which basically performed an INSERT query on 
the database, the grant-rights.php first checks, whether an entry corresponding to the two mentioned groups exists in the grants table. This just occurs, if the user has chosen 
a group, with which he wants to share data. Otherwise, nothing happens to the table and not selected groups are neither inserted nor updated. In case the entry with the two groups 
does not exist both ID\_Group values and the value for data access (1) are written into the database.\\
If the matching of both groups already exists, as it was created during a group creation, the script just updates the access value to one.\\
To withdraw rights from existing groups, the corresponding checkboxes on the admin page have to be unchecked. As the content of the checkboxes is transmitted as an array, containing all group numbers 
delivered by checking the checkboxes, the grant-rights.php script can check for the existance of all shown groups in the array. If an ID\_Group value does not come up in the array, the connected 
checkbox has either not been checked or has been unchecked.\\
As the first step, the script gathers all groups, to which the current user's group has granted rights, from the database, where entries to these groups must exist, as they have been at least 
created during the rights permission process. In the loop to create the array from the database results, the script performs a check, if the currently processed group comes up in the checkbox array 
from the script. If the ID\_Group value does not come up the checkbox array, an SQL query is executed to replace the value for data access (1) with a 0. Otherwise, the loop ends, when the array has 
been completely parsed.\\ 
Then the scripts exits with a success message, but does not indicate, which results have been achieved. This can easily be done by checking the checkboxes, which show the current right status for 
other groups.