Package gpgchallenge provides a Client and a Server so that a Client can prove ownership of an IP address by solving a GPG challenge sent by the Server at the claimed IP. The protocol is as follows:
- The Client GETs a random token from the server, at the /token endpoint, and signs that token with its GPG private key (armor detached signature).
- When it is ready[*], the client POSTs an application/x-www-form-urlencoded over HTTPS to the server, at the /claim endpoint. It sends the following URL-encoded values as the request body: its armor encoded public key as "pubkey", the IP address it's claiming as "challengeIP", the token it got from the server as "token", and the signature for the token as "signature".
- The Server receives the claim. It verifies that the token (nonce) is indeed one that it had generated. It parses the client's public key. It verifies with that public key that the sent signature matches the token. The serve ACKs to the client.
- The Server generates a random token, and POSTs it to the challenged IP (over HTTPS, with certificate verification disabled) at the /challenge endpoint.
- The Client receives the random token, signs it (armored detached signature), and sends the signature as a reply.
- The Server receives the signed token and verifies it with the Client's public key.
- At this point, the challenge is successful, so the Server performs the action registered through the OnSuccess function.
- The Server sends a last message to the Client at the /ack endpoint, depending on the result of the OnSuccess action. "ACK" if it was successful, the error message otherwise.
[*]As the Server connects to the Client to challenge it, the Client must obviously have a way, which does not need to be described by the protocol, to listen to and accept these connections.