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.