mirror of
https://github.com/Drop-OSS/drop.git
synced 2025-11-13 16:22:39 +10:00
32 lines
1.7 KiB
Markdown
32 lines
1.7 KiB
Markdown
# Client Handshake process
|
|
|
|
Drop clients need to complete a handshake in order to connect to a Drop server. It also trades certificates for encrypted P2P connections.
|
|
|
|
## 1. Client requests a handshake
|
|
|
|
Client makes request: `POST /api/v1/client/auth/initiate` with information about the client.
|
|
|
|
Server responds with a URL to send the user to. It generates a device ID, which has all the metadata attached.
|
|
|
|
## 2. User signs in
|
|
|
|
Client sends user to the provided URL (in external browser). User signs in using the existing authentication stack.
|
|
|
|
Server sends redirect to `drop://handshake/[id]/[token]`, where the token is an authentication token to generate the necessary certificates, and the ID is the client ID as generated by the server.
|
|
|
|
## 3. Client requests certificates
|
|
|
|
Client makes request: `POST /api/v1/client/auth/handshake` with the token recieved in the previous step.
|
|
|
|
The server uses it's CA to generate a public-private key pair, the CN of the client ID. It then sends that pair, plus the CA's public key, to the client, which stores it all.
|
|
|
|
_The certificate lasts for a year, and is rotated when it has 3 months or less left on it's expiry._
|
|
|
|
## 4.a Client requests one-time device endpoint
|
|
|
|
The client uses a millisecond UNIX timestamp and signs it with their private key. This is then attached to any device-related request. It has 30 seconds to make the request before the nonce becomes invalid (this is to prevent credential stealing & reusing).
|
|
|
|
## 4.b Client wants a long-lived session
|
|
|
|
The client does the same as above, but instead makes the request to `POST /api/v1/client/auth/session`, which generates a session token that lasts for a day. This can then be used in the request to provide authentication.
|