From c3fa6058b00fce0fffad6a828313b5ecde5c0a85 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Thu, 25 Apr 2024 19:52:23 +0200 Subject: [PATCH] Fixed markdown --- doc/agama-security.md | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index b277136f7d..9fb92988df 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -1,34 +1,30 @@ -Agama Concepts -============== +## Agama Concepts Agama's functionality is divided into backend and frontend. Communication between two parts is done through REST api. Most of the api requires an authorization. -Authorization -------------- +### Authorization -Authorization is done via password. To get authorized user is asked for a password of root on backend's machine. The password is validated through PAM [1]. Once the authorization succeeds, backend generates an authorization token and passes it back to frontend / user. Agama uses JWT as authorization token [2]. All subsequent calls to the API has to be done together with the token. +Authorization is done via password. To get authorized user is asked for a password of root on backend's machine. The password is validated through PAM [1]. Once the authorization succeeds, backend generates an authorization token and passes it back to frontend / user. Agama uses JWT [2] as authorization token [3]. All subsequent calls to the API has to be done together with the token. To make local use (frontend and backend running on same machine) a bit easier Agama implements option ```--generate-token```. When this option is used, Agama-web-server generates valid JWT automatically on start. The token is pushed into web browser's cache by Agama. -JWT ---- +### JWT The token carries just one claim - the expiration date. Token's lifetime is currently set to one day. The token is provided in an encrypted form. Security key is either automatically created random string [3] of length at least 30 characters. However, security key can be provided via ```/etc/agama.d/server.yaml``` using ```jwt_secret``` option. Content of this option is expected to be a string but no checks are done. -Communication between the frontend and the backend --------------------------------------------------- +### Communication between the frontend and the backend If both components run locally, communication can be done over HTTP even HTTPS. However, in case when both run on different machines the HTTPS is mandatory. In such case all HTTP requests are automatically redirected to HTTPS. A HTTP response with code 308 (permanent redirect) is returned in such case. -Https certificates ------------------- +### Https certificates SSL communication is secured either by self-signed certificate which is automatically generated by Agama if no certificate was provided by user. If Agama should use particular custom certificate Agama's web server provides options --cert and --key for path to certificate respectively to private key (in PEM format). ... TBD ... -External Projects in use -======================== -[1] Rust pam crate -[2] Rust jsonwebtoken crate -[3] Rust rand crate +## Links to external sources + +- [1] Rust pam crate, https://crates.io/crates/pam +- [2] RFC 7519, http://jwt.io +- [3] Rust jsonwebtoken crate, https://crates.io/crates/jsonwebtoken +- [4] Rust rand crate, https://crates.io/crates/rand