mirrors/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2025-05-12 22:26:08 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: run lint:fix

Browse source 
Signed-off-by: Philip Molares <philip.molares@udo.edu>
This commit is contained in:
Philip Molares 2023-07-06 02:45:32 +02:00
parent 366515e760
commit 50d4959e0a
21 changed files with 526 additions and 360 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/content/dev/design_docs/api_auth.md
View file

@ -6,7 +6,7 @@ feature. It is not a user guide and may or may not be fully implemented.
## Public API
All requests to the public API require authentication using a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750).
All requests to the public API require authentication using a [bearer token][bearer-token].
This token can be generated using the profile page in the frontend
(which in turn uses the private API to generate the token).
@ -14,27 +14,28 @@ This token can be generated using the profile page in the frontend
### Token generation
When a new token is requested via the private API, the backend generates a 64 bytes-long secret of
cryptographically secure data and returns it as a base64url-encoded string, along with an identifier.
That string can then be used by clients as a bearer token.
cryptographically secure data and returns it as a base64url-encoded string,
along with an identifier. That string can then be used by clients as a bearer token.
A SHA-512 hash of the secret is stored in the database. To validate tokens, the backend computes the hash of the provided
secret and checks it against the stored hash for the provided identifier.
A SHA-512 hash of the secret is stored in the database. To validate tokens, the backend computes
the hash of the providedsecret and checks it against the stored hash for the provided identifier.
#### Choosing a hash function
Unfortunately, there does not seem to be any explicit documentation about our exact use-case.
Most docs describe classic password-saving scenarios and recommend bcrypt, scrypt or argon2.
These hashing functions are slow to stop brute-force or dictionary attacks, which would expose the original,
user-provided password, that may have been reused across multiple services.
These hashing functions are slow to stop brute-force or dictionary attacks, which would expose
the original, user-provided password, that may have been reused across multiple services.
We have a very different scenario:
Our API tokens are 64 bytes of cryptographically strong pseudorandom data.
Brute-force or dictionary attacks are therefore virtually impossible, and tokens are not reused across multiple services.
Brute-force or dictionary attacks are therefore virtually impossible, and tokens are not
reused across multiple services.
We therefore need to only guard against one scenario:
An attacker gains read-only access to the database. Saving only hashes in the database prevents the attacker
from authenticating themselves as a user. The hash-function does not need to be very slow,
as the randomness of the original token prevents inverting the hash. The function actually needs to be reasonably fast,
as the hash must be computed on every request to the public API.
An attacker gains read-only access to the database. Saving only hashes in the database prevents the
attacker from authenticating themselves as a user. The hash-function does not need to be very slow,
as the randomness of the original token prevents inverting the hash. The function actually needs to
be reasonably fast, as the hash must be computed on every request to the public API.
SHA-512 (or alternatively SHA3) fits this use-case.
## Private API
@ -57,4 +58,7 @@ using one of the supported authentication methods:
- Google
The `SessionGuard`, which is added to each (appropriate) controller method of the private API,
checks if the provided session is still valid and provides the controller method with the correct user.
checks if the provided session is still valid and provides the controller method
with the correct user.
[bearer-token]: https://datatracker.ietf.org/doc/html/rfc6750