From a429350ff7ef8775b8412c86af56e19c93678048 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Thu, 25 Apr 2024 08:39:49 +0200 Subject: [PATCH 1/9] A few sentences about how agama deals with security --- doc/agama-security.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 doc/agama-security.md diff --git a/doc/agama-security.md b/doc/agama-security.md new file mode 100644 index 0000000000..3a15f69b26 --- /dev/null +++ b/doc/agama-security.md @@ -0,0 +1,34 @@ +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 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. + +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 +--- + +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 +-------------------------------------------------- + +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 +------------------ + +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 From 30c1f0afb1f7b8a2a82e0c91345533ed22a32fdb Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Thu, 25 Apr 2024 19:44:22 +0200 Subject: [PATCH 2/9] Fixed style issues --- doc/agama-security.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index 3a15f69b26..b277136f7d 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -8,7 +8,7 @@ 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. -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. +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 --- @@ -18,12 +18,12 @@ The token carries just one claim - the expiration date. Token's lifetime is curr 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. +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 ------------------ -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). +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 ... From c3fa6058b00fce0fffad6a828313b5ecde5c0a85 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Thu, 25 Apr 2024 19:52:23 +0200 Subject: [PATCH 3/9] 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 From c1016ee1b03bafe4bf0b626584ee604b50cb0a98 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Thu, 25 Apr 2024 19:57:58 +0200 Subject: [PATCH 4/9] Removed leftover(s) --- doc/agama-security.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index 9fb92988df..56b93a31b1 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -20,8 +20,6 @@ If both components run locally, communication can be done over HTTP even HTTPS. 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 ... - ## Links to external sources - [1] Rust pam crate, https://crates.io/crates/pam From e9e61bffddd6db3f8dcc3d04ae6bb4625722642c Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Fri, 26 Apr 2024 09:47:09 +0200 Subject: [PATCH 5/9] Provided some more technical details. --- doc/agama-security.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index 56b93a31b1..7e863fb8c1 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -1,16 +1,18 @@ ## 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. +Agama's functionality is divided into backend and frontend. Communication between two parts is done through HTTP/JSON and/or websocket. Most of the api requires an authorization. + +As frontend Agama offers web based UI or CLI. Backend currently is bunch of services implemented in Rust or Ruby with support from YaST libraries. For interprocess communication Agama uses D-Bus. ### 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 [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. +To make local use (frontend and backend running on same machine) with respect to agama-live use case more user friendly and allow skipping login in web UI Agama implements option ```--generate-token```. When this option is used, Agama's web server service generates valid JWT automatically on start. The token is stored locally [4] and then imported into web browser's internal database by Agama provided startup [5]. The script prepares custom profile with predefined homepage pointing to Agama's login page with the generated token as get parameter in the homepage url. Then the firefox browser is started in kiosk mode. ### 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. +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 [6] 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 @@ -25,4 +27,6 @@ SSL communication is secured either by self-signed certificate which is automati - [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 +- [4] Backend's machine at /run/agama/token +- [5] Agama's git repo - live/root/.icewm/startup +- [6] Rust rand crate, https://crates.io/crates/rand From 9e85be82026f416d0b0a3e149d0fc537f8c75b23 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Fri, 26 Apr 2024 10:01:29 +0200 Subject: [PATCH 6/9] Note about websocket --- doc/agama-security.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/agama-security.md b/doc/agama-security.md index 7e863fb8c1..6b749878a4 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -18,6 +18,8 @@ The token carries just one claim - the expiration date. Token's lifetime is curr 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. +For notifications on changes from backend Agama uses WebSocket technology. Typically backend notificates about installation progress or network configuration changes this way. + ### 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). From 2500a747db07fa80fcc9eb7df2b5c3548494151b Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Fri, 26 Apr 2024 10:37:18 +0200 Subject: [PATCH 7/9] Minor rephrasing --- doc/agama-security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index 6b749878a4..ebacff53a9 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -6,9 +6,9 @@ As frontend Agama offers web based UI or CLI. Backend currently is bunch of serv ### 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 [2] as authorization token [3]. All subsequent calls to the API has to be done together with the token. +Authorization is done via password. To get authorized frontend has to provide a root password (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. In case of web UI the token is stored in session cookie. -To make local use (frontend and backend running on same machine) with respect to agama-live use case more user friendly and allow skipping login in web UI Agama implements option ```--generate-token```. When this option is used, Agama's web server service generates valid JWT automatically on start. The token is stored locally [4] and then imported into web browser's internal database by Agama provided startup [5]. The script prepares custom profile with predefined homepage pointing to Agama's login page with the generated token as get parameter in the homepage url. Then the firefox browser is started in kiosk mode. +To make local use (frontend and backend running on same machine) with respect to agama-live use case more friendly and allow skipping explicit login in web UI Agama implements option ```--generate-token```. When this option is used, Agama's web server service generates valid JWT automatically on start. The token is stored locally [4] and then imported into web browser's internal database by Agama provided startup [5]. The script prepares custom profile with predefined homepage pointing to Agama's login page with the generated token as get parameter in the homepage url. Then the firefox browser is started in kiosk mode. ### JWT From 0ff3d1ef45597c8ed0d535d2610917585063e899 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Mon, 29 Apr 2024 09:22:09 +0200 Subject: [PATCH 8/9] Some more suggestions from the review --- doc/agama-security.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index ebacff53a9..03da9df1c1 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -2,25 +2,25 @@ Agama's functionality is divided into backend and frontend. Communication between two parts is done through HTTP/JSON and/or websocket. Most of the api requires an authorization. -As frontend Agama offers web based UI or CLI. Backend currently is bunch of services implemented in Rust or Ruby with support from YaST libraries. For interprocess communication Agama uses D-Bus. +As frontend Agama offers a web based user interface (web UI) or a commandline interface (CLI). Backend currently is bunch of services implemented in Rust or Ruby with support from YaST libraries. For interprocess communication Agama uses D-Bus. ### Authorization -Authorization is done via password. To get authorized frontend has to provide a root password (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. In case of web UI the token is stored in session cookie. +Authorization is done via password. To get authorized the frontend has to provide the root password (root on the backend's system). The password is validated through PAM [1]. Once the authorization succeeds, the backend generates an authorization token and passes it back to frontend. Agama uses [JSON Web Token (JWT)] [2] as authorization token [3]. All subsequent calls to the API has to be done together with the token. In case of the web UI, the token is stored in a HTTP-only cookie. -To make local use (frontend and backend running on same machine) with respect to agama-live use case more friendly and allow skipping explicit login in web UI Agama implements option ```--generate-token```. When this option is used, Agama's web server service generates valid JWT automatically on start. The token is stored locally [4] and then imported into web browser's internal database by Agama provided startup [5]. The script prepares custom profile with predefined homepage pointing to Agama's login page with the generated token as get parameter in the homepage url. Then the firefox browser is started in kiosk mode. +Agama supports special use case when Agama's UI or CLI is used in live installation media. In such case skipping autorization is supported to get feeling of using a desktop application. However, skipping authorization happens only for local access. When connecting remotely, authorization is still in place. Skipping of authorization is made possible thanks to option ```--generate-token```. When this option is used, Agama's web server service generates valid JWT automatically on start. The token is stored locally [4]. To make it usable for web UI, token is imported into web browser's internal database by Agama provided startup [5] script. The script prepares custom profile for Firefox with predefined homepage pointing to Agama's special login page with the generated token as part of a get request in the homepage url. As part of the response, the token is stored as `httpOnly` cookie. In case of CLI the situation is way easier as the token can be accessed and used directly as needed from well known location [4]. ### 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 [6] 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. +The token carries just one claim - the expiration date. Token's lifetime is currently set to one day. The token is provided in encrypted form. Security key is either automatically created random string [6] which is 30 characters long. However, security can be provided via the `jwt_secret` option in the `/etc/agama.d/server.yaml` agama's configuration file. The content of this option is expected to be a string but no checks are done. ### 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. +If both components run locally, communication can be done over HTTP or HTTPS. However, in case when both run on different machines, 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. For notifications on changes from backend Agama uses WebSocket technology. Typically backend notificates about installation progress or network configuration changes this way. -### 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). @@ -30,5 +30,5 @@ SSL communication is secured either by self-signed certificate which is automati - [2] RFC 7519, http://jwt.io - [3] Rust jsonwebtoken crate, https://crates.io/crates/jsonwebtoken - [4] Backend's machine at /run/agama/token -- [5] Agama's git repo - live/root/.icewm/startup +- [5] [Firefox startup script] See Agama's git repository path - live/root/.icewm/startup - [6] Rust rand crate, https://crates.io/crates/rand From 25552ae3a2fd4ea5d93f544edd79c86e02a0ca26 Mon Sep 17 00:00:00 2001 From: Michal Filka Date: Mon, 29 Apr 2024 11:44:23 +0200 Subject: [PATCH 9/9] Minor tweaks in references --- doc/agama-security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/agama-security.md b/doc/agama-security.md index 03da9df1c1..2e33326e1d 100644 --- a/doc/agama-security.md +++ b/doc/agama-security.md @@ -26,9 +26,9 @@ SSL communication is secured either by self-signed certificate which is automati ## Links to external sources -- [1] Rust pam crate, https://crates.io/crates/pam +- [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] Backend's machine at /run/agama/token -- [5] [Firefox startup script] See Agama's git repository path - live/root/.icewm/startup +- [5] [Firefox startup script] See https://github.com/openSUSE/agama/blob/master/live/root/root/.icewm/startup - [6] Rust rand crate, https://crates.io/crates/rand