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

docs: Split up 2.0.md and rename to dev_notes.md

Browse source 
Signed-off-by: David Mehren <git@herrmehren.de>
This commit is contained in:
David Mehren 2023-03-12 21:42:39 +01:00
parent bec48f3c22
commit c278f6d78b
5 changed files with 67 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -6,6 +6,31 @@ All requests to the public API require authentication using a [bearer token](htt
This token can be generated using the profile page in the frontend
(which in turn uses the private API to generate the token).
### 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.
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.
#### 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.
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.
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.
SHA-512 (or alternatively SHA3) fits this use-case.
## Private API
The private API uses a session cookie to authenticate the user.