本文へ移動
QuantLabTickDirect

ドキュメント接続仕様

認証(JWT)

Authenticate で送る JWT の作り方です。

Tick サーバーは、ggguilds の APIキーで署名した JWT で利用者を確かめます。JWT は、ggguilds の「APIキーの使い方」にある標準の JWT に、nonce を足したものです。

クレーム

項目値
ヘッダーの algEdDSA(Ed25519)
issキー ID(ggg_...)
audfreqrelay(固定の値です)
iat作った時刻(UNIX 時間の秒)
exp期限(UNIX 時間の秒)。iat から 5 分以内
nonceChallenge の 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 サーバーは応えません。