メインコンテンツまでスキップ

ZTXBAS API の HMAC リクエスト署名

すべての /v1/* リクエストはアプリケーションのシークレットを用いた HMAC-SHA256 で署名します。SDK はこの処理を代行します。手動で署名する場合や別言語で実装する場合に参照してください。

4 つのヘッダー​

ヘッダー値
X-Application-IDztxbas app create で発行されたアプリケーション ID
X-TimestampUnix 時刻（秒）。サーバー時刻の ±300 秒以内
X-Nonceリクエストごとのランダム文字列。32 桁の 16 進文字列でも可
X-Signaturehex(HMAC-SHA256(secret, canonical))

正規化形式​

正規化文字列は 1 行で、末尾に改行を付けません。

  • METHOD：GET、POST、DELETE 等の大文字の HTTP メソッド。
  • PATH：先頭が / の正確な URL パス。クエリ文字列は含みません。
  • TIMESTAMP：X-Timestamp と同じ値。
  • NONCE：X-Nonce と同じ値。
  • BODY：送信する本文の生バイト列。本文のない GET/DELETE は空文字列です。署名後に JSON を整形し直してはいけません。
METHOD "|" PATH "|" TIMESTAMP "|" NONCE "|" BODY

実例​

{"email":"alice@example.com"} を本文とする POST /v1/users の署名例です。SDK はこの既知のテストベクターを使って検証されています。新しい言語で署名を実装する場合にも同じ値で検証してください。

canonical = 'POST|/v1/users|1704067200|abc123|{"email":"alice@example.com"}'
signature = hex(HMAC-SHA256("topsecret", canonical))
          = 92c2aca00ba47b4377aebf3e3af134aff93cf7ad959d05e31a0f0618df9f7d9a
POST /v1/users HTTP/1.1
Host: ztxbas.example.com
X-Application-ID: app_test
X-Timestamp: 1704067200
X-Nonce: abc123
X-Signature: 92c2aca00ba47b4377aebf3e3af134aff93cf7ad959d05e31a0f0618df9f7d9a
Content-Type: application/json

{"email":"alice@example.com"}

セキュリティ上の注意​

  • シークレットは秘密鍵と同等に保護し、ファイル権限を 0600 に設定します。
  • 独自の検証実装では定数時間比較を使用します。サーバーは Go の crypto/subtle.ConstantTimeCompare を使用します。
  • 本文上限は 8 KiB。超過すると 413 BODY_TOO_LARGE が返ります。
  • 時刻ずれ許容は ±300 秒。TIMESTAMP_EXPIRED が発生する場合は NTP を確認します。
  • v1 ではノンスの再利用をサーバー側で強制的に拒否しません。 リプレイ境界はタイムスタンプの許容範囲です。それでも毎回新しいランダムノンスを生成してください。

関連資料​