diff --git a/doc/Authentication.md b/doc/Authentication.md new file mode 100644 index 0000000000000000000000000000000000000000..a7e424b4c321156a009d8a7d9631f32dd296ce1a --- /dev/null +++ b/doc/Authentication.md @@ -0,0 +1,81 @@ + + +Author: Timm Fitschen + +Email: timm.fitschen@ds.mpg.de + +Date: Older than 2016 + + Some features of CaosDB are available to registered users only. Making any changes to the data stock via HTTP requires authentication by `username` _plus_ `password`. They are to be send as a HTTP header, while the password is to be hashed by the sha512 algorithm: + +| `username:` | `$username` | +|-------------|-------------|- +| `password:` | `$SHA512ed_password` | + + +# Sessions + +## Login + +### Request Challenge + + * `GET http://host:port/login?username=$username` + * `GET http://host:port/login` with `username` header + +*no password required to be sent over http* + +The request returns an AuthToken with a login challenge as a cookie. The AuthToken is a dictionary of the following form: + + + {scope=$scope; + mode=LOGIN; + offerer=$offerer; + auth=$auth + expires=$expires; + date=$date; + hash=$hash; + session=$session; + } + + $scope:: A uri pattern string. Example: ` {**/*} ` + $mode:: `ONETIME`, `SESSION`, or `LOGIN` + $offerer:: A valid username + $auth:: A valid username + $expires:: A `YYYY-MM-DD HH:mm:ss[.nnnn]` date string + $date:: A `YYYY-MM-DD HH:mm:ss[.nnnn]` date string + $hash:: A string + $session:: A string + +The challenge is solved by concatenating the `$hash` string and the user's `$password` string and calculating the sha512 hash of both. Pseudo code: + + + $solution = sha512($hash + sha512($password)) + +### Send Solution + +The old $hash string in the cookie has to be replaces by $solution and the cookie is to be send with the next request: + +`PUT http://host:port/login` + +The server will return the user's entity in the HTTP body, e.g. + + + <Response ...> + <User name="$username" ...> + ... + </User> + </Response> + +and a new AuthToken with `$mode=SESSION` and a new expiration date and so on. This AuthToken cookie is to be send with every request. + +### Logout + +Send + +`PUT http://host:port/logout` + +with a valid AuthToken cookie. No new AuthToken will be returned and no AuthToken with that `$session` will be accepted anymore. + + + +