The Tick server identifies you with a JWT signed with your ggguilds API key. The JWT is the standard JWT described in ggguilds' "Using API keys", with nonce added.
Claims
| Field | Value |
|---|---|
Header alg | EdDSA (Ed25519) |
iss | Key ID (ggg_...) |
aud | freqrelay (a fixed value) |
iat | When the token was created (UNIX time in seconds) |
exp | Expiry (UNIX time in seconds). Within 5 minutes of iat |
nonce | The cookie from Challenge (16 bytes) as URL-safe Base64 without padding (22 characters) |
- Create a new JWT every time you send
Authenticate, because the cookie changes each time. - A clock difference of up to ±60 seconds from the Tick server is allowed. Keep the client's clock in sync with NTP or similar.
- Send the JWT in compact form (ASCII), at most 1,024 bytes.
Python example
This uses PyJWT.
# pip install "pyjwt[crypto]"
import base64, time, jwt
with open("ggguilds-api-key.pem", "rb") as f:
private_key = f.read()
now = int(time.time())
token = jwt.encode(
{
"iss": key_id, # Key ID (ggg_...)
"aud": "freqrelay",
"iat": now,
"exp": now + 300,
"nonce": base64.urlsafe_b64encode(cookie).rstrip(b"=").decode(), # Cookie from Challenge
},
private_key,
algorithm="EdDSA",
)
JavaScript example
This uses jose.
// npm install jose
import { SignJWT, importPKCS8 } from "jose"
const privateKey = await importPKCS8(pem, "EdDSA")
const token = await new SignJWT({ nonce: Buffer.from(cookie).toString("base64url") })
.setProtectedHeader({ alg: "EdDSA" })
.setIssuer(keyId) // Key ID (ggg_...)
.setAudience("freqrelay")
.setIssuedAt()
.setExpirationTime("5m")
.sign(privateKey)
When authentication is rejected
The result in AuthenticateAck tells you why. The common ones are below. All values are in Result codes.
| result | What to check |
|---|---|
InvalidSignature | Whether the key ID and the private key belong together |
TokenExpired | Whether the client's clock is correct, and whether exp − iat is within 5 minutes |
UnknownKey | If you just issued the key, wait about a minute and retry |
IpLimitReached | Stopping a connection on another IP address frees a slot |
Why the source address is checked
Getting a Challenge in reply to Hello and returning its cookie in the JWT confirms that the source address is genuine. The cookie is derived from the source address and a time window, so a request with a spoofed source address cannot authenticate.
For the same reason, Hello carries 32 bytes of padding (all zeros). This makes Hello larger than Challenge, so that a request with a spoofed source address cannot make the server send a larger reply to a third party. The Tick server does not reply to a Hello without the padding.