Fixed markdown

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