sio-2425/delivery3/report.adoc

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

:toc: macro
:toclevels: 3
:doctype: article
:source-highlighter: highlightjs
:icons: font
:sectnums:
:sectlinks:
:!last-update-label:

<<<

== 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_endpoints,Anonymous>>: No authentication required.
* <<_authenticated_endpoints,Authenticated>>: Authentication required.
* <<_authorized_endpoints,Authorized>>: Authentication and permissions required.

[[_anonymous_endpoints]]
=== Anonymous Endpoints

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

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

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

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

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

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

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

a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `signature`: Signature of the challenge using the private key.
| N/A

|===

[[_authenticated_endpoints]]
=== Authenticated Endpoints

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

a| `GET /user/list` → Returns a list of all users
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
| N/A
a| * `username`: Filter by username.

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

a| `GET /file/list` → Returns a list of all files.
a| * `Content-Type: application/octet-stream`
* `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)

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

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

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

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

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

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

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

|===

[[_authorized_endpoints]]
=== Authorized Endpoints

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

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

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

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

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

a| `POST /file/upload/content` → Uploads a file's content.
a| * `Authorization: token`
* `Content-Type: multipart/form-data`
a| * file's content as request data
| DOC_NEW

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

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

a| `POST /file/acl` → Updates the ACL of a file.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `document_handle`: Document handle.
* `role`: Role name.
* `perm`: Permission name.
* `operation`: `add` \| `remove`. (One of the following: add, remove)
| DOC_ACL

a| `POST /role/create` → Creates a new role.
a| * `Content-Type: application/octet-stream`
* `Authorization: token`
a| * `role`: Role name.
| ROLE_NEW

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

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

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

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

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

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

|===

== 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.

== Analysis

For the analysis section, the project will be evaluated under the scope of the V3 (Session Management) chapter of the OWASP ASVS. This will include an assessment of the session management mechanisms implemented, as well as any vulnerabilities identified and possible mitigations.

=== Session Management

==== Fundamental Session Management Security

==== Session Binding

==== Session Termination

==== Cookie-based Session Management

==== Token-based Session Management

==== Federated Re-authentication

==== Defenses Against Session Management Exploits

== Results and Conclusions

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