Tick サーバーは、ggguilds の APIキーで署名した JWT で利用者を確かめます。JWT は、ggguilds の「APIキーの使い方」にある標準の JWT に、nonce を足したものです。
クレーム
| 項目 | 値 |
|---|---|
ヘッダーの alg | EdDSA(Ed25519) |
iss | キー ID(ggg_...) |
aud | freqrelay(固定の値です) |
iat | 作った時刻(UNIX 時間の秒) |
exp | 期限(UNIX 時間の秒)。iat から 5 分以内 |
nonce | Challenge の cookie(16 バイト)を URL セーフ Base64(パディングなし)にした 22 文字 |
- JWT は、
Authenticateを送るたびに作り直してください。cookie が毎回変わるためです。 - Tick サーバーとの時刻のずれは ±60 秒まで許します。クライアントの時計は NTP などで合わせてください。
- JWT はコンパクト形式(ASCII)で、1,024 バイト以下にしてください。
Python の例
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, # キー ID(ggg_...)
"aud": "freqrelay",
"iat": now,
"exp": now + 300,
"nonce": base64.urlsafe_b64encode(cookie).rstrip(b"=").decode(), # Challenge の cookie
},
private_key,
algorithm="EdDSA",
)
JavaScript の例
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) // キー ID(ggg_...)
.setAudience("freqrelay")
.setIssuedAt()
.setExpirationTime("5m")
.sign(privateKey)
認証が拒否されたとき
AuthenticateAck の result で理由がわかります。主なものは次のとおりです。すべての値は結果と終了理由にあります。
| result | 確かめること |
|---|---|
InvalidSignature | キー ID と秘密鍵の組み合わせが合っているか |
TokenExpired | クライアントの時計が合っているか。exp − iat が 5 分以内か |
UnknownKey | 発行した直後なら、1 分ほど待ってから再試行する |
IpLimitReached | ほかの IP アドレスでの接続をやめると、枠が空く |
送信元の確かめ方について
Hello から Challenge を受け取り、その cookie を JWT に入れて返す手順は、送信元のアドレスが本物であることを確かめるためのものです。cookie は送信元のアドレスと時間枠から作られるので、送信元を偽った要求では認証できません。
同じ理由で、Hello には 32 バイトの詰め物(すべて 0)を入れます。Hello を Challenge より大きくして、送信元を偽った要求で第三者に大きな応答が送られないようにしています。詰め物を省いた Hello には、Tick サーバーは応えません。