= SIO Project Report
Authors: Rúben Gomes (113435), João Bastos (113470), Tiago Garcia (114184)

{authors} - {docdate}

:toc: macro
:toclevels: 2
:doctype: article
:source-highlighter: highlightjs
:icons: font
:sectnums:
:sectlinks:

== Introduction

This document serves as the final report for the SIO-2425 project. This project serves as a way to demonstrate the practical application of some of the concepts learned throughout the course (Authentication, Access Control, Session Management and Stored Cryptography). On a analysis perspective, it will be focused on the V2 (Authentication) chapter of the OWASP ASVS.

This report will cover the features implemented, the decisions made as a group, as well as results and conclusions of the project.

== Features

The features of the project are the ones present in the course project description, but with an extra feature, the possibility to reset the database of the server. This was shown to be useful for testing purposes, but it should be disabled/deleted in a production environment.


The API has a list of endpoints that require different permission levels to access. Mainly, it's divided into 3 categories:

* Anonymous: No authentication required.
* Authenticated: Authentication required.
* Authorized: Authentication and permissions required.


=== Anonymous Endpoints

[cols="1,1,1,1", options="header"]
|===
| Endpoint | Required headers | Required payload fields | Optional payload parameters

| `GET /` → Returns a ping message.
| N/A
| N/A
| N/A

| `POST /reset` → Resets the database and deletes all data.
| `Content-Type: application/json`
a| * `password`: The reset password. *Note: The reset password is `123` (very secure!).*
| N/A

| `GET /org/list` → Returns a list of all organizations.
| N/A
| N/A
| N/A

| `POST /org/create` → Creates a new organization.
| `Content-Type: application/json`
a| * `name`: Organization name.
* `username`: Manager username.
* `full_name`: Manager full name.
* `email`: Manager email.
* `public_key`: Manager public key.
| N/A

| `GET /file/get/<file_handle>/content` → Downloads the file content.
| N/A
| N/A
| N/A

| `POST /user/login` → Logs in a user.
| `Content-Type: application/json`
a| * `org`: Organization name.
* `username`: User username.
* `password`: User password.
* `credentials_file`: User credentials file.
| N/A

|===

=== Authenticated Endpoints

[cols="1,1,1,1", options="header", source]
|===
| Endpoint | Required headers | Required payload fields | Optional payload parameters

| `GET /user/list` → Returns a list of all users
| `Authorization: token`
| N/A
a| * `username`: Filter by username.

| `GET /user/<username>/roles` → Returns a list of all roles of a user.
| `Authorization: token`
| N/A
| N/A

| `GET /file/list` → Returns a list of all files.
| `Authorization: token`
| N/A
a|
* `username`: Filter by username.
* `datetime`: Filter by datetime. The datetime filter has the following fields:
    ** `value`: Epoch time in seconds.
    ** `relation`: `ot` \| `eq` \| `nt`. (One of the following: older than, equal to, newer than)

| `POST /user/logout` → Logs out a user.
| `Authorization: token`
| N/A
| N/A

| `POST /role/session/assume` → Assumes a role in the session.
| `Authorization: token`
a| * `role`: Role name.
| N/A

| `POST /role/session/drop` → Drops a role from the session.
| `Authorization: token`
a| * `role`: Role name.
| N/A

| `GET /role/session/list` → Lists the roles for the session.
| `Authorization: token`
| N/A
| N/A

| `GET /role/<role>/list/users` → Lists the users for a role.
| `Authorization: token`
| N/A
| N/A

| `GET /role/<role>/list/perms` → Lists the permissions for a role.
| `Authorization: token`
| N/A
| N/A

| `GET /role/perm/<perm>/roles`: → Lists the roles with a permission.
| `Authorization: token`
| N/A
| N/A

|===

=== Authorized Endpoints

[cols="1,1,1,1", options="header", source]
|===
| Endpoint | Required headers | Required payload fields | Optional payload parameters

| `POST /user/create` → Creates a new user.
a| * `Authorization: token`
* `Content-Type: application/json`
a| * `username`: User's username.
* `name`: User's name.
* `email`: User's email.
* `public_key`: User's public key.
| N/A

| `POST /user/<username>/suspend` → Suspends a user.
| `Authorization: token`
| N/A
| N/A

| `POST /user/<username>/activate` → Activates a user.
| `Authorization: token`
| N/A
| N/A

| `POST /file/upload/metadata` → Uploads a file's metadata.
a| * `Authorization: token`
* `Content-Type: application/json`
a| * `document_name`: Document name.
* `key`: Document key.
* `alg`: Document algorithm.
| N/A

| `POST /file/upload/content` → Uploads a file's content.
a| * `Authorization: token`
* `Content-Type: multipart/form-data`
a| * `content`: File's content to upload.
| N/A

| `GET /file/get/<document_handle>/metadata` → Downloads a file's metadata.
| `Authorization: token`
| N/A
| N/A

| `POST /file/delete/<document_handle>` → Deletes a file.
| `Authorization: token`
| N/A
| N/A

| `POST /file/acl` → Updates the ACL of a file.
| `Authorization: token`
a| * `document_handle`: Document handle.
* `role`: Role name.
* `perm`: Permission name.
* `operation`: `add` \| `remove`. (One of the following: add, remove)
| N/A

| `POST /role/create` → Creates a new role.
| `Authorization: token`
a| * `role`: Role name.
| N/A

| `POST /role/<role>/suspend` → Suspends a role.
| `Authorization: token`
| N/A
| N/A

| `POST /role/<role>/activate` → Activates a role
| `Authorization: token`
| N/A
| N/A

| `POST /role/<role>/user/add/<username>` → Adds a user to a role.
| `Authorization: token`
| N/A
| N/A

| `POST /role/<role>/user/remove/<username>` → Removes a user from a role.
| `Authorization: token`
| N/A
| N/A

| `POST /role/<role>/perm/add/<perm>` → Adds a permission to a role.
| `Authorization: token`
| N/A
| N/A

| `POST /role/<role>/perm/remove/<perm>` → Removes a permission from a role.
| `Authorization: token`
| N/A
| N/A

|===

== Decisions

The methodology section will delineate the steps undertaken to achieve the project objectives, including the tools and technologies utilized, as well as any challenges encountered and the strategies employed to address them.

== Results and Conclusions

This section will present the outcomes of the project, including any data collected, analyses performed, and key findings.
